title: 'Model Context Protocol (MCP)' sidebar_label: 'MCP' description: 'Learn how to use the Model Context Protocol (MCP) with Spice.' sidebar_position: 2 pagination_prev: null pagination_next: null tags:
The Model Context Protocol (MCP) helps integrate external tools and services into the Spice runtime. MCP tools can be run internally or connected over HTTP using the Streamable HTTP (opens in a new tab) transport.
MCP enables Spice to:
This flexibility helps extend the capabilities of language models by providing access to external tools and services.
To configure MCP tools, define them in the tools section of your spicepod.yaml file. The from field specifies the transport mechanism (e.g., mcp:npx for stdio or an HTTP URL for Streamable HTTP).
Once configured, MCP tools can be assigned to models via the tools parameter.
Spice can also act as an MCP server, exposing its tools over Streamable HTTP. This enables other Spice instances or external systems to connect and use the tools.
The /v1/mcp endpoint requires runtime.auth (opens in a new tab) to be configured. Without it, every request is rejected with 401 Unauthorized, including requests from local clients:
Clients then authenticate with an X-API-KEY header.
Because the remote endpoint requires authentication, pass credentials with mcp_headers — or mcp_auth_token to send Authorization: Bearer. See Connecting to an Auth-Enabled MCP Server (opens in a new tab).
By default the /v1/mcp endpoint only accepts requests with a Host header matching localhost, 127.0.0.1, or ::1 to prevent DNS rebinding attacks. To allow additional hosts, configure runtime.mcp.allowed_hosts (opens in a new tab):
Set allowed_hosts: ["*"] to disable host checking entirely.
fromThe from field specifies the transport mechanism for the MCP tool:
http://localhost:8090/v1/mcp).mcp:npx or mcp:docker. Additional arguments can be passed via params.mcp_args.paramsThe params field provides additional configuration for MCP tools. For stdio-based tools, use mcp_args to specify command-line arguments.
envFor stdio-based MCP tools, environment variables can be set using the env field.
For more details, see the MCP Tools Reference (opens in a new tab).
Spice can act as a unified MCP gateway, proxying multiple external MCP servers alongside its own built-in tools. Clients connect to a single /v1/mcp endpoint and see one combined tool catalog.
With this configuration, clients connecting to /v1/mcp see a single catalog that includes:
sql, list_datasets, table_schema, search, and moregithub__create_issue, github__list_pull_requests, github__search_code, and morejira__jira_get_issue, jira__jira_search, jira__jira_create_issue, and moreA proxied tool is exposed as <tool-name>__<upstream-tool-name>, joined by a double underscore. The tool-name is the name given in the tools section, so renaming the tool renames every tool it proxies.
The separator is not a /, because MCP clients such as Claude and Cursor reject any tool name that does not match ^[a-zA-Z0-9_-]{1,64}$.
Where an upstream server already namespaces its own tools, the prefix appears doubled — mcp-atlassian exposes jira_get_issue, so a tool named jira yields jira__jira_get_issue. This is expected.
The jira tool contributes no tools at all unless all three JIRA_* values resolve. mcp-atlassian starts successfully without them, registers nothing, and Spice logs no tool-loading error — the runtime reports healthy with Jira silently missing from the catalog. Check the startup log for runtime_secrets errors if jira__* tools do not appear.
JIRA_URL depends on which kind of API token is used, and a mismatch is the most common cause of an empty Jira catalog:
| Token type | JIRA_URL |
|---|---|
| Classic (unscoped) API token | https://your-org.atlassian.net |
| Scoped API token | https://api.atlassian.com/ex/jira/<cloud-id> |
Scoped tokens authenticate only against the api.atlassian.com gateway and return 401 against the site URL. Retrieve the cloud ID for a site from https://your-org.atlassian.net/_edge/tenant_info, which requires no authentication. Both token types use JIRA_USERNAME (the account email address) with HTTP basic auth.
Connect Claude Code to this gateway with a single command, using a key from runtime.auth:
:::warning Large tool catalogs
The two servers above expose close to 100 tools between them, which degrades tool selection in most MCP clients. Restrict each server to the tools actually needed — for mcp-atlassian, set TOOLSETS in its env block.
:::
See the mcp-server cookbook (opens in a new tab) for a complete runnable example.
A failing MCP server does not stop the runtime. Spice logs a warning, retries the connection in the background, and reports healthy — the tool is simply absent from tools/list. Verify the runtime log at startup:
A server that starts but authenticates with empty or invalid credentials is harder to spot: it registers zero tools without producing that warning. Check for runtime_secrets errors, which indicate a ${secrets:...} reference that did not resolve.
401/v1/mcp requires runtime.auth (opens in a new tab). The response body names the missing configuration:
403The Host header is not in runtime.mcp.allowed_hosts (opens in a new tab). This is the DNS-rebinding guard, and it applies to any host other than localhost, 127.0.0.1, or ::1.
To confirm what a client actually sees, call tools/list over the Streamable HTTP transport. The Accept header must offer both content types, and the session ID returned by initialize is required on subsequent requests:
Responses are returned as SSE frames prefixed with data:.