Connect an agent (MCP)

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.

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

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

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:

{"mcpServers": {"skimmerdb": {"url": "https://api.skimmerdb.com/mcp"}}}

{"mcpServers": {"skimmerdb": {"url": "https://api.skimmerdb.com/mcp",
  "headers": {"Authorization": "Bearer tb_..."}}}}

#Codex

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

[mcp_servers.skimmerdb]
url = "https://api.skimmerdb.com/mcp"

[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: every tool and its arguments.
• Agent skill: teaches a coding agent how to model data in SkimmerDB, beyond what the tools say.
• Agent memory: a namespace layout for per-user memory.