MCPProxy

https://docs.mcpproxy.app
Admin
MCPProxy is an intelligent proxy for AI agents using the Model Context Protocol (MCP) that provides...
Tokens:71,954
Snippets:676
Trust Score:5.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### Setup Local Documentation Environment

Source: https://docs.mcpproxy.app/contributing

Commands to clone the repository, install necessary dependencies, and start the local documentation development server for previewing changes.

```bash
git clone https://github.com/smart-mcp-proxy/mcpproxy-go.git
cd mcpproxy-go
make docs-setup
make docs-dev
```

--------------------------------

### Start MCPProxy Server via Terminal

Source: https://docs.mcpproxy.app/getting-started/quick-start

This command starts the MCPProxy core server from the terminal. It's recommended for users who installed via Homebrew or manual binary download. The server listens on http://127.0.0.1:8080, with the Web UI available at http://127.0.0.1:8080/ui/.

```bash
mcpproxy serve
```

--------------------------------

### Windows Installer Generation

Source: https://docs.mcpproxy.app/development/building

Commands to package the application into a Windows installer using Inno Setup or the WiX Toolset.

```powershell
# Using Inno Setup (recommended)
.\scripts\build-windows-installer.ps1 -Version "v1.0.0" -Arch "amd64"

# Using WiX Toolset
wix build -arch x64 -d Version=1.0.0.0 -d BinPath=dist\windows-amd64 wix\Package.wxs
```

--------------------------------

### Start MCPProxy Core Server with Custom Port

Source: https://docs.mcpproxy.app/configuration/environment-variables

Demonstrates how to start the mcpproxy core server and specify a custom listening port using the MCPPROXY_LISTEN environment variable.

```bash
MCPPROXY_LISTEN=":9000" mcpproxy serve
```

--------------------------------

### Start MCPProxy Daemon and Execute Commands

Source: https://docs.mcpproxy.app/cli/command-reference

Demonstrates how to start the MCPProxy daemon in the background and then execute CLI commands that automatically leverage the running daemon for faster execution and shared state.

```bash
# Start daemon in the background
mcpproxy serve &

# Commands that use daemon mode automatically
mcpproxy tools list --server=github-server
mcpproxy auth login --server=oauth-server
mcpproxy call tool --tool-name=github:search --json_args='{}'
```

--------------------------------

### MCP Proxy IDE Configuration Examples

Source: https://docs.mcpproxy.app/features/intent-declaration

Configuration examples for setting MCP tool permissions in different IDEs. Shows how to configure auto-approval, ask each time, or always ask for different tool operation types.

```yaml
MCPProxy Tools:
  call_tool_read        [Auto-approve]
  call_tool_write       [Ask each time]
  call_tool_destructive [Always ask]
```

```json
{
  "mcpServers": {
    "mcpproxy": {
      "permissions": {
        "call_tool_read": "auto",
        "call_tool_write": "ask",
        "call_tool_destructive": "always_ask"
      }
    }
  }
}
```

--------------------------------

### Syntax Highlighting Examples

Source: https://docs.mcpproxy.app/contributing

Examples of how to specify languages for syntax highlighting in documentation code blocks.

```bash
mcpproxy serve
```

```json
{
  "key": "value"
}
```

--------------------------------

### Start MCPProxy Server

Source: https://docs.mcpproxy.app/cli/command-reference

Command to start the MCPProxy server. It includes various flags to configure listening address, API key, socket enablement, and other operational parameters.

```bash
mcpproxy serve [flags]
# Example with flags:
mcpproxy serve --listen=127.0.0.1:8080 --enable-socket=true --tool-response-limit=1024
```

--------------------------------

### Install Trusted Certificate with mcpproxy

Source: https://docs.mcpproxy.app/cli/command-reference

Installs a certificate into the system or login keychain. Requires the path to the certificate file and optionally allows forcing installation without confirmation.

```bash
mcpproxy trust-cert <certificate-path> [--force] [--keychain=<keychain_name>]
```

--------------------------------

### List MCPProxy Servers

Source: https://docs.mcpproxy.app/api/rest-api

Example GET request to the /api/v1/servers endpoint, returning a list of all configured upstream servers with their health status.

```json
{
  "success": true,
  "data": {
    "servers": [
      {
        "name": "github-server",
        "protocol": "http",
        "enabled": true,
        "connected": true,
        "quarantined": false,
        "tool_count": 15,
        "health": {
          "level": "healthy",
          "admin_state": "enabled",
          "summary": "Connected (15 tools)",
          "action": ""
        }
      },
      {
        "name": "oauth-server",
        "protocol": "http",
        "enabled": true,
        "connected": false,
        "quarantined": false,
        "tool_count": 0,
        "health": {
          "level": "unhealthy",
          "admin_state": "enabled",
          "summary": "Token expired",
          "detail": "OAuth access token has expired",
          "action": "login"
        }
      }
    ]
  }
}
```

