Skip to content

Commit ae6d09f

Browse files
Claudelukekim
Claude
authored and
lukekim
committed
docs(cloud): add the MCP API reference for Spice Cloud apps
1 parent 0d93ad8 commit ae6d09f

3 files changed

Lines changed: 120 additions & 0 deletions

File tree

‎cloud/api/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Runtime APIs are served at `https://data.spiceai.io` and authenticated with [App
1919
| Text-to-SQL | `POST /v1/nsql` | [Text-to-SQL API](nsql.md) |
2020
| Text-to-SQL context | `GET /v1/nsql/context` | [Text-to-SQL API](nsql.md) |
2121
| Search | `POST /v1/search` | [Search API](search.md) |
22+
| MCP | `POST /v1/mcp` | [MCP API](mcp.md) |
2223
| Health | `GET /health` | [Health API](health.md) |
2324
| Metrics | `GET /v1/metrics` | [Metrics API](metrics.md) |
2425

‎cloud/api/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
* [LLM API](openai-api.md)
1111
* [Text-to-SQL API](nsql.md)
1212
* [Search API](search.md)
13+
* [MCP API](mcp.md)
1314
* [Health API](health.md)
1415
* [Metrics API](metrics.md)
1516

‎cloud/api/mcp.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
description: Connect MCP clients and AI coding agents to a Spice app
3+
icon: plug
4+
---
5+
6+
# MCP API
7+
8+
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.
9+
10+
{% hint style="info" %}
11+
**Runtime Endpoint:** These endpoints are served by your Spice runtime instance (e.g. `https://<app-cname>.spiceai.io`), not the Management API (`https://api.spice.ai`). Authenticate with your **app API key**, not a Personal Access Token.
12+
{% endhint %}
13+
14+
{% hint style="warning" %}
15+
The MCP API requires Spice runtime **v2.0.0 or later**. See [Spice Runtime Versions](../portal/app-spicepod/spice-runtime-versions.md).
16+
{% endhint %}
17+
18+
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.
19+
20+
## Send an MCP message
21+
22+
<mark style="color:blue;">`POST`</mark> `https://<app-cname>.spiceai.io/v1/mcp`
23+
24+
Sends a JSON-RPC message to the app's MCP server.
25+
26+
### Headers
27+
28+
| Header | Type | Description |
29+
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------- |
30+
| `X-API-Key` | string | Your app API key |
31+
| `Content-Type` | string | `application/json` |
32+
| `Accept` | string | `application/json` for a single JSON-RPC response, or `text/event-stream` to receive an SSE stream |
33+
| `Mcp-Session-Id` | string | Session identifier returned by the server on `initialize`. Required on every request that follows it. |
34+
35+
### Responses
36+
37+
| Status | Description |
38+
| ------ | --------------------------------------------------------------------------------------- |
39+
| `200` | JSON-RPC response, returned as `application/json` or as `text/event-stream` when the server streams additional messages. |
40+
| `202` | Message accepted. Returned for notifications and responses that do not require a reply. |
41+
| `400` | Malformed JSON-RPC payload. |
42+
| `404` | Unknown or expired `Mcp-Session-Id`. |
43+
| `413` | Payload too large. The maximum message size is 32 MiB. |
44+
45+
```bash
46+
curl -X POST https://<app-cname>.spiceai.io/v1/mcp \
47+
-H "X-API-Key: <app-api-key>" \
48+
-H "Content-Type: application/json" \
49+
-H "Accept: application/json, text/event-stream" \
50+
-d '{
51+
"jsonrpc": "2.0",
52+
"id": 1,
53+
"method": "tools/list"
54+
}'
55+
```
56+
57+
## Open a server-to-client stream
58+
59+
<mark style="color:blue;">`GET`</mark> `https://<app-cname>.spiceai.io/v1/mcp`
60+
61+
Opens a long-lived server-to-client SSE stream for an existing session, as defined by the Streamable HTTP transport.
62+
63+
### Headers
64+
65+
| Header | Type | Description |
66+
| ---------------- | ------ | ---------------------------------------------------------------------- |
67+
| `X-API-Key` | string | Your app API key |
68+
| `Mcp-Session-Id` | string | Session identifier of a session created by `POST /v1/mcp`. Required. |
69+
70+
### Responses
71+
72+
| Status | Description |
73+
| ------ | -------------------------------------------------------------------- |
74+
| `200` | SSE stream (`text/event-stream`) of server-originated MCP messages. |
75+
| `404` | Unknown or expired `Mcp-Session-Id`. |
76+
77+
## Connect an AI coding agent
78+
79+
The portal generates the registration command for an app. Open the app, select **Settings**, then **Endpoints**, and use **Connect an AI coding agent**.
80+
81+
Keep the app API key in an environment variable rather than writing it into a command or a config file:
82+
83+
```bash
84+
export SPICE_API_KEY=<app-api-key>
85+
```
86+
87+
### Claude Code
88+
89+
```bash
90+
claude mcp add --transport http spice https://<app-cname>.spiceai.io/v1/mcp \
91+
--header "X-API-Key: $SPICE_API_KEY"
92+
```
93+
94+
### Codex
95+
96+
`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:
97+
98+
```toml
99+
[mcp_servers.spice]
100+
url = "https://<app-cname>.spiceai.io/v1/mcp"
101+
env_http_headers = { "X-API-Key" = "SPICE_API_KEY" }
102+
```
103+
104+
### Grok CLI
105+
106+
```bash
107+
grok mcp add --transport http spice https://<app-cname>.spiceai.io/v1/mcp \
108+
--header "X-API-Key: $SPICE_API_KEY"
109+
```
110+
111+
{% hint style="info" %}
112+
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.
113+
{% endhint %}
114+
115+
See also:
116+
117+
* [MCP Server recipe](https://github.com/spiceai/cookbook/tree/trunk/mcp-server) — using Spice as an MCP server.
118+
* [App API Keys](../portal/apps/api-keys.md) — creating and rotating app API keys.

0 commit comments

Comments
 (0)