# Connect an agent (MCP)

> SkimmerDB's remote MCP server for Claude, ChatGPT, Codex, Cursor and other agents, with OAuth or an API key.

SkimmerDB is a remote MCP server: agents get tools to make namespaces, write documents, search,
count, read and run SQL, with the same limits and metering as the REST API.

| | |
|---|---|
| Endpoint | `https://api.skimmerdb.com/mcp` (`https://skimmerdb.com/mcp` is the same endpoint) |
| Transport | Streamable HTTP, JSON-RPC 2.0 |
| Auth | OAuth 2.1 (dynamic client registration or a client-ID metadata document, PKCE), or an API key as a bearer token |
| Tools | [MCP tools reference](/reference/mcp-tools) |

## Sign in with OAuth

Add the endpoint to your agent and it does the rest: its first request gets a 401 that points
it at SkimmerDB's authorization server, it registers itself, and it sends you to a consent page.
There you sign in and choose:

- the **tenant** the agent works in;
- **read only** or **read and write**;
- optionally, the **namespaces** it may use (names or prefixes such as `agent-7-*`).

Approve, and the client gets tokens that open only `/mcp`. Each approved client acts through a
key of its own, which shows in your key list as a connected app: revoke it there and the
connection stops at once.

## Or use an API key

Send a key as `Authorization: Bearer tb_...`. The key's scope and namespaces apply. To give an
agent the help center and nothing else, make a read key limited to it:

```sh title="curl"
curl -s https://api.skimmerdb.com/v1/keys -H "Authorization: Bearer $ADMIN_KEY" \
  -d '{"name": "help agent", "scope": "read", "namespaces": ["help-center"]}'
```

## Set up your client

### Claude Code

```sh title="shell"
claude mcp add --transport http skimmerdb https://api.skimmerdb.com/mcp      # OAuth in the browser
claude mcp add --transport http skimmerdb https://api.skimmerdb.com/mcp \
  --header "Authorization: Bearer tb_..."                                    # or with a key
```

### Claude Desktop and claude.ai

Settings > Connectors > Add custom connector, with the URL `https://api.skimmerdb.com/mcp`.
Claude registers itself and sends you to the consent page.

### Cursor

In `~/.cursor/mcp.json`:

```json title="OAuth"
{"mcpServers": {"skimmerdb": {"url": "https://api.skimmerdb.com/mcp"}}}
```

```json title="API key"
{"mcpServers": {"skimmerdb": {"url": "https://api.skimmerdb.com/mcp",
  "headers": {"Authorization": "Bearer tb_..."}}}}
```

### Codex

In `~/.codex/config.toml`, then `codex mcp login skimmerdb` for OAuth:

```toml title="OAuth"
[mcp_servers.skimmerdb]
url = "https://api.skimmerdb.com/mcp"
```

```toml title="API key"
[mcp_servers.skimmerdb]
url = "https://api.skimmerdb.com/mcp"
bearer_token_env_var = "SKIMMERDB_KEY"
```

### ChatGPT and others

Add a remote MCP server (a connector or app) with the URL `https://api.skimmerdb.com/mcp`.
OAuth with dynamic registration and PKCE works with any client that supports it.

## What the agent sees

- **Only what it may use.** `tools/list` offers the tools the connection's scope allows: a
  read-only connection sees only read tools. A namespace outside its list answers like one that
  doesn't exist.
- **Annotations.** Each tool has a title, `readOnlyHint` and `destructiveHint`, and a description
  written for agents; the server's instructions explain namespaces, documents, search, filters,
  SQL and vectors.
- **Typed, structured results.** Every tool declares an output schema (JSON Schema), and its
  answer comes as `structuredContent` matching it, alongside the same JSON as text, so agents
  and clients can read fields without parsing prose.
- **Same rules as REST.** Every tool call runs the same code as its REST call, with the same
  rate limits, time limits and errors. A failed call answers `isError: true` with the error's
  JSON.
- **Metered apart.** Queries and writes through MCP count toward your usage like any other, and
  show separately as `mcp_queries` and `mcp_writes` in `GET /v1/usage`.

## Next

- [MCP tools reference](/reference/mcp-tools): every tool and its arguments.
- [Agent skill](/agent-skill): teaches a coding agent how to model data in SkimmerDB, beyond what the tools say.
- [Agent memory](/guides/agent-memory): a namespace layout for per-user memory.