--------------------------------

### mcpproxy Configuration File

Source: https://docs.mcpproxy.app/features/agent-tokens

Example configuration for mcpproxy, showing settings for authentication enforcement and API key.

```json
{
  "require_mcp_auth": false,
  "api_key": "your-admin-key"
}
```

--------------------------------

### JavaScript Tool Chaining Example

Source: https://docs.mcpproxy.app/features/code-execution

An example of chaining tool calls in JavaScript. It first gets user information and then uses that information to create an issue.

```javascript
// Get user info then create an issue
var user = call_tool('github', 'get_user', { username: input.username });
var issue = call_tool('github', 'create_issue', {
  repo: input.repo,
  title: 'Issue from ' + user.name,
  body: 'Created by code execution'
});
({
  user: user,
  issue: issue
})
```

--------------------------------

### Configure MCPProxy with Keyring Secrets

Source: https://docs.mcpproxy.app/features/keyring-integration

Example JSON configuration showing how to use ${keyring:name} syntax for headers and environment variables within the mcpServers definition.

```json
{
  "mcpServers": [
    {
      "name": "github-mcp",
      "url": "https://api.github.com/mcp",
      "protocol": "http",
      "headers": {
        "Authorization": "Bearer ${keyring:github-token}"
      },
      "enabled": true
    },
    {
      "name": "my-stdio-server",
      "command": "python",
      "args": ["-m", "my_server"],
      "protocol": "stdio",
      "env": {
        "API_KEY": "${keyring:my-api-key}",
        "DATABASE_URL": "${env:DATABASE_URL}"
      },
      "enabled": true
    }
  ]
}
```

--------------------------------

### Enable MCPProxy Server

Source: https://docs.mcpproxy.app/api/rest-api

Example POST request to enable a specific server managed by MCPProxy. Requires the server name in the URL path.

```bash
curl -X POST http://127.0.0.1:8080/api/v1/servers/your-server-name/enable
```

--------------------------------

### MCPProxy CLI OAuth Error Output Example

Source: https://docs.mcpproxy.app/features/oauth-authentication

This example shows the detailed error output provided by the MCPProxy CLI when an OAuth authentication fails. It includes the error type, server information, a descriptive message, and suggestions for resolution. It also provides debug information, such as server logs and request IDs, to aid in troubleshooting.

```bash
❌ OAuth Error: dcr_failed
  
Server: github-server
Message: Dynamic Client Registration failed: 403 Forbidden
Suggestion: Check if the OAuth server requires pre-registered clients
  
🔍 Debug:
   Server logs: mcpproxy upstream logs github-server
   Activity log: mcpproxy activity list --request-id req-xyz-123
   Request ID: req-xyz-123
   Correlation ID: a1b2c3d4e5f6789012345678
```

--------------------------------

### Retrieve Tools Input Schema and Example

Source: https://docs.mcpproxy.app/api/mcp-protocol

Defines the input schema for the 'retrieve_tools' function, which searches for tools across servers using BM25 keyword search. It includes an example of how to use this function.

```JSON
{
  "query": "string (required) - Search keywords",
  "limit": "number (optional) - Maximum results, default 15"
}
```

```JSON
{
  "query": "create github issue",
  "limit": 5
}
```

--------------------------------

### JavaScript Conditional Logic Example

Source: https://docs.mcpproxy.app/features/code-execution

An example demonstrating conditional logic in JavaScript. It lists directory files and returns different outputs based on the number of files or filters for markdown files.

```javascript
var files = call_tool('filesystem', 'list_directory', { path: input.path });
  
if (files.length > 100) {
  ({
    status: 'too_many_files',
    count: files.length
  });
} else {
  var results = [];
  for (var i = 0; i < files.length; i++) {
    if (files[i].endsWith('.md')) {
      results.push(files[i]);
    }
  }
  ({
    markdown_files: results
  });
}
```

--------------------------------

### Tool Orchestration via CLI

Source: https://docs.mcpproxy.app/features/code-execution

Example of orchestrating a tool call ('github', 'get_user') using the command-line interface. The input specifies the username.

```bash
mcpproxy code exec --code="call_tool('github', 'get_user', {username: input.user})" --input='{"user":"octocat"}'
```

--------------------------------

### Define Permission Tiers for Tokens

Source: https://docs.mcpproxy.app/features/agent-tokens

Examples of creating tokens with varying levels of access, from read-only monitoring to full administrative control.

```bash
# Read-only monitoring agent
mcpproxy token create --name monitor --servers "*" --permissions read

# CI/CD agent that creates and updates
mcpproxy token create --name ci-agent --servers github --permissions read,write

# Full-access admin agent
mcpproxy token create --name admin-bot --servers "*" --permissions read,write,destructive
```

