> For the complete documentation index, see [llms.txt](https://ai-security-docs.akto.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-security-docs.akto.io/akto-atlas-agentic-ai-security-for-employee-endpoints/endpoints-discovery-agents/ai-endpoint-shield.md).

# AI Endpoint Shield

## Overview

AI Endpoint Shield provides **runtime security** and auto-discovery of local MCP servers configured on your machine. It acts as a protective layer between the MCP client (e.g., Cursor, VS Code, Claude) and the MCP servers, requiring no changes to your setup.

## What is Agentic Endpoint Shield?

Endpoint Shield continuously monitors employee devices to identify and track:

* **AI Agents**: All deployed agents across web, desktop, and endpoint devices
* **MCP Servers**: Model Context Protocol server instances running locally or remotely
* **Device Information**: Complete device inventory with hardware IDs, usernames, and locations
* **Agent Activity**: Real-time heartbeat monitoring and deployment status
* **MCP Connections**: Server URLs, connection health, and last seen timestamps

## Features

* Continuous safety checks on all requests and responses to the MCP servers
* Automatic blocking of unsafe interactions (via standard JSON-RPC errors)
* Works out-of-the-box with popular MCP clients (Cursor, VS Code, Claude)
* Zero changes required in your MCP server

## Installation

* The application is provided as an installble package (.app, .deb, .exe)
* Please reach out to Akto Support to get your installer.
* Please refer to the [Manaul Setup](#manual-setup) section if you wish to run the tool without an installer.

## Auto-Detection

Akto AI Endpoint Shield automatically detects MCP client configurations:

* **Cursor** → Reads `~/.cursor/mcp.json`
* **Visual Studio Code** → Reads `.vscode/mcp.json` inside your workspace
* **Claude Desktop** → Reads Claude’s MCP config JSON

For each detected MCP server config:

1. The JSON file is parsed.
2. Each server entry is automatically wrapped with **Akto AI Endpoint Shield**.
3. Your MCP clients transparently run through the shield without requiring manual reconfiguration.

{% hint style="warning" %}
You don’t need to manually edit your MCP config files — the wrapper handles this for you.
{% endhint %}

<details>

<summary>Example — Cursor <code>mcp.json</code></summary>

**Original file (before wrapping):**

```json
{
  "mcpServers": {
    "chrome-devtools-mcp": {
      "command": "npx",
      "args": [
        "-y"
        "chrome-devtools-mcp@latest"
      ]
    }
  }
}
```

**Automatically wrapped file (after Akto AI Endpoint Shield):**

```json
{
  "mcpServers": {
    "chrome-devtools-mcp": {
      "command": "mcp-endpoint-shield",
      "args": [
        "stdio",
        "--name",
        "chrome-devtools-mcp",
        "--exec",
        "npx",
        "-y",
        "chrome-devtools-mcp@latest"
      ]
    }
  }
}
```

Here how the wrap looks in the code:

<figure><img src="https://2916937215-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRc4KTKGprZI2sPWKoaLe%2Fuploads%2Fgit-blob-a71682de7c1df47b6a5ea827fc2bf83af6fde9ff%2Fmcp_endpoint_shield_example.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

**What changed:**

* `mcp-endpoint-shield` is now the entry command.
* Original server command (`npx -y chrome-devtools-mcp@latest`) is passed through `--exec`.

</details>

## Manual Setup

Follow these steps to manually set up and run AI Endpoint Shield to protect your MCP servers.

### Prerequisites

* You have the `mcp-endpoint-shield` binary available
* You have an Akto API token
* uninstall AI Endpoint Shield if installed previously using installers

{% stepper %}
{% step %}
**Set Your API Token**

Set the `AKTO_API_TOKEN` environment variable:

```bash
export AKTO_API_TOKEN="your-actual-token-here"
```

**Make it permanent** (optional):

* For **bash** users, add to `~/.bashrc`:

  ```bash
  echo 'export AKTO_API_TOKEN="your-actual-token-here"' >> ~/.bashrc
  source ~/.bashrc
  ```
* For **zsh** users, add to `~/.zshrc`:

  ```bash
  echo 'export AKTO_API_TOKEN="your-actual-token-here"' >> ~/.zshrc
  source ~/.zshrc
  ```

Verify it's set:

```bash
echo $AKTO_API_TOKEN
```

{% endstep %}

{% step %}
**Start the Agent**

The agent automatically discovers and protects your MCP servers.

```bash
./mcp-endpoint-shield agent
```

**Expected output:**

```
Starting akto agent...
Starting RunAgent...
Agent mode started. Press Ctrl+C to stop...
```

**Keep this terminal running.** The agent will:

* Find your MCP configuration files (Cursor, VS Code, Claude Desktop)
* Wrap your MCP servers with security
* Sync security policies from Akto backend
* Watch for changes and auto-update configs

{% hint style="info" %}
**Note:**

If you want the agent to run in the background, use:

<pre class="language-bash"><code class="lang-bash"><strong>nohup ./mcp-endpoint-shield agent > agent.log 2>&#x26;1 &#x26;
</strong></code></pre>

{% endhint %}
{% endstep %}

{% step %}
**Protecting Local MCP Servers (STDIO)**

**Option A: Let the Agent Wrap It (Recommended)**

If the agent is running (Step 2), it will **automatically** detect and wrap your config. Your MCP configuration will be automatically modified to route through the security shield.

<details>

<summary><strong>Example transformation</strong></summary>

Before:

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools"]
    }
  }
}
```

After (automatic):

```json
{
  "mcpServers": {
    "chrome-devtools-endpoint-shield": {
      "command": "mcp-endpoint-shield",
      "args": [
        "stdio",
        "--name",
        "chrome-devtools",
        "--akto-api-token",
        "your-actual-token-here",
        "--exec",
        "npx",
        "-y",
        "chrome-devtools"
      ]
    }
  }
}
```

</details>

**Restart your MCP client** (Cursor/VS Code) to apply changes.

**Option B: Manual Wrapping (If Not Using Agent)**

If you're not running the agent, manually edit your MCP config file (e.g., `~/.cursor/mcp.json`):

**Key changes:**

1. Change `command` to the full path of `mcp-endpoint-shield`
2. Add `"stdio", "--name", "<server-name>", "--akto-api-token", "<your-token>", "--exec"` to the start of `args`
3. Place the original command (`npx`) and arguments (`-y`, `chrome-devtools`) after `--exec`

<details>

<summary><strong>Example transformation</strong></summary>

**Before:**

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools"]
    }
  }
}
```

