Skip to main content

routes.mcp_proxy

FastAPI routes for MCP Tool Proxy.

This module provides an HTTP endpoint that allows remote sandboxes (e.g., Jupyter kernels in separate containers) to call MCP tools running in the agent-runtimes container via stdio.

Architecture Overview (Two-Container Codemode):

When running in a Kubernetes environment with separate containers:

┌──────────────────────────────────────────────────────────────────────────────┐
│  agent-runtimes container (port 8765)                                        │
│  ┌─────────────────────┐    ┌──────────────────────────────────────────────┐ │
│  │  MCP Servers (stdio)│◀───│  /api/v1/mcp/proxy/{server}/{tool}           │ │
│  │  - github           │    │  - Receives HTTP POST from Jupyter kernel     │ │
│  │  - filesystem       │    │  - Routes to appropriate stdio MCP server     │ │
│  │  - tavily           │    │  - Returns tool result as JSON                │ │
│  └─────────────────────┘    └────────────────────▲─────────────────────────┘ │
│                                                   │ HTTP POST                 │
└───────────────────────────────────────────────────┼──────────────────────────┘
                                                    │
         ┌──────────────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  jupyter container (port 2300)                                                │
│  ┌────────────────────────────────────────────────────────────────────────┐  │
│  │  Jupyter Server + Kernel                                                │  │
│  │  - Executes generated Python code                                       │  │
│  │  - `from generated.mcp.github import star_repo`                     │  │
│  │  - `result = await star_repo(owner="datalayer", repo="ui")`            │  │
│  │  - Generated code calls HTTP proxy instead of stdio                     │  │
│  │                                                                          │  │
│  │  /mnt/shared-agent/generated/  (shared emptyDir volume)                 │  │
│  │  └── servers/                                                            │  │
│  │      └── github.py  ─────────────────────────────────────────────────┐  │  │
│  │                     │  async def star_repo(...):                     │  │  │
│  │                     │      # Calls HTTP proxy at agent-runtimes:8765 │  │  │
│  │                     │      return await http_call_tool(...)          │  │  │
│  │                     └────────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────────┘

The shared volume (/mnt/shared-agent) contains:
- generated/  - Python bindings generated by agent-runtimes, read by Jupyter kernel
- skills/     - User-created skills, accessible from both containers

This module provides the /api/v1/mcp/proxy/* endpoints that bridge the gap between the remote Jupyter sandbox and the local stdio MCP servers.

set_skills_proxy_caller​

def set_skills_proxy_caller(caller: Any) -> None

Register a callable for proxying skill tool calls from remote sandboxes.

get_skills_proxy_caller​

def get_skills_proxy_caller() -> Any

Return the currently registered skills proxy caller (or None).

ToolCallRequest Objects​

class ToolCallRequest(BaseModel)

Request body for tool calls.

Attributes:

  • arguments - The arguments to pass to the tool.

ToolCallResponse Objects​

class ToolCallResponse(BaseModel)

Response from a tool call.

Attributes:

  • success - Whether the tool call succeeded.
  • result - The result data from the tool (if successful).
  • error - Error message (if failed).
  • is_error - Whether the MCP response indicates an error.

proxy_tool_call​

@router.post("/{server_name}/tools/{tool_name}",
             response_model=ToolCallResponse)
async def proxy_tool_call(server_name: str, tool_name: str,
                          request: ToolCallRequest) -> ToolCallResponse

Proxy a tool call from a remote sandbox to a local MCP server.

This endpoint allows code running in a remote Jupyter kernel to call tools on MCP servers that are running as stdio subprocesses in the agent-runtimes container.

The flow is:

  1. Jupyter kernel generates: await github__star_repo(owner="x", repo="y")
  2. Generated code sends HTTP POST to: /api/v1/mcp/proxy/github/tools/star_repo
  3. This endpoint finds the 'github' MCP server instance
  4. Calls the 'star_repo' tool via the MCP stdio session
  5. Returns the result as JSON

Arguments:

  • server_name - Name of the MCP server (e.g., 'github', 'filesystem').
  • tool_name - Name of the tool to call (e.g., 'star_repo', 'list_dir').
  • request - The tool call arguments.

Returns:

ToolCallResponse with the result or error.

list_proxy_servers​

@router.get("/servers")
async def list_proxy_servers() -> dict[str, Any]

List available MCP servers that can be proxied.

Returns:

Dictionary with list of available servers and their tools.

proxy_health​

@router.get("/health")
async def proxy_health() -> dict[str, str]

Health check for the MCP proxy endpoint.

Returns:

Health status.