DocsStart

Connect your agent

Create a key, then point your agent at your cell over MCP or plain HTTP.

Your agent reaches Sioma at your cell: an endpoint that serves your workspace and nothing else. Your dashboard shows your cell URL. The examples below use the shared managed cell, so replace it with the URL your dashboard shows you.

Create a key#

Create keys on the dashboard, or in Control room under Keys. Pick the scope that matches the job:

Scope For Can do
agent Your coding agent, your agent loop Call your cell: focus, explore, record outcomes
publish CI, the CLI's publish Publish a spec to your workspace
admin Workspace administration Control-plane changes

The key is shown once, when you create it. Copy it then. If you lose it, revoke it and create another. A key can never create another key or approve anything on your behalf, so a leaked agent key cannot escalate itself.

Add the MCP server#

Pick your tool.

The plugin is the shortest path, since it brings the MCP server and the onboarding skills together:

/plugin marketplace add sioma-ai/claude-plugins
/plugin install sioma@sioma

Export SIOMA_API_KEY in your shell before you run it, and the key travels by reference instead of sitting in a file.

To add just the MCP server, without the skills:

claude mcp add --transport http sioma https://aws-us1.cells.sioma.ai/mcp --header "Authorization: Bearer YOUR_API_KEY"

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "sioma": {
      "url": "https://aws-us1.cells.sioma.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Keep that file out of git. Cursor does not resolve environment variables inside headers for remote HTTP servers, so the key has to be literal here.

Add to .vscode/mcp.json. VS Code prompts for the key on first use, so nothing is stored in the file:

{
  "servers": {
    "sioma": {
      "type": "http",
      "url": "https://aws-us1.cells.sioma.ai/mcp",
      "headers": { "Authorization": "Bearer ${input:sioma-api-key}" }
    }
  },
  "inputs": [
    {
      "id": "sioma-api-key",
      "type": "promptString",
      "description": "Sioma API key",
      "password": true
    }
  ]
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sioma": {
      "serverUrl": "https://aws-us1.cells.sioma.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Anything that speaks Streamable HTTP:

{
  "mcpServers": {
    "sioma": {
      "type": "http",
      "url": "https://aws-us1.cells.sioma.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Your dashboard renders each of these against your own cell URL, so you can copy one straight from there.

Approving from the browser instead#

Agent-driven setup does not ask you for a key at all. The agent prints a short code and a URL, you open it, check the code matches what your terminal shows, and click Approve. The agent receives its credential directly.

Approve only a code you triggered yourself, just now.

Not using MCP#

If you are calling Sioma from your own agent loop, skip MCP entirely and use the HTTP API with the same agent-scoped key.

Checking it worked#

Ask your agent something about your system. The dashboard's connect step turns green once your key is first presented at the cell, which can take a minute. If your agent reports that no spec is registered, the connection works and there is nothing to serve yet: map your system next.

AI resources These docs are built to be read by your agent, not just by you.