--------------------------------

### Real-time Tool Call Monitoring

Source: https://docs.mcpproxy.app/features/activity-log

This example demonstrates how to monitor real-time events specifically for tool calls using `grep` on the SSE stream.

```curl
curl -N "http://127.0.0.1:8080/events?apikey=$KEY" | grep "activity.tool_call"
```

--------------------------------

### Configure MCP Client with Token

Source: https://docs.mcpproxy.app/features/agent-tokens

Example JSON configuration for an MCP client to include the agent token in the headers for server communication.

```json
{
  "mcpServers": {
    "mcpproxy": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "X-API-Key": "mcp_agt_a1b2c3d4..."
      }
    }
  }
}
```

--------------------------------

### Restart MCPProxy Server

Source: https://docs.mcpproxy.app/api/rest-api

Example POST request to restart a specific server managed by MCPProxy. Requires the server name in the URL path.

```bash
curl -X POST http://127.0.0.1:8080/api/v1/servers/your-server-name/restart
```

--------------------------------

### Get MCPProxy Server Status

Source: https://docs.mcpproxy.app/api/rest-api

Example of a GET request to the /api/v1/status endpoint to retrieve the current status, version, uptime, and server/tool counts of MCPProxy.

```json
{
  "status": "running",
  "version": "0.11.0",
  "uptime": 3600,
  "servers": {
    "total": 5,
    "connected": 4,
    "quarantined": 1
  },
  "tools": {
    "total": 42
  }
}
```

--------------------------------

### Import Configurations via CLI

Source: https://docs.mcpproxy.app/features/config-import

Use the mcpproxy CLI to import configurations from local files. Supports format hints, dry-run previews, and bypassing quarantine for trusted sources.

```bash
# Import from Claude Desktop config
mcpproxy upstream import ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Import from Claude Code config
mcpproxy upstream import ~/.claude.json

# Import with format hint (if auto-detect fails)
mcpproxy upstream import --format claude-desktop config.json

# Preview without importing
mcpproxy upstream import --dry-run config.json

# Import without quarantine (trusted configs)
mcpproxy upstream import --no-quarantine ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

--------------------------------

### MCPProxy System Start Event Log

Source: https://docs.mcpproxy.app/features/activity-log

Logs MCPProxy server startup events, including version, listen address, startup duration, and configuration path.

```json
{
  "id": "01JFXYZ123DEF",
  "type": "system_start",
  "status": "success",
  "timestamp": "2025-01-15T10:00:00Z",
  "metadata": {
    "version": "v0.5.0",
    "listen_address": "127.0.0.1:8080",
    "startup_duration_ms": 150,
    "config_path": "/Users/user/.mcpproxy/mcp_config.json"
  }
}
```

--------------------------------

### Build Core and Tray Applications

Source: https://docs.mcpproxy.app/development/building

Standard build commands for the headless core server and the tray application using Go. Requires CGO for the tray component on macOS/Linux.

```bash
# Core server (headless)
go build -o mcpproxy ./cmd/mcpproxy

# Tray application (requires CGO on macOS)
CGO_ENABLED=1 go build -o mcpproxy-tray ./cmd/mcpproxy-tray

# Both with make
make build
```

--------------------------------

### Upgrade MCPProxy via Homebrew

Source: https://docs.mcpproxy.app/features/version-updates

For users who installed MCPProxy via Homebrew, the standard upgrade command will fetch and install the latest version.

```bash
brew upgrade mcpproxy
```

--------------------------------

### TypeScript Type Annotations Example

Source: https://docs.mcpproxy.app/features/code-execution

Example of using TypeScript type annotations within code execution. Types are automatically stripped before execution.

```typescript
const x: number = 42;
({ result: x });
```

--------------------------------

### JavaScript Simple Calculation Example

Source: https://docs.mcpproxy.app/features/code-execution

A simple JavaScript example that takes an input object with properties 'a' and 'b' and returns an object containing their sum.

```javascript
// input: { "a": 5, "b": 3 }
({
  sum: input.a + input.b
})
```

--------------------------------

### JavaScript Error Handling Example

Source: https://docs.mcpproxy.app/features/code-execution

An example of error handling in JavaScript using a try-catch block. It attempts to fetch data and returns success or failure information.

```javascript
try {
  var result = call_tool('api', 'fetch_data', { url: input.url });
  ({
    success: true,
    data: result
  });
} catch (e) {
  ({
    success: false,
    error: e.message
  });
}
```

--------------------------------

### REST API - Import from Path

Source: https://docs.mcpproxy.app/features/config-import

Imports servers by reading a configuration file from the server's filesystem.

```APIDOC
## POST /api/v1/servers/import/path

### Description
Import servers by reading a file from the server's filesystem.

### Method
POST

### Endpoint
/api/v1/servers/import/path

