MCP Protocol

MCPProxy implements the Model Context Protocol (MCP) specification, providing AI clients with unified access to multiple upstream MCP servers.

Endpoints

Default Endpoint

http://127.0.0.1:8080/mcp

Serves the routing mode configured in routing_mode (default: retrieve_tools).

Routing Mode Endpoints

Each routing mode has a dedicated endpoint that is always available regardless of the configured default:

See Routing Modes for details on each mode.

Note: MCP endpoints do not require API key authentication for client compatibility.

Built-in Tools

MCPProxy provides several built-in tools for managing and interacting with upstream servers.

retrieve_tools

Search for tools across all connected servers using BM25 keyword search.

Input Schema:

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

Example:

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

call_tool_read

Execute a read-only tool on an upstream server. Use for operations that query data without modifying state.

Input Schema:

{
  "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"
  }
}

Example:

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

Validation: Rejected if server marks tool as destructiveHint: true.

call_tool_write

Execute a state-modifying tool on an upstream server. Use for operations that create or update resources.

Input Schema:

{
  "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"
  }
}

Example:

{
  "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"
  }
}

Validation: Rejected if server marks tool as destructiveHint: true.

call_tool_destructive

Execute a destructive tool on an upstream server. Use for operations that delete or permanently modify resources.

Input Schema:

{
  "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"
  }
}

Example:

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

Validation: Most permissive - allowed regardless of server annotations.

:::tip Choosing the Right Tool Variant Use retrieve_tools to discover tools - each result includes a call_with field recommending the appropriate variant based on server annotations. :::

See Intent Declaration for complete documentation on the two-key security model.

upstream_servers

Manage upstream server configurations with smart patching support.

Operations:

• list - List all servers with health status
• add - Add a new server (quarantined by default)
• remove - Remove a server
• update - Update server (smart merge)
• patch - Patch server (smart merge)
• tail_log - View server logs

Smart Patching (update/patch):

Uses deep merge semantics - only specify fields you want to change:

Example (patch - toggle enabled):

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

Only enabled changes - all other fields (env, isolation, oauth) are preserved.

Example (add with isolation):

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

Example (patch isolation image only):

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

Only isolation.image changes - isolation.enabled and other fields preserved.

:::caution Concurrent Edits MCPProxy does not support three-way merge with conflict detection. Avoid making concurrent edits to the same server configuration from multiple sources (MCP tool, Web UI, CLI) simultaneously. If concurrent edits occur, the last write wins and earlier changes may be lost.

Best practices:

• Make configuration changes from a single interface at a time
• Use the list operation to verify current state before patching
• Consider using the Web UI for interactive editing sessions :::

code_execution

Execute JavaScript code to orchestrate multiple tools. Disabled by default.

See Code Execution for complete documentation.

Tool Name Format

Tools from upstream servers are prefixed with the server name:

<serverName>:<originalToolName>

Examples:

• github:create_issue
• filesystem:read_file
• sqlite:query

This prevents naming conflicts when multiple servers provide similar tools.

Quarantine Behavior

When a tool is called on a quarantined server:

1. The tool call is not executed
2. A security analysis is returned instead
3. User must approve the server via Web UI or config

This protects against Tool Poisoning Attacks (TPA).

Connection States

Upstream servers can be in these states:

Tool Change Notifications

MCPProxy subscribes to the MCP notifications/tools/list_changed notification from upstream servers. This enables automatic tool re-indexing when servers add, remove, or modify their available tools.

How It Works

1. Server Capability: Servers that support tool change notifications advertise capabilities.tools.listChanged: true during initialization
2. Notification Handler: MCPProxy registers a notification handler after connecting to each server
3. Automatic Re-indexing: When a notification is received, MCPProxy triggers DiscoverAndIndexToolsForServer() within seconds
4. Fallback Behavior: Servers without notification support continue to use the 5-minute background polling cycle

Supported Connection Types

Tool change notifications are supported across all connection types:

• stdio: Local process servers
• HTTP/SSE: Remote HTTP-based servers
• Streamable HTTP: Modern HTTP transport

Resilience Features

• Deduplication: Rapid successive notifications are deduplicated to prevent redundant discovery
• Timeout Protection: Discovery operations have a 30-second timeout
• Graceful Degradation: Errors during discovery are logged but don't crash the proxy

Logs

When notifications are received, MCPProxy logs:

Error Handling

MCP errors follow the JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": {}
  }
}