MCP Gateway

Last updated 2026-10-06·Reviewed against Prism v0.3.26

Why route MCP through Prism

Endpoints

# Every enabled server
POST http://127.0.0.1:11434/mcp
Authorization: Bearer prism
Content-Type: application/json

# One agent's allowlist only
POST http://127.0.0.1:11434/mcp/claude-code
Authorization: Bearer prism

The whole gateway sits behind the same token as the rest of the proxy, so Authorization: Bearer prism and x-api-key: prism both work. Agent ids are the same 14 ids Prism uses in the Agents tab, such as claude-code, codex or zed.

Supported methods

Prism identifies itself as the server prism version 1.0.0, and tells the agent that tool names follow the mcp__<server>__<tool> convention.

Tool namespacing

Two servers can both expose a tool called search. To keep them distinguishable, Prism prefixes every tool name with its server id.

Upstream servers                 What the agent sees
────────────────                 ───────────────────
weather    → get_forecast        mcp__weather__get_forecast
github     → search              mcp__github__search
filesystem → read_file           mcp__filesystem__read_file

Server ids are whatever you named the server in Prism — which the marketplace prefills from the registry entry. Only the first __ after the server id splits the name, so upstream tool names that contain double underscores still route correctly.

Transports

For stdio servers, Prism resolves the command from your PATH and then from the places a GUI process does not inherit — /opt/homebrew/bin, ~/.local/bin, ~/.npm-global/bin, ~/.cargo/bin, ~/go/bin and the platform npm config directory. On Windows, .cmd and .bat shims such as npx are run through cmd.exe, which exec cannot do directly.

Authentication to upstream servers

Brokered OAuth

With oauth, Prism discovers the server's authorization server, registers a client, opens your browser for consent, and stores the access and refresh tokens in config.json with file mode 0600. Tokens are refreshed automatically 60 seconds before expiry, and an upstream 401 triggers a refresh attempt before the call is retried.

Prism supports three registration modes and caches a registered client per authorization server, so a second MCP server on the same provider reuses the existing registration instead of registering again.

Add an MCP server

The marketplace

Prism ships with the official registry (registry.modelcontextprotocol.io) seeded and searches its catalog locally, so typing in the search box is instant and works offline once synced. Any registry that speaks the same OpenAPI shape can be added as an extra source — a private or company catalog becomes a drop-in addition rather than a separate client.

Per-agent access

Access is an allowlist per agent. An agent reaching /mcp/<agent> sees only its own servers, and a tools/call for a server outside that list is rejected with "server is not enabled for this endpoint". The unrestricted /mcp endpoint reaches every enabled server.

Prism writes the gateway entry into each agent's own MCP config file:

Limits and lifecycle

Remote HTTP and SSE servers are left connected because keeping them costs nothing; only child processes are reaped. Changing the idle timeout in the MCP tab sets idle_timeout_sec.

Server states

Configuration

{
  "mcp": {
    "servers": [
      {
        "id": "weather",
        "name": "Weather",
        "transport": "stdio",
        "enabled": true,
        "command": "npx",
        "args": ["-y", "@example/weather-mcp"],
        "env": { "WEATHER_API_KEY": "..." },
        "auth_mode": "none"
      },
      {
        "id": "linear",
        "name": "Linear",
        "transport": "http",
        "url": "https://mcp.linear.app/mcp",
        "enabled": true,
        "auth_mode": "oauth"
      }
    ],
    "agent_servers": {
      "claude-code": ["weather", "linear"],
      "zed": ["weather"]
    },
    "idle_timeout_sec": 300,
    "auto_connect": true,
    "registries": [
      { "id": "official", "name": "Official MCP Registry", "base_url": "https://registry.modelcontextprotocol.io", "enabled": true, "builtin": true }
    ]
  }
}