SkimmerDB Docs
API reference

MCP

For AI agents.

Kept in this tab only and sent only to api.skimmerdb.com. Requests run against your account and count as usage. Make a key.

MCP endpoint (Streamable HTTP)

POST /mcp

For Claude, ChatGPT, Codex, Cursor and other agents: JSON-RPC 2.0 (initialize, tools/list, tools/call). Tools: list_namespaces, create_namespace, delete_namespace, write_documents, delete_documents, search, sql_query, count, get_document, warm_namespace; each runs the same code, limits and metering as its REST call (metered apart as mcp_queries / mcp_writes). Agents sign in with OAuth 2.1 (discovery from the 401's WWW-Authenticate, dynamic registration, PKCE); API keys work too. Connect: claude mcp add --transport http skimmerdb https://api.skimmerdb.com/mcp (https://skimmerdb.com/mcp is the same endpoint).

Body application/json

jsonrpcstringrequired
idinteger | string
methodstringrequiredinitialize, ping, tools/list or tools/call.
paramsobject

Answer

jsonrpcstring
idinteger | string | null
resultobject
errorobject
error.codeinteger
error.messagestring

Status codes

200OK
401No key, or an unknown or revoked one.
curl -s https://api.skimmerdb.com/mcp \
  -H "Authorization: Bearer $KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
from skimmerdb import SkimmerDB
from skimmerdb._api.api.mcp import mcp
from skimmerdb._api.models import JsonRpcRequest

db = SkimmerDB()  # SKIMMERDB_KEY
answer = mcp.sync(client=db.api, body=JsonRpcRequest.from_dict({"jsonrpc":"2.0","id":1,"method":"tools/list"}))
import { SkimmerDB } from "skimmerdb";
import { mcp } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await mcp({ client: db.client, body: {"jsonrpc":"2.0","id":1,"method":"tools/list"} });
200 answer
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "search"
      }
    ]
  }
}

OAuth protected-resource metadata

GET /.well-known/oauth-protected-resource no key

Where MCP clients find the OAuth server (RFC 9728).

Answer

resourcestring
authorization_serversstring[]
scopes_supportedstring[]
bearer_methods_supportedstring[]
resource_namestring
resource_documentationstring

Status codes

200OK
curl -s https://api.skimmerdb.com/.well-known/oauth-protected-resource
from skimmerdb import SkimmerDB
from skimmerdb._api.api.mcp import get_resource_metadata

db = SkimmerDB()  # SKIMMERDB_KEY
answer = get_resource_metadata.sync(client=db.api)
import { SkimmerDB } from "skimmerdb";
import { getResourceMetadata } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await getResourceMetadata({ client: db.client });