Modules / AI and operations
MCP server
Expose workspace tools to MCP clients over Streamable HTTP.
Setup and configuration
POST /api/mcp is a stateless Streamable HTTP MCP endpoint built on @modelcontextprotocol/sdk. Authentication is API keys only — the same sk_ keys and scopes as the public /api/v1 REST API. Cookie sessions never apply; missing or invalid keys get a 401 with a Bearer challenge, and GET/DELETE return 405.
The endpoint registers only the tools the key's scopes allow from the shared workspace-tool registry (get_workspace, list_entitlements, create_ai_task, get_ai_task, get_ai_task_result). Every call reuses the /api/v1 BFF with the caller's headers, so REST authorization, workspace checks, and scope enforcement are identical — the MCP surface never widens access.
{
"mcpServers": {
"supastack": {
"url": "https://<app>/api/mcp",
"headers": {
"Authorization": "Bearer sk_..."
}
}
}
}Implementation workflow
Issue a scoped key from Settings → Developers (or the API-keys flow) and hand the client the Authorization header shown above. A read-only key sees only read tools; write tools such as create_ai_task appear only for keys with the write scope.
The endpoint shares the /api/v1 rate limiter. Tool results are JSON text content; workspace errors surface as isError results with the REST error message — no stack traces or secrets cross the boundary.
Verification and troubleshooting
Drive initialize → tools/list → tools/call against the handler in tests with a fake registry before touching production keys. Verify a read-scoped key cannot see write tools and that requests without Authorization are rejected even when a session cookie is present.