### Parameters
#### Query Parameters
- **preview** (boolean) - Optional - If true, performs a preview import without saving changes.

#### Request Body
- **path** (string) - Required - The file path to the configuration file.
- **format** (string) - Optional - The format of the configuration file (e.g., "claude-code"). If not provided, it will be auto-detected.

### Request Example (Preview)
```bash
curl -X POST -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"path": "/Users/user/.claude.json", "format": "claude-code"}' \
  "http://127.0.0.1:8080/api/v1/servers/import/path?preview=true"
```

### Request Example (Actual Import)
```bash
curl -X POST -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"path": "/Users/user/.claude.json"}' \
  http://127.0.0.1:8080/api/v1/servers/import/path
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the import was successful.
- **data** (object) - Contains information about the imported servers (structure may vary based on preview or actual import).
```

--------------------------------

### Build Documentation Locally

Source: https://docs.mcpproxy.app/contributing

Command to verify that the documentation build succeeds before submitting a pull request.

```bash
make docs-build
```

--------------------------------

### Call Tool Destructive Input Schema and Example

Source: https://docs.mcpproxy.app/api/mcp-protocol

Defines the input schema for the 'call_tool_destructive' function, used for destructive operations like deleting resources. It provides an example for deleting a GitHub repository.

```JSON
{
  "name": "string (required) - Tool name in server:tool format",
  "args_json": "string (optional) - Tool arguments as JSON string",
  "intent": {
    "operation_type": "destructive (required)",
    "data_sensitivity": "string (optional) - public|internal|private|unknown",
    "reason": "string (optional) - Explanation for audit trail"
  }
}
```

```JSON
{
  "name": "github:delete_repo",
  "args_json": "{\"repo\": \"test-repo\"}",
  "intent": {
    "operation_type": "destructive",
    "data_sensitivity": "private",
    "reason": "User confirmed deletion"
  }
}
```

--------------------------------

### MCPProxy: Combine Filters for Activity Search

Source: https://docs.mcpproxy.app/cli/sensitive-data-commands

Demonstrates combining multiple filters such as sensitive data presence, severity, detection type, server, and time range for precise activity log queries. Includes an example of a full combination with a limit.

```bash
# Combine filters for targeted search
mcpproxy activity list --sensitive-data --severity critical

# Filter by type and server
mcpproxy activity list --detection-type aws_access_key --server github

# Filter by severity with time range
mcpproxy activity list --severity high --start-time "$(date -u +%Y-%m-%dT00:00:00Z)"

# Full combination
mcpproxy activity list \
  --sensitive-data \
  --severity critical \
  --server myserver \
  --limit 100
```

--------------------------------

### Execute MCP Proxy CLI Commands

Source: https://docs.mcpproxy.app/features/intent-declaration

Examples of executing MCP Proxy tools via the command-line interface. Demonstrates commands for read, write, and destructive operations, including specifying arguments, sensitivity, and reasons for audit.

```bash
# Read operation
mcpproxy call tool-read github:list_repos --args '{"org": "myorg"}'

# Write operation
mcpproxy call tool-write github:create_issue \
  --args '{"title": "Bug", "body": "Details"}' \
  --reason "Creating bug report"

# Destructive operation
mcpproxy call tool-destructive github:delete_repo \
  --args '{"repo": "test"}' \
  --sensitivity private \
  --reason "User confirmed deletion"
```

--------------------------------

### Configure MCPProxy with Environment Variables

Source: https://docs.mcpproxy.app/cli/command-reference

Demonstrates how to use environment variables to customize MCPProxy's behavior, such as overriding the socket path or forcing standalone mode.

```bash
# Use a custom socket endpoint
MCPPROXY_TRAY_ENDPOINT="unix:///tmp/custom.sock" mcpproxy tools list --server=myserver

# Force standalone mode by setting an empty endpoint
MCPPROXY_TRAY_ENDPOINT="" mcpproxy tools list --server=myserver --log-level=trace
```

--------------------------------

### Call Tool Write Input Schema and Example

Source: https://docs.mcpproxy.app/api/mcp-protocol

Defines the input schema for the 'call_tool_write' function, used to execute state-modifying tools. It includes an example for creating a GitHub issue, specifying the tool, arguments, and intent.

```JSON
{
  "name": "string (required) - Tool name in server:tool format",
  "args_json": "string (optional) - Tool arguments as JSON string",
  "intent": {
    "operation_type": "write (required)",
    "data_sensitivity": "string (optional) - public|internal|private|unknown",
    "reason": "string (optional) - Explanation for audit trail"
  }
}
```

```JSON
{
  "name": "github:create_issue",
  "args_json": "{\"repo\": \"owner/repo\", \"title\": \"Bug report\", \"body\": \"Description\"}",
  "intent": {
    "operation_type": "write",
    "reason": "Creating bug report per user request"
  }
}
```

