Connect an AI app (MCP)

Soma is an MCP server. Add this URL to your AI app:

https://staging.soma.evarist.com/mcp

The app opens Soma’s sign-in page; you sign in with your Soma account and allow it. From then on it can search and read the workspaces you belong to (read-only), and cite them. You can see and disconnect connected apps in Soma, under Account settings → Connect an AI app.

Sign-in follows the MCP authorization standard (OAuth 2.1 with PKCE). Nothing to copy or configure besides the URL.

Per app

Claude (claude.ai, Desktop)

Settings → Connectors → Add custom connector, paste the URL, then Connect. In a conversation, enable the Soma connector and ask, for example: List my Soma workspaces.

Claude Code

claude mcp add --transport http soma https://staging.soma.evarist.com/mcp

Then run /mcp in Claude Code and choose Authenticate for soma.

ChatGPT

Add a custom connector (developer mode) with the URL and OAuth authentication.

Cursor

In ~/.cursor/mcp.json:

{ "mcpServers": { "soma": { "url": "https://staging.soma.evarist.com/mcp" } } }

VS Code

In .vscode/mcp.json:

{ "servers": { "soma": { "type": "http", "url": "https://staging.soma.evarist.com/mcp" } } }

Codex

codex mcp add soma --url https://staging.soma.evarist.com/mcp

Microsoft Copilot Studio

Add an MCP tool with the URL and OAuth 2.0 (dynamic discovery).

Tested so far: claude.ai and the official MCP Python SDK. The others use the same standard; tell us if one doesn’t connect.

Agents that can only send a header

Some agents and frameworks can’t run a sign-in flow. Create an API key in Soma (Account settings → API keys), choose the workspaces it may read, and send it as a header:

{
  "mcpServers": {
    "soma": {
      "type": "http",
      "url": "https://staging.soma.evarist.com/mcp",
      "headers": { "Authorization": "Bearer scribe_mcp_…" }
    }
  }
}

API keys are read-only and limited to the workspaces you chose. Revoke them in the same place.

What the agent can do

See MCP tools: search, read whole documents, explore the knowledge graph, list sub-scopes. Every tool takes the workspace_id to work on; list_workspaces lists them.

Get started

Connect your agents

CLI

API

MCP

Connect an AI app (MCP)

Per app

Agents that can only send a header

What the agent can do

​Per app

​Agents that can only send a header

​What the agent can do

Per app

Agents that can only send a header

What the agent can do