Connect Claude Desktop to ScaiGrid

This tutorial walks you through making ScaiGrid's tool catalog available inside Claude Desktop. The same pattern works for any MCP-capable client that supports the streamable-HTTP transport with custom headers (Cursor, Continue, Cline, etc.).

You need:

Claude Desktop installed and signed in.
A ScaiGrid API key (sgk_...) for the tenant whose tools you want to use.
The ability to edit claude_desktop_config.json on your machine.

1. Locate the config#

Claude Desktop reads claude_desktop_config.json at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

If the file doesn't exist, create it. If it does, you'll merge a new entry into mcpServers.

2. Add the ScaiGrid entry#

Streamable-HTTP MCP servers are configured by url with optional headers. Add an entry like this:

json
{
  "mcpServers": {
    "scaigrid": {
      "transport": "streamable-http",
      "url": "https://scaigrid.scailabs.ai/mcp",
      "headers": {
        "Authorization": "Bearer sgk_your_scaigrid_api_key"
      }
    }
  }
}

The transport key is required because Claude Desktop also supports stdio-based MCP servers — naming the transport tells it which type this is.

If you already have other MCP servers configured, add scaigrid as a sibling key inside mcpServers.

3. Restart Claude Desktop#

Quit and relaunch. On startup, Claude Desktop calls list_tools against /mcp. If the connection works, your ScaiGrid tools appear in the tool list in a conversation — typically under a scaigrid group prefix in the UI.

If the entry is grey or marked failed, expand it to see the error. Most failures fall into two buckets: wrong token (401 / 403) or unreachable host (DNS / firewall).

4. Use a tool from a conversation#

Open a new chat and type something that invites tool use:

"List the models I have access to in ScaiGrid."

Claude will pick models_list, call it, and read the result. You'll see a tool-use card showing the call and the JSON response. Follow-ups like "now give me a one-line summary of each" run on top of that response without a second tool call.

For richer interactions:

"Use ScaiGrid to generate a one-paragraph product description for a noise-cancelling headphone, picking the model yourself."

Claude lists models, picks one, then calls inference_chat. The completion comes back as text content in the conversation.

5. Set tool-use boundaries#

By default Claude Desktop asks permission for each tool call. That's the right setting while you're exploring. Once you trust a tool, switch it to "always allow" in the tool-use settings UI.

For tools that mutate state — models_create, tenants_update, webhooks_create, anything under the platform admin namespace — keep manual approval on. The whole point of ScaiGrid's permission model is that you control who can do what; turning off approval is fine for read tools but reckless for writes.

6. Scope the API key#

The key in the config carries every permission the issuing user has. Two ways to make that less scary:

Use a service-account key. Create a dedicated user (or service account) for the desktop client with only the permissions you want exposed — typically models:use, models:list, sessions:*, accounting:view_own. The desktop client then can't access tenant admin even if Claude tries.
Bound the budget. Set a per-key budget through the accounting API. If the key starts spending unexpectedly, the budget caps it.

Both apply equally to the next tutorial — they're just the right hygiene for any agent-held credential.

7. Other MCP-capable clients#

The same pattern works for Cursor, Cline, Continue, and any client that supports the standard streamable-HTTP transport. The header name (Authorization) and value format (Bearer <token>) are identical; the only thing that varies is the config-file syntax. Look up "MCP server config" in the client's docs and substitute the same URL and header.

8. Verifying with the MCP Inspector#

Before debugging via the Claude Desktop UI (which can be opaque), the official MCP Inspector is the fastest way to confirm your config is correct end-to-end. It speaks the same protocol Claude Desktop does, so a passing Inspector run guarantees Claude Desktop will also connect.

bash
npx @modelcontextprotocol/inspector \
  --url "https://scaigrid.scailabs.ai/mcp" \
  --header "Authorization: Bearer sgk_your_scaigrid_api_key"

The Inspector opens a browser UI. Click "Connect", then "List Tools" — you should see the same catalog Claude Desktop will see. Try a sample call from the UI to confirm a round-trip.

9. What gets sent to ScaiGrid#

When Claude Desktop calls a tool, ScaiGrid sees a normal authenticated request from your token. The payload includes:

The tool name and JSON arguments.
Your bearer token in the Authorization header.
Standard request metadata (request id, user-agent identifying as the MCP client).

Tool results stream back as text content; Claude reads the JSON, summarises it for the conversation, and decides whether to call again. ScaiGrid logs the call under its underlying service action (inference.chat, models.list, etc.) — there's no separate "MCP" audit category.

Common gotchas#

Forgot to specify the transport. Without "transport": "streamable-http" some clients default to stdio and try to spawn https://... as a subprocess. The error message is unhelpful; this is the usual cause.
Wrong host. https://scaigrid.scailabs.ai/mcp is the managed endpoint; on-prem deployments use a different host. The token has to match the host.
Tool appears but always fails. Usually a permission gap — the key holder doesn't have the tool's required_permission. List tools first and see what's actually exposed; if a tool isn't in the list, the key can't call it.
CORS errors from a web client. ScaiGrid's CORS allowlist doesn't include arbitrary origins by default. For browser-based MCP clients, configure the allowlist in your tenant settings.
Tool list looks empty. Most likely you have a token that authenticates fine but holds no permissions. Run me_get (always available to any authenticated user) — if that works, your auth is good; you just need to grant the calling identity some permissions.