--------------------------------

### Call Tool Read Input Schema and Example

Source: https://docs.mcpproxy.app/api/mcp-protocol

Defines the input schema for the 'call_tool_read' function, used to execute read-only tools. It specifies the tool name, optional arguments, and intent details, with an example for listing GitHub repositories.

```JSON
{
  "name": "string (required) - Tool name in server:tool format",
  "args_json": "string (optional) - Tool arguments as JSON string",
  "intent": {
    "operation_type": "read (required)",
    "data_sensitivity": "string (optional) - public|internal|private|unknown",
    "reason": "string (optional) - Explanation for audit trail"
  }
}
```

```JSON
{
  "name": "github:list_repos",
  "args_json": "{\"org\": \"myorg\"}",
  "intent": {
    "operation_type": "read"
  }
}
```

--------------------------------

### Go Unit Test Pattern

Source: https://docs.mcpproxy.app/development/testing

Demonstrates the standard pattern for writing unit tests in Go using the 'testing' package. It follows the Arrange-Act-Assert structure.

```go
func TestFeatureName(t *testing.T) {
    // Arrange
    sut := NewSystemUnderTest()

    // Act
    result, err := sut.DoSomething()

    // Assert
    require.NoError(t, err)
    assert.Equal(t, expected, result)
}
```

--------------------------------

### GET /api/v1/tokens

Source: https://docs.mcpproxy.app/features/agent-tokens

Lists all existing agent tokens.

```APIDOC
## GET /api/v1/tokens

### Description
Retrieves a list of all agent tokens managed by the proxy.

### Method
GET

### Endpoint
/api/v1/tokens

### Response
#### Success Response (200)
- **tokens** (array) - List of token objects containing name, prefix, servers, permissions, revoked status, and expiry.

#### Response Example
[
  {
    "name": "deploy-bot",
    "prefix": "mcp_agt_a1b2",
    "servers": ["github", "gitlab"],
    "permissions": ["read", "write"],
    "revoked": false,
    "expires": "2026-04-05 14:30"
  }
]
```

--------------------------------

### GET /api/v1/servers

Source: https://docs.mcpproxy.app/features/tool-quarantine

Retrieves the list of servers and their associated quarantine metrics.

```APIDOC
## GET /api/v1/servers

### Description
Returns a list of all configured servers, including quarantine metrics if there are pending or changed tools.

### Method
GET

### Endpoint
/api/v1/servers

### Response
#### Success Response (200)
- **servers** (array) - List of server objects.
- **quarantine** (object) - Contains pending_count and changed_count if applicable.

#### Response Example
{
  "servers": [
    {
      "name": "github-server",
      "quarantine": {
        "pending_count": 2,
        "changed_count": 1
      }
    }
  ]
}
```

--------------------------------

### Get Activity Summary

Source: https://docs.mcpproxy.app/web-ui/activity-log

Retrieves a summary of activities over the last 24 hours.

```APIDOC
## GET /api/v1/activity/summary

### Description
Provides a summary of activities within the last 24 hours.

### Method
GET

### Endpoint
/api/v1/activity/summary

### Response
#### Success Response (200)
- **total_activities** (integer) - Total number of activities in the last 24 hours.
- **success_count** (integer) - Number of successful activities.
- **error_count** (integer) - Number of failed activities.
- **blocked_count** (integer) - Number of blocked activities.
- **recent_activities** (array) - A list of the 5 most recent activities.

#### Response Example
{
  "total_activities": 1200,
  "success_count": 1100,
  "error_count": 50,
  "blocked_count": 50,
  "recent_activities": [
    {
      "id": "activity_456",
      "timestamp": "2023-10-27T10:05:00Z",
      "type": "tool_call",
      "server": "server_b",
      "status": "success"
    }
  ]
}
```

--------------------------------

### Configure stdio Server for MCPProxy

Source: https://docs.mcpproxy.app/configuration/upstream-servers

Defines a local server that communicates via standard input/output. Requires a command to execute and optionally accepts arguments, protocol, and enablement status.

```json
{
  "name": "filesystem",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
  "protocol": "stdio",
  "enabled": true
}
```

--------------------------------

### Get Activity Details

Source: https://docs.mcpproxy.app/web-ui/activity-log

Retrieves detailed information for a specific activity by its ID.

```APIDOC
## GET /api/v1/activity/{id}

### Description
Retrieves detailed information for a specific activity.

### Method
GET

### Endpoint
/api/v1/activity/{id}

### Path Parameters
- **id** (string) - Required - The unique identifier of the activity.

### Response
#### Success Response (200)
- **activity** (object) - Detailed activity object including metadata, request, response, and error information.

#### Response Example
{
  "activity": {
    "id": "activity_123",
    "timestamp": "2023-10-27T10:00:00Z",
    "type": "tool_call",
    "server": "server_a",
    "details": "Run command X",
    "intent": "write",
    "status": "success",
    "duration": 1500,
    "metadata": {
      "session_id": "session_abc"
    },
    "request": {
      "args": {
        "command": "ls -l"
      }
    },
    "response": {
      "output": "-rw-r--r-- 1 user group 1024 Oct 27 10:00 file.txt"
    }
  }
}
```

