[claudespice]

Summary

The published HTTP API reference documents the MCP endpoint at a path that has not existed since v2.0.0:

	Documented (before)	Actual runtime
Path	/v1/mcp/sse	/v1/mcp
Operations	GET "Establish an MCP SSE Connection", POST "Send message to MCP server"	GET mcp_stream, POST mcp_message, DELETE mcp_terminate_session

crates/runtime/src/http/routes.rs mounts an rmcp StreamableHttpService at /v1/mcp and documents three operations there. The comment in source is explicit:

Streamable HTTP transport endpoint per MCP 2025-11-25 spec. This replaces the legacy SSE transport that was removed in rmcp 1.x.

A client following the reference would POST to /v1/mcp/sse and get a 404, and the DELETE session-termination operation was entirely undocumented.

The prose docs are already correct — features/large-language-models/mcp.md, components/tools/mcp.md, and reference/spicepod/runtime.md all say /v1/mcp. Only the OpenAPI-derived reference was stale, because website/public/openapi.json was last refreshed for spiceai/spiceai#10272 and still carried the SSE-era spec.

What changed

• website/public/openapi.json: replaced the /v1/mcp/sse path object with the runtime's /v1/mcp object (three operations, verbatim from spiceai/spiceai@trunk .schema/openapi.json; no $refs, so no schema changes were needed).
• Regenerated with npx docusaurus gen-api-docs spice → new mcp-stream, mcp-message, mcp-terminate-session pages; deleted the stale operation-id.* and mcp-event.* pages; updated the mcp category in the generated sidebar.ts.
• The regenerated sidebar.ts block was verified byte-identical to what a full clean-api-docs + gen-api-docs emits, so the hand-applied sidebar edit matches plugin output. Unrelated operations' base64 api: blobs are untouched (a full clean+regen rewrites all of them non-deterministically; avoided deliberately to keep the diff reviewable).

Version scope

/v1/mcp/sse was correct through v1.11.x and wrong from v2.0.0 onward, so this is a version-specific change fixed at and after the release that introduced the new path:

Snapshot	MCP route in that release	Action
website/docs/ (vNext)	/v1/mcp	fixed
version-2.1.x	/v1/mcp (verified at tag v2.1.1)	fixed
version-2.0.x	/v1/mcp (verified at tag v2.0.0)	fixed
version-1.11.x and older	/v1/mcp/sse (verified at tag v1.11.6)	unchanged — correct as-is

The v2.0.0 and v2.1.1 route tables are identical to trunk's (same three operations, same runtime.mcp.allowed_hosts 403 text, same 32 MiB body limit), so the regenerated pages are accurate for both snapshots. Versioned API pages in this repo are byte-identical copies of the vNext ones (verified against get-catalogs.api.mdx / list-tools.api.mdx), so they were propagated by copy, matching how the snapshots were originally cut.

After the sweep, grep -rln 'v1/mcp/sse' website/ returns only version-1.5.x–version-1.11.x pages plus the historical releases/v1.1.0.md blog post — all correct for their versions.

Source refs

• spiceai/spiceai@trunk crates/runtime/src/http/routes.rs — nest_service("/v1/mcp", mcp_service) + the three documented operations
• spiceai/spiceai@trunk .schema/openapi.json — /v1/mcp with mcp_stream / mcp_message / mcp_terminate_session
• Tags checked: v1.11.6 (/v1/mcp/sse), v2.0.0 and v2.1.1 (/v1/mcp)

Test plan

• cd website && npm run build passes (with the versioned propagation in place)
• Versioned-docs propagation checked — vNext + 2.1.x + 2.0.x fixed; 1.x intentionally unchanged; post-sweep grep documented above
• Files updated: 55

[github-actions]

✅ Pull with Spice Passed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected
• ✅ Has at least one assignee: claudespice

[claudespice]

Heads-up on the red Generate API Docs check: it is a pre-existing repo failure, not caused by this PR. The updated_openapi.yml workflow (which triggers on any website/public/openapi.json change, wipes website/docs/api/HTTP/*, regenerates, and commits the result back) dies in its Install dependencies step:

npm error `npm ci` can only install packages when your package.json and package-lock.json ... are in sync.
npm error Missing: yaml@2.9.0 from lock file

website/package.json and website/package-lock.json are untouched by this branch (git diff origin/trunk -- website/package.json website/package-lock.json is empty), and the workflow's last green run was months ago (jeadie/openapi-10272), so the lockfile drifted on trunk at some point after that — most likely during a dependency bump. Because the workflow only fires on openapi.json changes, nothing surfaced it until now.

Practical consequence: the bot cannot regenerate the API MDX for this PR, so the generated pages in the diff were produced locally with npx docusaurus gen-api-docs spice and hand-verified (see the PR description). Deploy — the check that actually validates the built site — passes.

Worth a separate npm install lockfile-refresh PR to unblock the bot; happy to open one if you'd like.

[github-actions]

🚀 deployed to https://835b4bce.spiceai-org-website.pages.dev

[github-actions]

🚀 deployed to https://2485106b.spiceai-org-website.pages.dev