MCP tools

The tools on https://api.skimmerdb.com/mcp. Each runs the same code as its REST call, with the same limits, metering and errors. See Connect an agent to set it up.

Results are typed. Every tool declares an outputSchema (JSON Schema) in tools/list, and a call answers structuredContent matching it: the same fields as the REST call's answer (the API reference describes them). The same JSON also comes as one text content item, for clients that read only text. A failed call answers isError: true with the error's JSON ({"error", "code"}).

Each tool's output schema is its REST call's answer, from the same OpenAPI component, so the typed result can't drift from the API:

{"jsonrpc": "2.0", "id": 2, "result": {
  "content": [{"type": "text", "text": "{\"namespace\":\"support\",\"hits\":[...],\"next\":\"\",...}"}],
  "structuredContent": {"namespace": "support", "hits": [...], "next": "", "docs": 2, "took_ms": 0.41, "partial": false},
  "isError": false}}

Read tools carry readOnlyHint: true; delete_namespace and delete_documents carry destructiveHint: true. A read-only connection (or a read key) is offered only the read tools. Namespace limits on the connection apply to every tool.

#list_namespaces

Lists your namespaces by name, with what each stores.

#create_namespace

Creates an empty namespace. With dims, it stores your own embeddings too; with embed_provider, documents' text is embedded for you (see Embeddings) and search takes semantic. Writing documents to a new name also creates it, so this is only needed to choose vector settings up front.

#update_namespace

Sets, changes or stops a namespace's embedding model. The model must make vectors of the namespace's length. Leave embed_provider out (or empty) to stop embedding. Provider keys are not an MCP tool on purpose: they're pasted in the dashboard.

#delete_namespace

Deletes a namespace and every document in it, for good. Answers {"deleted": true}.

#write_documents

Stores (upserts) documents: an id written again replaces its earlier version. May also delete ids in the same call. Durable when it answers; searchable within about a second, or before it answers with wait.

#delete_documents

Deletes documents by id, for good. Ids that don't exist are ignored.

#search

Finds documents containing some text or matching a regex, optionally only those whose meta matches a filter. Newest first; each hit has the id, the matched text, the line around it, meta and when it was written. With vector (or semantic, a text, in a namespace with an embedding model): the nearest documents by meaning (among those matching query and filter, if given), with a score.

#count

Counts every document that contains some text or matches a regex (and the filter), exactly, with a sample of ids; or estimates fast with exact: false.

#get_document

Reads one document whole: its text, meta, vector (if any) and when it was written.

#sql_query

Counts, groups, aggregates and filters a namespace's documents with SQL over their metadata, combined with exact text or regex matches. Answers columns, types and rows (at most 10,000). Run SHOW COLUMNS first to see the columns. See the SQL reference.

#warm_namespace

Opens a namespace the agent is about to search, and fetches what the given searches will need, so they answer at warm speed. Says how warm it was (warm, local or cold).