> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soma.evarist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an AI app (MCP)

> Use Soma inside Claude, ChatGPT, Cursor, VS Code, Copilot Studio or any MCP client.

Soma is an [MCP](https://modelcontextprotocol.io) server. Add this URL to your AI app:

```text theme={null}
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**.

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

## Per app

<AccordionGroup>
  <Accordion title="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*.
  </Accordion>

  <Accordion title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http soma https://staging.soma.evarist.com/mcp
    ```

    Then run `/mcp` in Claude Code and choose **Authenticate** for soma.
  </Accordion>

  <Accordion title="ChatGPT">
    Add a custom connector (developer mode) with the URL and OAuth authentication.
  </Accordion>

  <Accordion title="Cursor">
    In `~/.cursor/mcp.json`:

    ```json theme={null}
    { "mcpServers": { "soma": { "url": "https://staging.soma.evarist.com/mcp" } } }
    ```
  </Accordion>

  <Accordion title="VS Code">
    In `.vscode/mcp.json`:

    ```json theme={null}
    { "servers": { "soma": { "type": "http", "url": "https://staging.soma.evarist.com/mcp" } } }
    ```
  </Accordion>

  <Accordion title="Codex">
    ```bash theme={null}
    codex mcp add soma --url https://staging.soma.evarist.com/mcp
    ```
  </Accordion>

  <Accordion title="Microsoft Copilot Studio">
    Add an MCP tool with the URL and OAuth 2.0 (dynamic discovery).
  </Accordion>
</AccordionGroup>

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

## 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:

```json theme={null}
{
  "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](/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.