MCP API

Connect MCP clients and AI coding agents to a Spice project

The MCP API exposes a project's configured tools over the Model Context Protocol using the Streamable HTTP transport. MCP clients, including AI coding agents, connect to the project's runtime, list the tools it serves, and call them to query the project's datasets and models.

Which tools a project exposes depends on the tools configured in its spicepod. See Model Context Protocol (MCP) for tool configuration.

Send an MCP message

POST https://<project-cname>.spiceai.io/v1/mcp

Sends a JSON-RPC message to the project's MCP server.

Headers

Header	Type	Description
`X-API-Key`	string	Your project 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.

curl -X POST "https://<project-cname>.spiceai.io/v1/mcp" \
  -H "X-API-Key: <project-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://<project-cname>.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 project 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 a project. Open the project, select Settings, then Endpoints, and use Connect an AI coding agent.

Keep the project API key in an environment variable rather than writing it into a command or a config file:

export SPICE_API_KEY="<project-api-key>"

Claude Code

claude mcp add --transport http spice "https://<project-cname>.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:

[mcp_servers.spice]
url = "https://<project-cname>.spiceai.io/v1/mcp"
env_http_headers = { "X-API-Key" = "SPICE_API_KEY" }

Grok CLI

grok mcp add --transport http spice "https://<project-cname>.spiceai.io/v1/mcp" \
  --header "X-API-Key: $SPICE_API_KEY"