**After:**

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "/path/to/mcp-endpoint-shield",
      "args": [
        "stdio",
        "--name",
        "chrome-devtools",
        "--akto-api-token",
        "your-actual-token-here",
        "--exec",
        "npx",
        "-y",
        "chrome-devtools"
      ]
    }
  }
}
```

</details>

**Restart your MCP client** to apply changes.
{% endstep %}

{% step %}
**Protecting Remote MCP Servers (HTTP)**

For HTTP-based MCP servers, run the HTTP proxy in a **new terminal**:

```bash
export AKTO_API_TOKEN="your-actual-token-here"
./mcp-endpoint-shield http
```

**Expected output:**

```
Starting MCP HTTP Proxy on 127.0.0.1:57294
Project: default, Skip Threat: false
```

**Keep this terminal running.**

{% hint style="info" %}
**Note:** The proxy runs on port `57294` by default.
{% endhint %}

**Configure Your Remote MCP Server**

**Original config** (direct connection to remote server):

```json
{
  "mcpServers": {
    "remote-mcp": {
      "url": "https://remote-mcp-server.example.com/mcp",
      "headers": {
        "Authorization": "Basic <token>"
      }
    }
  }
}
```

**Protected config** (route through proxy):

```json
{
  "mcpServers": {
    "remote-mcp": {
      "url": "http://localhost:57294/mcp/streamable",
      "headers": {
        "Authorization": "Basic <token>",
        "mcp-server-base-url": "https://remote-mcp-server.example.com/mcp"
      }
    }
  }
}
```

**Key changes:**

1. Change `url` to `http://localhost:57294/mcp/streamable`
2. Keep your existing `Authorization` header (or any other headers)
3. Add new header `mcp-server-base-url` with the original remote server URL

The proxy will:

* Receive requests at `http://localhost:57294/mcp/streamable`
* Read the `mcp-server-base-url` header to know where to forward
* Apply security policies
* Forward to your actual remote MCP server
* Return the response back to your client

**Restart your MCP client** to apply changes.
{% endstep %}

{% step %}
**Verify Everything is Working**

* **Check Agent Status**

  Look at the agent terminal - you should see:

  ```
  Agent mode started. Press Ctrl+C to stop...
  ```

  No errors means it's working!
* **Check HTTP Proxy Status**

  Look at the proxy terminal:

  ```
  Starting MCP HTTP Proxy on 127.0.0.1:57294
  ```
* **Probe Your MCP Server**

  Open your MCP client (Cursor, VS Code, Claude Desktop) and try using your wrapped MCP server. It should work normally, but now with security protection.Step 4:
  {% endstep %}
  {% endstepper %}

## Quick Command Reference

**Terminal 1 - Agent:**

```bash
export AKTO_API_TOKEN="your-token"
./mcp-endpoint-shield agent
```

**Terminal 2 - HTTP Proxy:**

```bash
export AKTO_API_TOKEN="your-token"
./mcp-endpoint-shield http
```

**Get Help:**

```bash
./mcp-endpoint-shield help
```

This protects:

* **STDIO servers** (like `npx -y chrome-devtools`) via agent
* **HTTP servers** (remote MCP servers) via proxy

## Common Flags

