MCP gateway for AI agents, tools, and live data

How does Spice work as an MCP gateway?

An MCP gateway sits between AI clients and the MCP servers that provide their tools. Clients connect to one endpoint instead of to each server. Spice fills this role with the same runtime that federates and accelerates SQL queries, so the gateway also serves data. The Model Context Protocol guide explains the protocol itself. In Spice, a request moves through four steps:

1. Declare: the tools section of spicepod.yaml lists each upstream MCP server. from: mcp:npx, mcp:uvx, or mcp:docker runs a stdio server as a subprocess, and from: mcp:https://... connects to a remote server over Streamable HTTP.
2. Connect: at startup, Spice connects to each server, lists its tools, and names each proxied tool <tool-name>__<upstream-tool-name>. A double underscore separates the parts because MCP clients reject tool names with a /.
3. Serve: Spice exposes the combined catalog, plus its built-in sql, list_datasets, table_schema, and search tools, at /v1/mcp over Streamable HTTP.
4. Call: a model running in Spice calls the tools named in its tools parameter. An external MCP client calls the tools at /v1/mcp with an API key.

The following Spicepod proxies GitHub's maintained GitHub MCP server in Docker, accelerates the repository's issues for SQL, and gives one model access to both:

version: v1
kind: Spicepod
name: mcp-gateway

runtime:
  auth:
    api_key:
      enabled: true
      keys:
        - ${secrets:SPICE_API_KEY}

datasets:
  - from: github:github.com/your-org/your-repo/issues
    name: github_issues
    params:
      github_token: ${secrets:GITHUB_PERSONAL_ACCESS_TOKEN}
    acceleration:
      enabled: true

tools:
  - name: github
    from: mcp:docker
    description: GitHub tools to manage issues, review PRs, and search code
    params:
      mcp_args: run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: ${secrets:GITHUB_PERSONAL_ACCESS_TOKEN}

models:
  - name: triage
    from: openai:gpt-4o
    params:
      openai_api_key: ${secrets:OPENAI_API_KEY}
      tools: github, sql, table_schema, list_datasets

To connect Claude Code to the same gateway, pass a key from runtime.auth:

claude mcp add --transport http spice http://localhost:8090/v1/mcp --header "X-API-KEY: <key>"

The MCP documentation has the full configuration reference, and the Spice as MCP Server cookbook recipe is a runnable version of the same pattern.

Which MCP connection types does Spice support?

Spice supports two transports when it connects to an MCP server, and one when it serves tools. The three roles compare as follows:

Spice v2.0 and later use Streamable HTTP for remote connections. Spice v1.11 and earlier used the older HTTP with Server-Sent Events (SSE) transport. Because /v1/mcp is itself an MCP server, one Spice instance can proxy another by setting from: mcp:https://<other-instance>/v1/mcp. The other instance requires an API key, so pass it with mcp_headers: 'X-API-KEY: ${secrets:SPICE_API_KEY}' or as a bearer token with mcp_auth_token.

How does Spice control which tools a model can call?

A model can call only the tools in its tools parameter, and that parameter accepts tool names, tool groups, or both. Tool access is set per model in the Spicepod, so two models in the same runtime can see different tools:

The tool registry matters for gateways with many MCP servers. A typical tool definition is 200 to 500 tokens, so 50 tools add 10,000 to 25,000 tokens to every chat turn. With the registry, the model searches for tools and sees only the schemas it asks for, which the docs measure at about one-tenth of the tool-definition tokens for a 50-tool catalog. tool_recursion_limit in a model's params, 10 by default, limits how deep a chain of tool calls can recurse within one request. For the wider set of agent controls, see secure AI agents.

What does exposing /v1/mcp require?

Four settings control who can reach /v1/mcp and what its tools can do. Plan for each one before other systems connect to the endpoint:

• API key authentication: /v1/mcp returns 401 Unauthorized to every request, including local ones, until runtime.auth is configured. This requirement applies from Spice v2.2.
• An allowed host list: by default, /v1/mcp accepts only requests whose Host header is localhost, 127.0.0.1, or ::1, which blocks DNS rebinding attacks. Requests to any other host name return 403 Forbidden until that host is added to runtime.mcp.allowed_hosts. This applies to self-hosted runtimes: a Spice Cloud project allow-lists its own hostname when it deploys.
• Secrets from a secret store: ${secrets:...} references resolve tokens for upstream servers from a secret store instead of plain text in the Spicepod.
• Read-only SQL by default: the sql tool accepts write statements only when the request uses a ReadWrite API key and the target dataset sets access: read_write. Otherwise, it runs as read-only.

To run the gateway as a managed service, compare Spice Cloud and Enterprise plans.