--------------------------------

### Filter and process activity logs with jq

Source: https://docs.mcpproxy.app/cli/activity-commands

Demonstrates how to pipe mcpproxy JSON output into jq for advanced filtering. Includes examples for searching by server name and counting errors per server.

```bash
# Find all tool calls with "github" in JSON output
mcpproxy activity list -o json | jq '.activities[] | select(.server_name | contains("github"))'

# Count errors by server
mcpproxy activity list --status error -o json | jq -r '.activities[].server_name' | sort | uniq -c
```

--------------------------------

### GET /api/v1/servers/{server_name}/tools/export

Source: https://docs.mcpproxy.app/features/tool-quarantine

Exports tool descriptions and schemas for audit purposes.

```APIDOC
## GET /api/v1/servers/{server_name}/tools/export

### Description
Retrieves all tool descriptions and schemas for a specific server, useful for auditing changes.

### Method
GET

### Endpoint
/api/v1/servers/{server_name}/tools/export

### Parameters
#### Path Parameters
- **server_name** (string) - Required - The name of the server.

#### Query Parameters
- **format** (string) - Optional - The output format, e.g., 'text' or 'json' (default).

### Request Example
curl -H "X-API-Key: your-key" http://127.0.0.1:8080/api/v1/servers/github-server/tools/export?format=text

### Response
#### Success Response (200)
- **data** (object/string) - The exported tool schema information.
```

--------------------------------

### GET /api/v1/secrets/config

Source: https://docs.mcpproxy.app/features/keyring-integration

Retrieves all secret and environment variable references found in the current configuration.

```APIDOC
## GET /api/v1/secrets/config

### Description
Returns all secret and environment variable references found in the current configuration, along with their resolution status.
```

--------------------------------

### GET /api/v1/info

Source: https://docs.mcpproxy.app/api/rest-api

Retrieves application information, version details, and update availability status.

```APIDOC
## GET /api/v1/info

### Description
Returns the current version of MCPProxy, network configuration, and information regarding available software updates.

### Method
GET

### Endpoint
/api/v1/info

### Response
#### Success Response (200)
- **version** (string) - Current MCPProxy version
- **web_ui_url** (string) - URL to access the web control panel
- **update** (object) - Update information including availability and release URL

### Response Example
{
  "success": true,
  "data": {
    "version": "v1.2.3",
    "update": {
      "available": true,
      "latest_version": "v1.3.0"
    }
  }
}
```

--------------------------------

### Recommended Settings by Use Case

Source: https://docs.mcpproxy.app/configuration/sensitive-data-detection

Provides example configurations for sensitive data detection tailored to different use cases, such as high-security, performance-sensitive, and minimal detection environments.

```APIDOC
## Recommended Settings by Use Case

### High-Security Environments
```json
{
  "sensitive_data_detection": {
    "enabled": true,
    "scan_requests": true,
    "scan_responses": true,
    "max_payload_size_kb": 2048,
    "entropy_threshold": 4.0
  }
}
```

### Performance-Sensitive Environments
```json
{
  "sensitive_data_detection": {
    "enabled": true,
    "scan_requests": true,
    "scan_responses": false,
    "max_payload_size_kb": 512,
    "entropy_threshold": 4.8,
    "categories": {
      "high_entropy": false
    }
  }
}
```

### Minimal Detection (Critical Only)
```json
{
  "sensitive_data_detection": {
    "enabled": true,
    "scan_requests": true,
    "scan_responses": true,
    "categories": {
      "cloud_credentials": true,
      "private_key": true,
      "api_token": true,
      "auth_token": false,
      "sensitive_file": false,
      "database_credential": true,
      "high_entropy": false,
      "credit_card": true
    }
  }
}
```
```

--------------------------------

### GET /events

Source: https://docs.mcpproxy.app/features/activity-log

Streams real-time activity events via Server-Sent Events (SSE).

```APIDOC
## GET /events

### Description
Provides a real-time stream of activity events for monitoring.

### Method
GET

### Endpoint
/events

### Parameters
#### Query Parameters
- **apikey** (string) - Required - API key for authentication.
```

--------------------------------

### REST API - Import from Content

Source: https://docs.mcpproxy.app/features/config-import

Imports servers by posting configuration content directly as JSON or TOML.