* `--name <project_name>` → Friendly label used in logs and insights
* `--akto-api-token <token>` → Your Akto API token
* `--exec <command> [args...]` → Command to start your MCP server
* `--env KEY=VALUE` (repeatable) → Pass additional environment variables to the MCP process

## Logging

Based on Log File Locations, choose from the following:

### Manual Run

When you manually run `mcp-endpoint-shield`, logs are written to:

```
~/.akto-mcp-endpoint-shield/logs/
```

**Example:**

```bash
# If you wrapped a server with --name chrome-devtools
tail -f ~/.akto-mcp-endpoint-shield/logs/chrome-devtools.log

# View all logs
ls -la ~/.akto-mcp-endpoint-shield/logs/
tail -f ~/.akto-mcp-endpoint-shield/logs/*.log
```

### MacOS System Service (LaunchDaemon)

When installed and running as a system service on macOS:

* **Agent logs**

  ```
  /var/log/akto-mcp-endpoint-shield/agent.log
  /var/log/akto-mcp-endpoint-shield/agent-error.log
  ```
* **HTTP Proxy logs**

  ```
  /var/log/akto-mcp-endpoint-shield/proxy-server.log
  /var/log/akto-mcp-endpoint-shield/proxy-error.log
  ```
* **View logs**

  ```bash
  sudo tail -f /var/log/akto-mcp-endpoint-shield/*.log
  ```

### Linux System Service (systemd)

When installed and running as a systemd service on Linux:

* **Agent logs**

  ```
  /var/log/akto-mcp-endpoint-shield/agent.log
  ```
* **HTTP Proxy logs**

  ```
  /var/log/akto-mcp-endpoint-shield/proxy-server.log
  ```
* **View logs**

  ```bash
  # Direct log files
  sudo tail -f /var/log/akto-mcp-endpoint-shield/*.log

  # Via systemd journalctl
  sudo journalctl -u mcp-endpoint-shield-agent -f
  sudo journalctl -u mcp-endpoint-shield -f
  ```

### Windows

When AI Endpoint Shield runs on Windows, agent logs are stored in the user’s local application data directory:

```powershell
%LOCALAPPDATA%\akto-mcp-endpoint-shield\logs\
```

You can use this command to verify agent startup, inspect runtime errors, and confirm connectivity from the Windows endpoint.

### STDIO Wrapped MCP servers (Manual and Installer)

Each wrapped STDIO MCP server gets its own log file named after the `--name` attribute:

```
~/.akto-mcp-endpoint-shield/logs/<name>.log
```

## Troubleshooting

**Issue:** `AKTO_API_TOKEN is not set`

* **Cause**: Environment variable not configured.
* **Fix**: Set the token with `export AKTO_API_TOKEN="your-token"` and verify with `echo $AKTO_API_TOKEN`.

**Issue:** `Port already in use` (HTTP Proxy)

* **Cause**: Port 57294 is already being used by another process.
* **Fix 1**: Find and kill the process with `lsof -i :57294` and `kill -9 PID`.
* **Fix 2**: Use a different port with `./mcp-endpoint-shield http --port 8080` and update your config.

**Issue:** MCP server not working after wrapping

* **Cause**: Multiple possible causes.
* **Fix**:
  * Restart your MCP client,
  * Verify binary path with `which mcp-endpoint-shield`,
  * Check logs at `~/.akto-mcp-endpoint-shield/logs/` or `/var/log/akto-mcp-endpoint-shield/` (if installed using installer)
  * Test original command works standalone.

**Issue:** `permission denied: ./mcp-endpoint-shield` ➡

* **Cause**: Binary doesn't have execute permissions. ➡
* **Fix**: Run `chmod +x ./mcp-endpoint-shield`.

**Issue:** `command not found: mcp-endpoint-shield` ➡

* **Cause**: Binary not in PATH or wrong path used. ➡
* **Fix**: Use full path (`./mcp-endpoint-shield` or `/usr/local/bin/mcp-endpoint-shield`) or add to PATH with `export PATH=$PATH:/path/to/binary/directory`.

{% hint style="success" %}
**Akto Security Scope**

* **Transparency**: Safe traffic is never altered.
* **Clarity**: Unsafe traffic always results in a clear JSON-RPC error.
* **Minimal footprint**: Designed to stay invisible unless an issue occurs.
  {% endhint %}

## Get Support for your Akto setup

There are multiple ways to request support from Akto. We are 24X7 available on the following:

1. In-app `intercom` support. Message us with your query on intercom in Akto dashboard and someone will reply.
2. Join our [discord channel](https://www.akto.io/community) for community support.
3. Contact `support@akto.io` for email support.
4. Contact us [here](https://www.akto.io/contact-us).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ai-security-docs.akto.io/akto-atlas-agentic-ai-security-for-employee-endpoints/endpoints-discovery-agents/ai-endpoint-shield.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.