--- summary: "MCP server for ScaiGrid \u2014 exposes inference, sessions, rooms, accounting,\ \ IAM, and module operations as Model Context Protocol tools." title: ScaiMCP path: overview status: published --- ScaiMCP is the Model Context Protocol server that fronts ScaiGrid. MCP-aware clients — Claude Desktop, Cursor, custom agents — connect to one endpoint and get the whole gateway as a typed tool catalog, with the same auth, permissions, and accounting as the REST API. Under the hood it is a ScaiGrid module that registers tool definitions, mounts an MCP-over-HTTP transport, and resolves every call through the same `CurrentUser` your REST endpoints see. ## When to use it - You want an AI agent (Claude Desktop, a Cursor workflow, a custom LangGraph runner) to call ScaiGrid features directly — chat, embeddings, sessions, rooms, model admin — without you wiring HTTP plumbing. - You want one place that aggregates ScaiGrid features *and* any external MCP servers you've registered through ScaiLink — a unified catalog the agent doesn't have to think about. - You want tool calls metered and audited the same way as REST calls. If you only need an LLM gateway from server code you control, call `/v1/inference/chat` directly — MCP is for agentic clients, not service-to-service calls. ## What you get - **Streamable HTTP transport.** Standard MCP transport at `/mcp` — no SDK shim, just point a compliant client at it. - **Filtered tool catalog.** Every `list_tools` call returns only the tools the caller has permission to invoke, and only from modules enabled for their tenant. - **Built-in tool coverage.** ~80 tools across inference, models, sessions, rooms, accounting, IAM, webhooks, modules admin, and platform admin out of the box. - **Module-contributed tools.** Each ScaiGrid module can ship its own MCP tools; they auto-appear once the module is enabled. - **Cloud MCP aggregation.** Tools from cloud MCP servers users have registered through ScaiLink appear in the same catalog with a `remote.{user_id|tenant}.{slug}.{tool}` prefix. - **Same auth as REST.** Bearer tokens (JWT or `sgk_` API keys) are accepted via the standard `Authorization` header. ## Two-minute mental model You manage one verb and three nouns: - A **Tool** is a named, typed operation. ScaiGrid ships the catalog; you don't author tools unless you're writing a module. - A **Module** owns a slice of the tool catalog. Tools from a module appear only when that module is enabled for the caller's tenant. - A **Remote tool** is a tool from a cloud MCP server registered through ScaiLink — it lives behind the `remote.` prefix but lists and calls the same way. - The verb is **call**: an MCP client lists tools, picks one, and calls it with a JSON-shaped argument blob. The MCP transport is mounted at `/mcp`. The module's admin API is at `/v1/modules/scaimcp/`. There is no separate process — both run inside the same ScaiGrid FastAPI app and share auth, accounting, and the audit log. ## How it relates to the REST API ScaiMCP is **not** an alternative API surface; it's a different transport over the same services. An MCP `inference_chat` call lands in `InferenceService.chat` — the exact code path `POST /v1/inference/chat` uses. Permissions, dispatch, token accounting, and audit are identical. That matters because it sets the right mental model. Use REST from server code you control; use MCP when the caller is an AI agent that needs runtime tool discovery and schema-typed arguments. Both pay the same accounting bill and write the same audit events. ## Who this is for - **Agent builders** wiring up Claude Desktop, Cursor, Continue, Cline, or any other MCP-capable client to your ScaiGrid tenant. - **Custom-agent authors** building bespoke loops with the MCP SDK — Python, TypeScript, or any language with an SDK. - **Module authors** exposing their own capabilities as MCP tools through the standard `get_mcp_tools()` hook. If you're a service-to-service integrator, you almost certainly want the REST API instead. MCP buys you discovery and typed dispatch; REST buys you simplicity. ## What you don't get A few things ScaiMCP deliberately doesn't do: - **No streaming tool results.** Tool calls return one final result. For streaming chat use ScaiGrid's REST `/v1/inference/chat` with SSE — MCP itself doesn't define a streaming tool-result shape in the version of the protocol ScaiMCP targets. - **No resources or prompts surfaces.** Only the `tools/*` family is implemented. We may add the `resources/*` family later for ScaiDrive and ScaiMatrix content, but it's not in v1.0. - **No anonymous access.** Every request must authenticate. There is no public-read mode. - **No write API for the catalog itself.** Tools are registered in code by modules — you don't `POST` a tool definition at runtime. ## A minimal example A client connects, lists tools, and calls one. With the official MCP Python SDK that's roughly: ```python async with streamablehttp_client( "https://scaigrid.scailabs.ai/mcp", headers={"Authorization": "Bearer sgk_..."}, ) as (read, write, _): async with ClientSession(read, write) as session: await session.initialize() tools = await session.list_tools() result = await session.call_tool("models_list", {}) ``` The same shape works from TypeScript, Go, and any other language with an MCP SDK — see the [quickstart](./quickstart) for the full version. ## Where to go next - [Quickstart](./quickstart) — connect Claude Desktop to ScaiGrid in five minutes. - [Architecture](./concepts/architecture) — how the transport, tool registry, and permission filter fit together. - [Tool naming](./concepts/tool-naming) — core tools, module tools, and the `remote.` namespace for registered cloud servers. - [Connect Claude Desktop](./tutorials/connect-claude-desktop) — full configuration walkthrough. - [Build a custom MCP client](./tutorials/build-custom-client) — Python and TypeScript end-to-end. - [API reference](./reference/api) — every built-in tool and its input schema. ScaiMCP's module ID inside ScaiGrid is `scaimcp`; its admin API is mounted at `/v1/modules/scaimcp/` and the MCP transport itself at `/mcp`.