MCP Server (Advanced)

Deep dive into the ScaiGrid MCP server. For the basics, see ScaiMCP.

Protocol#

ScaiGrid's MCP server speaks MCP version 2024-11-05 (the current stable spec) over Server-Sent Events (SSE) transport.

Endpoint: https://scaigrid.scailabs.ai/mcp

Session initialization#

MCP clients connect, identify themselves, and list tools:

1
2
3
4
5
6

Client → Server:  initialize     (client info, capabilities)
Server → Client:  ServerCapabilities (tools, resources, prompts)
Client → Server:  tools/list
Server → Client:  ListToolsResult  (tool definitions)
Client → Server:  tools/call      (tool name + args)
Server → Client:  CallToolResult  (output or error)

Capabilities#

ScaiGrid advertises these MCP capabilities:

• Tools. Yes. Every ScaiGrid API is available as a tool.
• Resources. Yes. Some data (session history, queue messages) is addressable via mcp:// URIs.
• Prompts. Limited. Modules can contribute prompt templates (e.g., scaipersona_invoke).
• Sampling. No — agents don't delegate inference back to the MCP server. ScaiGrid IS the inference provider.

Tool discovery strategy#

For rich deployments with many modules and skills, the full tool list can be large (50+ tools). MCP clients have finite context; loading all of them upfront wastes tokens.

ScaiGrid supports progressive disclosure via ScaiSkills:

1. Client calls skills_list and skills_search MCP tools to find relevant skills.
2. Client calls skills_view on a specific skill to see its detailed capabilities and prompt guidance.
3. Agent invokes the skill's backing tools only when actually needed.

Most core tools (chat, embed, session create) are always available. Module-specific tools are only advertised to clients whose tenant has the module enabled.

Per-tool permission gating#

Each MCP tool is tied to an HTTP endpoint and inherits its permission requirements. Calling bunker_exec via MCP requires scaibunker:execute, same as calling POST /v1/modules/scaibunker/bunkers/{id}/exec via HTTP.

If a client lacks permission for a tool, tools/list hides that tool entirely — agents never see tools they can't use.

Rate limiting#

MCP tool invocations count against the same rate limits as direct REST calls. The rate limiter doesn't distinguish between origin protocols.

Long-running tools#

Some tools (bunker_exec with timeout_s: 600, training job submit) take minutes. MCP's default tool-call timeout is short. Clients must extend their timeouts:

1
2
3
4

const result = await client.callTool({
  name: "bunker_exec",
  arguments: {...}
}, { timeout: 600000 });  // 10 minutes in ms

Some MCP clients (Claude Desktop) don't yet expose per-tool timeouts — for those, long operations should be broken up (submit job, poll status) rather than blocking.

Streaming tool results#

MCP doesn't have a native streaming tool-result primitive (as of the current spec). For chat completions through MCP, the entire response is buffered and returned at once — you don't get token-by-token streaming.

For true streaming, bypass MCP and call POST /v1/inference/chat with stream: true directly.

Custom tool registration#

Modules register tools via their get_mcp_tools() method. Each tool is a McpToolDef with:

• name — the tool identifier (e.g., custom_do_thing)
• description — shown to the LLM; should be precise about what the tool does and when to use it
• input_schema — JSON Schema for arguments
• handler — async function invoked on call
• required_permission — permission needed; tool is hidden from users without it

See the module developer guide for details.

Multiple MCP clients per user#

A user can have multiple MCP clients connected simultaneously — Claude Desktop, a custom agent, a browser extension. Each establishes its own session; each gets the same tool set (filtered by the user's permissions).

Invocations from each client are independently audited.

Troubleshooting#

"No tools visible" — check the client's permission. Tools require at least scaimcp:access plus tool-specific permissions. Verify via GET /v1/me.

"Tool call timeout" — bump the client's timeout, or break up long operations.

"Unauthorized" — the connection token may be a ScaiKey JWT that expired. Refresh and reconnect.

"Tool X not in list" — the module isn't enabled for your tenant. Check GET /v1/modules or have your tenant admin enable it.

Related#

• ScaiMCP — module page with client setup examples
• ScaiSkills — progressive-disclosure tool surface
• MCP Specification (external)