# How MetaMCP Integrates with Claude Desktop Using mcp-proxy

> Discover how MetaMCP integrates with Claude Desktop using mcp-proxy. Learn how this local bridge converts JSON-RPC messages enabling stdio-only clients to access remote MCP servers.

- Repository: [metatool-ai/metamcp](https://github.com/metatool-ai/metamcp)
- Tags: how-to-guide
- Published: 2026-03-07

---

**MetaMCP integrates with Claude Desktop by running `mcp-proxy` as a local stdio-to-HTTP bridge that converts Claude's JSON-RPC messages into streamable HTTP or SSE requests to MetaMCP's remote endpoints, enabling stdio-only clients to access remote MCP servers.**

The `metatool-ai/metamcp` repository aggregates multiple MCP (Model Context Protocol) servers behind a unified interface, but Claude Desktop only supports stdio transport. This guide explains the technical architecture behind MetaMCP Claude Desktop integration, detailing how the `mcp-proxy` executable bridges the protocol gap.

## The Protocol Architecture

Claude Desktop operates as a **stdio-only** MCP client, reading JSON-RPC messages from STDIN and writing responses to STDOUT. MetaMCP, however, exposes **remote-only** endpoints using **streamable HTTP** or **Server-Sent Events (SSE)** transports.

The `mcp-proxy` process resolves this mismatch by acting as a bidirectional translator. When Claude Desktop launches the proxy via its `mcpServers` configuration, the proxy maintains a persistent stdio connection with Claude while forwarding requests to MetaMCP's HTTP endpoints. Each MCP request—whether `tools/list`, `tools/call`, or resource discovery—travels through this local bridge to reach the remote MetaMCP server.

## Core Proxy Implementation

### Unified Server Composition

The aggregation logic resides in [`apps/backend/src/lib/metamcp/metamcp-proxy.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/lib/metamcp/metamcp-proxy.ts), where the system instantiates a unified MCP `Server` from the official MCP SDK. This server registers request handlers for `ListToolsRequestSchema` and `CallToolRequestSchema`, wrapping them with middleware for caching and override filtering.

```typescript
// apps/backend/src/lib/metamcp/metamcp-proxy.ts
const server = new Server(
  { name: `metamcp-unified-${namespaceUuid}`, version: "1.0.0" },
  { capabilities: { prompts: {}, resources: {}, tools: {} } },
);

server.setRequestHandler(ListToolsRequestSchema, async (request) => {
  return await listToolsWithMiddleware(request, handlerContext);
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  return await callToolWithMiddleware(request, handlerContext);
});

```

### Request Dispatching to Remote Servers

When Claude Desktop invokes a tool, the proxy executes `originalCallToolHandler` or `originalListToolsHandler` to locate the target MCP server. The system queries `getMcpServers` to identify the correct upstream endpoint, then acquires a session via `mcpServerPool.getSession`. The request forwards through `session.client.request`, which translates the stdio JSON-RPC into an HTTP POST or SSE event to `http://localhost:12008/metamcp/<endpoint-name>/mcp`.

### Circular Reference Protection

To prevent infinite loops, the proxy implements the `isSameServerInstance` guard within [`metamcp-proxy.ts`](https://github.com/metatool-ai/metamcp/blob/main/metamcp-proxy.ts). This check ensures that if MetaMCP itself is configured as a downstream MCP endpoint, the proxy will not route requests back to the originating server, avoiding recursive tool calls.

## HTTP Infrastructure and Routing

### Backend Route Exposure

The Express-style router in [`apps/backend/src/routers/mcp-proxy/server.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/routers/mcp-proxy/server.ts) mounts the proxy handlers under the `/mcp-proxy/*` path. This allows the Next.js frontend to communicate with the proxy service through a consistent URL structure, handling both HTTP POST requests for streamable transport and SSE connections for event-based messaging.

### Frontend Proxy Configuration

To avoid CORS issues and provide seamless browser access, [`apps/frontend/next.config.js`](https://github.com/metatool-ai/metamcp/blob/main/apps/frontend/next.config.js) implements rewrite rules that forward all `/mcp-proxy/:path*` requests to the backend service:

```javascript
// apps/frontend/next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: "/mcp-proxy/:path*",
        destination: `${process.env.BACKEND_URL}/mcp-proxy/:path*`,
      },
    ];
  },
};

```

## Configuring Claude Desktop for MetaMCP

### Streamable HTTP Transport Setup

To connect Claude Desktop to MetaMCP using the HTTP transport, add the following configuration to [`claude_desktop_config.json`](https://github.com/metatool-ai/metamcp/blob/main/claude_desktop_config.json) (located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "MetaMCP": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "http://localhost:12008/metamcp/your-endpoint-name/mcp"
      ],
      "env": {
        "API_ACCESS_TOKEN": "sk_mt_your_api_key_here"
      }
    }
  }
}

```

The `uvx` runner executes `mcp-proxy` without global installation, while `--transport streamablehttp` specifies the HTTP POST-based protocol. The `API_ACCESS_TOKEN` environment variable authenticates requests against MetaMCP's access control layer.

### SSE Alternative Configuration

For environments requiring persistent connections, use the default SSE transport by omitting the `--transport` flag:

```json
{
  "mcpServers": {
    "MetaMCP": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "http://localhost:12008/metamcp/your-endpoint-name/sse"
      ],
      "env": {
        "API_ACCESS_TOKEN": "sk_mt_your_api_key_here"
      }
    }
  }
}

```

This configuration maintains an open event-stream connection, suitable for real-time tool updates and long-running operations.

## Summary

- **Protocol Translation**: `mcp-proxy` bridges Claude Desktop's stdio transport with MetaMCP's remote HTTP/SSE endpoints, enabling bidirectional JSON-RPC communication.
- **Unified Aggregation**: The [`metamcp-proxy.ts`](https://github.com/metatool-ai/metamcp/blob/main/metamcp-proxy.ts) file implements a unified MCP server that aggregates multiple remote endpoints using middleware for caching and request routing.
- **Safety Mechanisms**: The `isSameServerInstance` guard prevents circular references when MetaMCP is chained with other MCP servers.
- **Configuration**: Claude Desktop requires `uvx mcp-proxy` entries in [`claude_desktop_config.json`](https://github.com/metatool-ai/metamcp/blob/main/claude_desktop_config.json), specifying either `streamablehttp` or SSE transports with valid `API_ACCESS_TOKEN` credentials.
- **Infrastructure**: Next.js rewrites in [`next.config.js`](https://github.com/metatool-ai/metamcp/blob/main/next.config.js) and Express routes in [`apps/backend/src/routers/mcp-proxy/server.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/routers/mcp-proxy/server.ts) expose the proxy through `/mcp-proxy/*` endpoints.

## Frequently Asked Questions

### What is mcp-proxy and why is it required for MetaMCP?

**`mcp-proxy`** is a lightweight executable that translates between stdio and HTTP/SSE transports. Claude Desktop only supports stdio communication, while MetaMCP exposes remote HTTP endpoints. Without the proxy, Claude Desktop cannot natively connect to MetaMCP's networked architecture, as the two systems use incompatible transport protocols.

### How does MetaMCP prevent circular references when proxying?

MetaMCP implements the **`isSameServerInstance`** guard in [`apps/backend/src/lib/metamcp/metamcp-proxy.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/lib/metamcp/metamcp-proxy.ts). This function checks whether a target MCP server shares the same instance identifier as the current MetaMCP process. If detected, the proxy blocks the request to prevent infinite loops where MetaMCP would attempt to call itself through the proxy chain.

### Can I use MetaMCP with other stdio-only clients besides Claude Desktop?

Yes. Any stdio-only MCP client—including **Cursor**, **Zed**, or custom CLI tools—can integrate with MetaMCP using the same `mcp-proxy` configuration pattern. As long as the client supports the standard MCP stdio protocol and can launch the `uvx mcp-proxy` command, it can access MetaMCP's aggregated remote endpoints.

### What transport protocols does MetaMCP support through mcp-proxy?

MetaMCP supports both **streamable HTTP** (`--transport streamablehttp`) and **Server-Sent Events (SSE)**. Streamable HTTP uses POST requests for bidirectional communication, while SSE maintains a persistent event-stream connection. The proxy automatically handles protocol selection based on the `--transport` flag or defaults to SSE when connecting to endpoints ending in `/sse`.