```APIDOC
## POST /api/v1/servers/import/json

### Description
Import by posting configuration content directly.

### Method
POST

### Endpoint
/api/v1/servers/import/json

### Parameters
#### Request Body
- **content** (string) - Required - The configuration content as a JSON string.
- **format** (string) - Optional - The format of the configuration content (e.g., "claude-desktop"). If not provided, it will be auto-detected.

### Request Example
```bash
curl -X POST -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{ \
    "content": "{\"mcpServers\": {\"my-server\": {\"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\"]}}}", \
    "format": "claude-desktop" \
  }' \
  http://127.0.0.1:8080/api/v1/servers/import/json
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the import was successful.
- **data** (object) - Contains information about the imported servers.
```

--------------------------------

### Set Custom API Key for MCPProxy

Source: https://docs.mcpproxy.app/configuration/environment-variables

Provides an example of setting a custom API key for authentication with the mcpproxy core server using the MCPPROXY_API_KEY environment variable.

```bash
MCPPROXY_API_KEY="my-secure-key" mcpproxy serve
```

--------------------------------

### Configure HTTP Server for MCPProxy

Source: https://docs.mcpproxy.app/configuration/upstream-servers

Sets up a connection to a remote server accessible via HTTP or HTTPS. Requires a URL and the protocol type, along with an enablement status.

```json
{
  "name": "remote-server",
  "url": "https://api.example.com/mcp",
  "protocol": "http",
  "enabled": true
}
```

--------------------------------

### GET /api/v1/status

Source: https://docs.mcpproxy.app/features/routing-modes

Retrieves the current operational status of the MCPProxy, including the active routing mode.

```APIDOC
## GET /api/v1/status

### Description
Provides the system status of the MCPProxy instance.

### Method
GET

### Endpoint
/api/v1/status

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Authentication key for the proxy.

### Request Example
curl -H "X-API-Key: your-key" http://127.0.0.1:8080/api/v1/status

### Response
#### Success Response (200)
- **routing_mode** (string) - The currently configured routing mode.
```

--------------------------------

### Enable Debug Logging for MCPProxy

Source: https://docs.mcpproxy.app/configuration/environment-variables

Shows how to enable debug logging for the mcpproxy core server by passing the --log-level=debug flag.

```bash
mcpproxy serve --log-level=debug
```

--------------------------------

### GET /api/v1/routing

Source: https://docs.mcpproxy.app/features/routing-modes

Retrieves the current routing mode configuration and available endpoints for the MCPProxy instance.

```APIDOC
## GET /api/v1/routing

### Description
Returns the current active routing mode, its description, and the mapping of available MCP endpoints.

### Method
GET

### Endpoint
/api/v1/routing

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Authentication key for the proxy.

### Request Example
curl -H "X-API-Key: your-key" http://127.0.0.1:8080/api/v1/routing

### Response
#### Success Response (200)
- **routing_mode** (string) - The active mode (e.g., "retrieve_tools").
- **description** (string) - Explanation of the current mode.
- **endpoints** (object) - Map of available service paths.

#### Response Example
{
  "routing_mode": "retrieve_tools",
  "description": "BM25 search via retrieve_tools + call_tool variants (default)",
  "endpoints": {
    "default": "/mcp",
    "direct": "/mcp/all",
    "code_execution": "/mcp/code",
    "retrieve_tools": "/mcp/call"
  },
  "available_modes": ["retrieve_tools", "direct", "code_execution"]
}
```

--------------------------------

### Import Configuration from Content via REST API

Source: https://docs.mcpproxy.app/features/config-import

Directly submit configuration content as a JSON string to the API for parsing and import.

```bash
curl -X POST -H "X-API-Key: your-key" -H "Content-Type: application/json" -d '{"content": "{\"mcpServers\": {\"my-server\": {\"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\"]}}}", "format": "claude-desktop"}' http://127.0.0.1:8080/api/v1/servers/import/json
```

--------------------------------

### GET /mcp/code

Source: https://docs.mcpproxy.app/features/routing-modes

The code_execution endpoint provides specialized tools for JavaScript-based orchestration and tool discovery.

```APIDOC
## GET /mcp/code

### Description
Provides access to the code_execution routing mode, enabling multi-step orchestration and dynamic tool discovery.

### Method
GET

### Endpoint
/mcp/code

### Response
#### Success Response (200)
- **tools** (array) - List of tools available for code execution and orchestration.

