> For the complete documentation index, see [llms.txt](https://docs.spice.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spice.ai/api/runtime-apis/mcp.md). # MCP API The MCP API exposes an app's configured tools over the [Model Context Protocol](https://modelcontextprotocol.io/) using the Streamable HTTP transport. MCP clients — including AI coding agents — connect to the app's runtime, list the tools it serves, and call them to query the app's datasets and models. {% hint style="info" %} **Runtime Endpoint:** These endpoints are served by your Spice runtime instance (e.g. `https://.spiceai.io`), not the Management API (`https://api.spice.ai`). Authenticate with your **app API key**, not a Personal Access Token. {% endhint %} {% hint style="warning" %} The MCP API requires Spice runtime **v2.0.0 or later**. See [Spice Runtime Versions](https://github.com/spicehq/docs/tree/trunk/cloud/portal/app-spicepod/spice-runtime-versions.md). {% endhint %} Which tools an app exposes depends on the `tools` configured in its spicepod. See [Model Context Protocol (MCP)](https://docs.spiceai.org/features/large-language-models/mcp) for tool configuration. ## Send an MCP message `POST` `https://.spiceai.io/v1/mcp` Sends a JSON-RPC message to the app's MCP server. ### Headers | Header | Type | Description | | ---------------- | ------ | ----------------------------------------------------------------------------------------------------- | | `X-API-Key` | string | Your app API key | | `Content-Type` | string | `application/json` | | `Accept` | string | `application/json` for a single JSON-RPC response, or `text/event-stream` to receive an SSE stream | | `Mcp-Session-Id` | string | Session identifier returned by the server on `initialize`. Required on every request that follows it. | ### Responses | Status | Description | | ------ | ------------------------------------------------------------------------------------------------------------------------ | | `200` | JSON-RPC response, returned as `application/json` or as `text/event-stream` when the server streams additional messages. | | `202` | Message accepted. Returned for notifications and responses that do not require a reply. | | `400` | Malformed JSON-RPC payload. | | `404` | Unknown or expired `Mcp-Session-Id`. | | `413` | Payload too large. The maximum message size is 32 MiB. | ```bash curl -X POST https://.spiceai.io/v1/mcp \ -H "X-API-Key: " \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }' ``` ## Open a server-to-client stream `GET` `https://.spiceai.io/v1/mcp` Opens a long-lived server-to-client SSE stream for an existing session, as defined by the Streamable HTTP transport. ### Headers | Header | Type | Description | | ---------------- | ------ | -------------------------------------------------------------------- | | `X-API-Key` | string | Your app API key | | `Mcp-Session-Id` | string | Session identifier of a session created by `POST /v1/mcp`. Required. | ### Responses | Status | Description | | ------ | ------------------------------------------------------------------- | | `200` | SSE stream (`text/event-stream`) of server-originated MCP messages. | | `404` | Unknown or expired `Mcp-Session-Id`. | ## Connect an AI coding agent The portal generates the registration command for an app. Open the app, select **Settings**, then **Endpoints**, and use **Connect an AI coding agent**. Keep the app API key in an environment variable rather than writing it into a command or a config file: ```bash export SPICE_API_KEY= ``` ### Claude Code ```bash claude mcp add --transport http spice https://.spiceai.io/v1/mcp \ --header "X-API-Key: $SPICE_API_KEY" ``` ### Codex `codex mcp add` registers stdio servers only, so declare the Streamable HTTP server in `~/.codex/config.toml`. The `env_http_headers` value names the environment variable to read, not the key itself: ```toml [mcp_servers.spice] url = "https://.spiceai.io/v1/mcp" env_http_headers = { "X-API-Key" = "SPICE_API_KEY" } ``` ### Grok CLI ```bash grok mcp add --transport http spice https://.spiceai.io/v1/mcp \ --header "X-API-Key: $SPICE_API_KEY" ``` {% hint style="info" %} Spice Cloud apps need no `runtime.mcp.allowed_hosts` configuration. The app's own hostname is allow-listed when the app is deployed, and any entries set in the spicepod for local development are kept. {% endhint %} See also: * [MCP Server recipe](https://github.com/spiceai/cookbook/tree/trunk/mcp-server) — using Spice as an MCP server. * [App API Keys](https://github.com/spicehq/docs/tree/trunk/cloud/portal/apps/api-keys.md) — creating and rotating app API keys. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.spice.ai/api/runtime-apis/mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.