MCP and AI Assistants

Sombra is an MCP (Model Context Protocol) server. That means any AI tool that speaks MCP can save, search, organise, and read your library directly. Claude Desktop, Claude Code, ChatGPT, Cursor, and agentic frameworks like LangGraph and CrewAI all work.

Your AI assistant gets 19 tools across four categories — saving content, reading and searching, organising collections, and managing lifecycle. The full tool listing is always available at sombra.so/mcp.

Connecting — interactive clients

For AI tools where you're present (Claude Desktop, Claude.ai, Claude Code, ChatGPT), use OAuth. You authenticate through your browser once, and the connection stays active.

Claude Desktop and Claude.ai

1. Go to Settings → Connectors → Add Custom Connector
2. Enter "Sombra" as the name and set the URL to https://sombra.so/mcp
3. Click Connect, log in or create an account, and you're done

This connection carries over to Claude Code automatically.

Claude Code

If you set up via Claude.ai above, you're already connected. Otherwise, add the server directly:

claude mcp add --transport http sombra https://sombra.so/mcp

After adding, Claude Code will show Sombra as an unauthenticated connector. Select it and your browser will open to complete the OAuth login.

ChatGPT

1. In ChatGPT, go to Settings → Apps and enable Developer mode
2. Click Create App
3. Set the URL to https://sombra.so/mcp
4. Set auth type to OAuth — no other details needed
5. Save, log in when prompted, and you're done

Other MCP clients

Any MCP-compatible client can connect using:

Personal Access Tokens

OAuth works when a human is in the loop to click "Authorize." For headless agents, CI pipelines, and agentic frameworks, you need a Personal Access Token (PAT).

A PAT is a Bearer token you pass in the Authorization header:

Authorization: Bearer sombra_pat_YOUR_TOKEN

Creating a token

1. Log in at sombra.so
2. Go to Settings → Access Tokens
3. Click Create Token
4. Give it a descriptive name (e.g. "CrewAI agent", "CI pipeline")
5. Copy the token immediately — it won't be shown again

Monitor usage and revoke tokens from the same page.

PATs are workspace-scoped

Each Personal Access Token is tied to a specific workspace. When an agent authenticates with a PAT, it operates within that workspace's collections, artifacts, and search index — just like a user who has that workspace selected.

If you have multiple workspaces and need an agent to access each one, create a separate token per workspace. This keeps access explicit and revocable.

By contrast, OAuth connections (Claude Desktop, Claude.ai, etc.) are user-scoped and can switch workspaces within a session.

Using PATs with agentic frameworks

For LangGraph, CrewAI, OpenAI Agents SDK, Pydantic AI, Google ADK, or custom agents — point them at the MCP endpoint with your token:

POST https://sombra.so/mcp
Authorization: Bearer sombra_pat_YOUR_TOKEN
Content-Type: application/json

Using PATs with stdio-only clients

Some MCP clients only support stdio-based servers (Cursor, Windsurf, OpenClaw). The sombra-mcp npm package bridges stdio to Sombra's HTTP endpoint:

npx sombra-mcp --token sombra_pat_YOUR_TOKEN

Or via environment variable:

SOMBRA_TOKEN=sombra_pat_YOUR_TOKEN npx sombra-mcp

For Claude Desktop, add it to claude_desktop_config.json:

{
  "mcpServers": {
    "sombra": {
      "command": "npx",
      "args": ["-y", "sombra-mcp", "--token", "sombra_pat_YOUR_TOKEN"],
      "env": {}
    }
  }
}

What your AI assistant can do

Once connected, your assistant has access to the full Sombra toolkit:

Save & Create — save web pages by URL, create markdown notes, build collections

Read & Browse — search your library, read collections and artifacts, browse notes, read distilled context

Organise — move artifacts between collections, update metadata, write distilled context summaries

Manage — archive and restore artifacts, delete collections

The practical workflow: you save sources through the browser or ask your assistant to save them. Organise into collections. Distil the collection into dense context. Then your assistant reads that context before writing code, generating reports, or doing analysis — working from your curated sources instead of stale training data.

Security

• Never commit tokens to version control. Use environment variables.
• Revoke tokens you no longer need from Settings → Access Tokens.
• If a token is compromised, revoke it immediately and create a new one.
• PATs have the same access level as you within the scoped workspace.
• MCP connections expire after 21 days of inactivity. Reconnect by selecting the Sombra connector again.

Troubleshooting

"Not authenticated" in Claude Code The OAuth flow hasn't completed yet. Run /mcp in Claude Code to see your connectors. Select the Sombra connector — your browser will open to complete login. Alternatively, add Sombra as a connector in the Claude.ai app first, which also enables it for Claude Code.

Connection stopped working MCP connections expire after 21 days of inactivity. Reconnect by selecting the Sombra connector again — no need to remove and re-add it.