#### Response Example
{
  "tools": [
    {"name": "code_execution", "description": "Execute custom JS logic"}
  ]
}
```

--------------------------------

### Manage Upstream Servers with Smart Patching (JSON)

Source: https://docs.mcpproxy.app/api/mcp-protocol

Demonstrates operations for managing upstream servers. Supports 'patch' and 'add' operations with smart merging for fields like 'enabled', 'isolation', and 'args_json'. 'patch' uses deep merge semantics, while 'add' quarantines new servers by default.

```json
{
  "operation": "patch",
  "name": "my-server",
  "enabled": true
}
```

```json
{
  "operation": "add",
  "name": "isolated-server",
  "command": "npx",
  "args_json": "[\"-y\", \"some-mcp-server\"]",
  "isolation_json": "{\"enabled\": true, \"image\": \"node:20\"}"
}
```

```json
{
  "operation": "patch",
  "name": "isolated-server",
  "isolation_json": "{\"image\": \"node:22\"}"
}
```

--------------------------------

### GET /api/v1/servers

Source: https://docs.mcpproxy.app/api/rest-api

Lists all upstream servers managed by the proxy, including their connection status and health details.

```APIDOC
## GET /api/v1/servers

### Description
Retrieves a list of all upstream servers with their current health status and configuration details.

### Method
GET

### Endpoint
/api/v1/servers

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (object) - Contains the list of servers

#### Response Example
{
  "success": true,
  "data": {
    "servers": [
      {
        "name": "github-server",
        "protocol": "http",
        "enabled": true,
        "connected": true,
        "quarantined": false,
        "tool_count": 15,
        "health": {
          "level": "healthy",
          "admin_state": "enabled",
          "summary": "Connected (15 tools)",
          "action": ""
        }
      }
    ]
  }
}
```

--------------------------------

### GET /api/v1/status

Source: https://docs.mcpproxy.app/api/rest-api

Retrieves the current operational status, version information, and server statistics for the MCPProxy instance.

```APIDOC
## GET /api/v1/status

### Description
Returns the current health status, uptime, and summary statistics of the MCPProxy server.

### Method
GET

### Endpoint
/api/v1/status

### Response
#### Success Response (200)
- **status** (string) - Current status of the server (e.g., 'running')
- **version** (string) - Current version of MCPProxy
- **uptime** (integer) - Server uptime in seconds
- **servers** (object) - Statistics regarding total, connected, and quarantined servers
- **tools** (object) - Total count of available tools

#### Response Example
{
  "status": "running",
  "version": "0.11.0",
  "uptime": 3600,
  "servers": {
    "total": 5,
    "connected": 4,
    "quarantined": 1
  },
  "tools": {
    "total": 42
  }
}
```

--------------------------------

### GET /api/v1/activity/export

Source: https://docs.mcpproxy.app/features/activity-log

Exports activity records for compliance and auditing purposes in JSON Lines or CSV format.

```APIDOC
## GET /api/v1/activity/export

### Description
Exports activity logs to a file format for external auditing.

### Method
GET

### Endpoint
/api/v1/activity/export

### Parameters
#### Query Parameters
- **format** (string) - Required - Export format: 'json' (JSON Lines) or 'csv'
- **[filters]** (various) - Optional - Supports the same filters as the list endpoint.
```

--------------------------------

### GET /api/v1/tools

Source: https://docs.mcpproxy.app/features/search-discovery

Search for available tools across all connected MCP servers using full-text search.

```APIDOC
## GET /api/v1/tools

### Description
Searches for tools indexed by MCPProxy using BM25 ranking based on provided query parameters.

### Method
GET

### Endpoint
/api/v1/tools

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query string.
- **limit** (integer) - Optional - Maximum number of results to return (default: 15).

### Request Example
curl -H "X-API-Key: your-key" "http://127.0.0.1:8080/api/v1/tools?q=create%20file&limit=10"

### Response
#### Success Response (200)
- **tools** (array) - List of matching tool objects.

#### Response Example
{
  "tools": [
    {
      "name": "github:create_issue",
      "server": "github-server",
      "description": "Create a new issue in a GitHub repository",
      "score": 0.89
    }
  ]
}
```

--------------------------------

### Execute mcpproxy Tool

Source: https://docs.mcpproxy.app/cli/command-reference

Executes a specified tool with optional JSON arguments and output formatting. Supports both built-in and upstream server tools. Dependencies include the tool name and optional JSON arguments.

```bash
mcpproxy call tool --tool-name=<server:tool> [flags]
mcpproxy call tool --tool-name=upstream_servers --json_args='{"operation":"list"}'
mcpproxy call tool --tool-name=github:list_repos --json_args='{"owner":"myorg"}'
```

--------------------------------

### Enable prerelease updates via environment export

Source: https://docs.mcpproxy.app/features/version-updates

Persistently enable prerelease updates for the current session by exporting the configuration variable.

```bash
export MCPPROXY_ALLOW_PRERELEASE_UPDATES=true
```

--------------------------------

### Compliance Auditing Export

Source: https://docs.mcpproxy.app/features/activity-log

An example of exporting activity data for a specific quarter to be used for compliance and auditing reviews.

```curl
curl -H "X-API-Key: $KEY" \
  "http://127.0.0.1:8080/api/v1/activity/export?format=csv&start_time=2025-01-01T00:00:00Z" \
  > audit-q1-2025.csv
```
Tokens:
Raw