Quickstart

In five minutes you'll register a cloud MCP server with ScaiGrid, see its tools auto-discovered, and invoke one. This path uses the cloud registry rather than the desktop bridge because it needs nothing on your machine but a terminal.

You need:

• A ScaiGrid API key with scailink:remote.manage_own (tenant admins have it by default).
• The URL of a reachable MCP server speaking streamable_http or sse. A public test server, your own deployment, or a third party.
• The credential the server needs — bearer token, API key headers, or nothing for an open server.

1
2

export SCAIGRID_HOST="https://scaigrid.scailabs.ai"
export SCAIGRID_API_KEY="sgk_..."

1. Register the server#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

curl -X POST "$SCAIGRID_HOST/v1/modules/scailink/remote-servers" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My GitHub MCP",
    "endpoint_url": "https://mcp.example.com/mcp",
    "auth_type": "bearer",
    "credentials": {"authorization": "ghp_..."},
    "is_tenant_shared": false,
    "transport": "streamable_http"
  }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import httpx, os
server = httpx.post(
    f"{os.environ['SCAIGRID_HOST']}/v1/modules/scailink/remote-servers",
    headers={"Authorization": f"Bearer {os.environ['SCAIGRID_API_KEY']}"},
    json={
        "name": "My GitHub MCP",
        "endpoint_url": "https://mcp.example.com/mcp",
        "auth_type": "bearer",
        "credentials": {"authorization": "ghp_..."},
        "is_tenant_shared": False,
        "transport": "streamable_http",
    },
).json()["data"]
print(server["id"], server["slug"], server["status"])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

const res = await fetch(`${process.env.SCAIGRID_HOST}/v1/modules/scailink/remote-servers`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCAIGRID_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "My GitHub MCP",
    endpoint_url: "https://mcp.example.com/mcp",
    auth_type: "bearer",
    credentials: { authorization: "ghp_..." },
    is_tenant_shared: false,
    transport: "streamable_http",
  }),
});
const { data: server } = await res.json();
console.log(server.id, server.slug, server.status);

Registration triggers an immediate discovery handshake against the endpoint. If the server is reachable, status is active and tool rows are populated. If unreachable, the registration still saves with status: "error" — fix the network or credentials and call refresh rather than re-registering.

2. List discovered capabilities#

1
2
3

SERVER_ID="..."  # from step 1
curl "$SCAIGRID_HOST/v1/modules/scailink/remote-servers/$SERVER_ID" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"

The detail response includes capabilities, credential_fields, credential_oldest_days, and consecutive_failures. Capabilities is the list of tools, resources, and prompts that the server advertised during discovery.

3. Re-discover on demand#

If you've changed something on the server side and want fresh capability rows immediately rather than waiting for the 15-minute cron:

1
2

curl -X POST "$SCAIGRID_HOST/v1/modules/scailink/remote-servers/$SERVER_ID/refresh" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"

This re-runs the handshake, upserts capability rows, and resets the failure streak on success.

4. Invoke a tool through ScaiMCP#

Once registered, the server's tools appear in the ScaiMCP catalog under remote.{user_id}.{slug}.{tool_name} for personal scope, or remote.tenant.{slug}.{tool_name} for tenant-shared scope. Any ScaiGrid surface that consumes MCP (agents, chat, ScaiCore runs) sees them.

1
2
3
4

curl -X POST "$SCAIGRID_HOST/v1/modules/scaimcp/tools/$TOOL_NAME/call" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"repo": "owner/name"}}'

ScaiLink resolves the namespaced name back to the registered server, fetches its credentials, opens (or reuses) a session, and forwards the call.

5. Rotate a credential#

When the upstream credential needs replacing — token expired, rotated by your security policy — rotate it in place. The server keeps its id; capability rows and namespaced tool names don't churn.

1
2
3
4

curl -X PUT "$SCAIGRID_HOST/v1/modules/scailink/remote-servers/$SERVER_ID/credentials/authorization" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "ghp_new..."}'

The PUT is idempotent on (server, field) — overwriting an existing credential overwrites both ciphertext and DEK.

What just happened#

• A row landed in mod_scailink_remote_server for your server; credentials went to mod_scailink_remote_credential encrypted with the platform KEK.
• ScaiLink opened the server, called tools/list / resources/list / prompts/list, and wrote one capability row per item.
• The discovery cron now refreshes you on its 15-minute cadence, with a per-tenant budget of 10 servers per tick.
• Your tool names are namespaced so they can't collide with another tenant's registration of the same display name.

Next#

• Cloud MCP registry — scope, namespacing, credentials, health, session pool, rotation hygiene.
• Architecture — how the bridge and the registry fit into the agent runtime.
• Run a desktop session — bridge a local MCP server instead of a hosted one.
• Register a cloud MCP server — tenant-shared scope, multi-header auth, forward_user_id, custom consent_tier.