ScaiMCP

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:

1
2
3
4
5
6
7
8

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 for the full version.

Where to go next#

• Quickstart — connect Claude Desktop to ScaiGrid in five minutes.
• Architecture — how the transport, tool registry, and permission filter fit together.
• Tool naming — core tools, module tools, and the remote. namespace for registered cloud servers.
• Connect Claude Desktop — full configuration walkthrough.
• Build a custom MCP client — Python and TypeScript end-to-end.
• API reference — 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.