# sombra-mcp

Stdio-to-HTTP bridge for [Sombra](https://sombra.so). Persistent reader mode for AI.

MCP clients that only support stdio-based servers (OpenClaw, Cursor, Windsurf, and others) can't connect directly to remote HTTP MCP servers. This package bridges that gap: it speaks stdio locally and proxies requests to `https://sombra.so/mcp` over Streamable HTTP.

## Quick start

```bash
npx sombra-mcp --token sombra_pat_YOUR_TOKEN
```

Or set the token as an environment variable:

```bash
SOMBRA_TOKEN=sombra_pat_YOUR_TOKEN npx sombra-mcp
```

## Getting a token

1. Sign up or log in at [sombra.so](https://sombra.so/login)
2. Go to **Settings > Access Tokens**
3. Click **Create Token**
4. Copy the token (starts with `sombra_pat_`)

Tokens authenticate your agent against your personal Sombra library. Each token has full read/write access to your account.

## SKILL.md

We offer two SKILL.md files in this repo - the root [SKILL.md](SKILL.md) is for OpenClaw and similar, and one [for Claude specifically](.claude/skills/sombra/SKILL.md).


## Configuring MCP clients

### OpenClaw, Claude Desktop, Cursor, Windsurf

Add to your MCP config file (`openclaw.json`, `claude_desktop_config.json`, etc.):

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

### Claude.ai

Add Sombra as a connector in **Settings > Connectors**. No bridge needed - and it will automatically pop up in Claude Code.


### Claude Code

Claude Code supports remote HTTP MCP servers directly, so you don't need this bridge, or if you don't want to set it up in Claude.ai or Claude Desktop.

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

## What is Sombra?

Sombra is a research library that your AI agent can read from and write to through MCP. Save web pages as clean markdown, organise them into collections, distil the important parts into dense context, and search across everything.

19 tools for saving, searching, organising, and distilling web content and notes. Two prompts for context distillation. Collections exposed as MCP resources.

Your research persists between sessions. Tomorrow's conversation picks up where today's left off.

[sombra.so](https://sombra.so) | [MCP setup docs](https://sombra.so/mcp) | [What is Sombra?](https://sombra.so/blog/what-is-sombra)

## How it works

The bridge reads JSON-RPC messages from stdin, forwards them to `https://sombra.so/mcp` as HTTP POST requests with your Bearer token, and writes the responses back to stdout. It handles session management, protocol version negotiation, and streaming (SSE) responses.

No config beyond the token. No local state.

## Requirements

Node.js 18 or later.

## License

MIT