One endpoint,
whichever agent you run
CameoDB serves MCP on the port it already listens on, :9480/mcp. Connecting an agent takes one entry in its config, and your indexes become tools it can call.
-
Claude Code in one line
One command for you, or a
.mcp.jsonin the repository for the whole team. - Cursor, Windsurf and Claude Desktop The same URL, in the config file each client already reads.
- ChatGPT and claude.ai by URL Add the node as a custom connector and sign in once, with OAuth.
claude mcp add --transport http cameodb http://localhost:9480/mcp
.mcp.jsonClaude Code, for the whole team, as "type": "http".cursor/mcp.jsonCursor, as "url"mcp_config.jsonWindsurf, as "serverUrl"claude_desktop_config.jsonClaude Desktop, through mcp-remotehttps://<host>/mcpChatGPT and claude.ai, as a custom connectorThe key decides
what the agent sees
With security on, an agent is a caller like any other. It presents a key, and that key’s capabilities and index scope apply to every tool it calls.
- Offered only what it may use The tool list and the index list are filtered to the key, so an agent never sees what it would be refused.
-
Read-only, closed world
Every tool is annotated
readOnlyHintand reaches this node’s own indexes alone, so areadkey covers the whole surface. -
The same key as the HTTP API
One
Authorization: Bearerheader, one set of roles, one audit trail for people, services and agents.
claude mcp add --transport http cameodb \
http://localhost:9480/mcp \
--header "Authorization: Bearer $CAMEODB_KEY"
Sign in by URLOAuth
- 1Add the URL
https://<host>/mcpas a custom connector. - 2Approve on the nodeThe client opens the node’s approval page; paste your key once.
- 3A token that acts as the keyIt reads what the key reads, and ends when the key is revoked.
Six tools, and the agent
teaches itself the rest
Nobody pastes a schema into a prompt. The agent asks what is here, reads the index it wants, checks its query, then searches. A new index joins that loop the moment it exists.
-
Briefed on connect
Every client gets a short guide to reading CameoDB’s answers, with the full workflow as the
cameodb-orchestratorprompt. - Hints from the parser itself Operators and tokenizer rules come from the tables the query parser runs on, so the guidance always matches the engine.
-
One result shape
Read
content[0].textand letisErrorsay whether to parse it. The same for every protocol revision.
An agent meets booksreal responses
- 1
list_indexesbooks · 16,559 documents · 8 fields: “Plot summaries of 16,559 novels from Wikipedia, one document per book.” - 2
describe_indexpublication_dateis a sortable date, taking ranges, comparisons andINsets. - 3
validate_queryUnknown field ‘titel’. Did you mean: title (text)? - 4
search_indexgenres:"Science Fiction" AND publication_date:[1960 TO 1969]→ 171 hits.
- 5
search_across_indexesSeveral indexes at once, merged into one ranked list. - 6
get_catalog_statsTotals for everything the key can see.
A wrong query is refused,
never quietly answered
The risky answer is the one that looks complete. When part of a query cannot run, CameoDB names it and the fix before any hit goes back.
-
A dry run on the real parser
validate_queryreports whether a query parses, what the engine will run, and any clause it would drop. -
Corrections, with their types
An unknown field comes back with the nearest real ones:
titelfindstitle,riskscorefindssandbox_risk_score. -
Arguments checked too
A misspelled argument fails by name, so a typo in
limitnever passes for the whole answer.
{ "index": "books", "query": "titel:potter AND publication_date:>=1997" }
"parses": true,
"normalized_query": "titel:potter AND publication_date:>=1997-01-01T00:00:00Z",
"discarded_clauses": [ "unknown field 'titel' — the clause … was dropped, …" ],
"suggestions": [ "Unknown field 'titel'. Did you mean: title (text)?" ]
{ "index": "books", "query": "title:potter", "limt": 3 }
Invalid search_index arguments: unknown field `limt`,
expected one of `index`, `query`, `limit`, `offset`, `fields`, …
search_index refuses such a query outright: a narrower question never passes for the one you asked.
Your schema is
the agent’s vocabulary
An agent knows your data through list_indexes and describe_index. Three choices in the schema decide how well it queries.
- Write the descriptions The one part of a schema that says what the data is. Both tools carry it word for word, up to 512 characters per index and 200 per field.
-
Declare the fields that matter
Set them with
PUT /_configor in the first write, and pick thedefault_fieldsa bare term searches. -
Choose types for the operators
Dates and numbers sort on their fast column,
stringmatches a whole value,indexed: falsekeeps a payload out of queries.
{
"description": "Plot summaries of 16,559 novels from Wikipedia, one document per book.",
"fields": [
{ "name": "publication_date", "type": "date",
"description": "First publication. Older titles often carry the year alone.",
"searchable": true, "sortable": true, "returned": true },
{ "name": "genres", "type": "text", "tokenizer": "default",
"description": "Genres as a JSON object of Freebase id to name, e.g. \"Science Fiction\".",
"searchable": true, "sortable": false, "returned": true }, …
], …
}
The repository’s index-describe skill profiles a live index, checks every statement against the data, and writes the PUT /_config body that applies them.
Declare it once,
in your own terms
Eleven core types, answering to the names you already use for them in SQL, Python, JavaScript or Rust.
-
Every field takes a list
No array type to declare:
[9, 12]in ani64field stores two values, each matched on its own. -
Typed in the CSV header
publication_date.dateorprice.f64names a column’s type as the file loads. -
Or detected for you
schema detectreads a file and drafts its schema, anddata loadapplies one as it ingests.
textWords, under the field’s tokenizerstring · exactThe whole value, as writteni64 · integer int number numeric signedPython, JavaScript, SQLu64 · unsigned uintC, C++, Rustf64 · float double decimalPython, SQLdate · datetime timestampSQL, Pythonboolean · boolPython, Rust, C++bytes · binary blobSQLipIPv4 and IPv6, with rangesjson · object documentJavaScript, Pythonfacet · category tagCommon terminologyA REPL that knows
your indexes
cameodb client -i opens a shell that completes against the live schema and speaks the same grammar the agent sends.
-
Completion from the node
Commands, index names, and fields with their types, as
title: [text]. - Load from anywhere CSV, TSV, JSON and NDJSON, from disk or HTTP(S), with Gzip and Zip unpacked in flight.
- Left open all day Persistent history with Ctrl-R, and colorized JSON that turns plain in a pipe.
cameodb@localhost ▶ search books genres:"Science Fiction" AND publication_date:[1960 TO 1969] return title,author sort publication_date limit 3 { "hits": [ { "title": "The Bronze God of Rhodes", "author": "L. Sprague de Camp" }, { "title": "A Mystery for Mr. Bass", "author": "Eleanor Cameron" }, { "title": "The High Crusade", "author": "Poul Anderson" } ], "hits_returned": 3, "total_hits": 171, "took_ms": 1, "stats": { "shards": { "total": 4, "responded": 4, "failed": 0 }, … } }
No agent, no client,
just the endpoint
An application wants plain JSON over HTTP: the same indexes, the same query grammar.
- Same grammar, same answers The query an agent sends works here as is.
-
Streams both ways
/search/streamreturns NDJSON, one hit per line;/document/streamtakes writes. -
The key travels in the header
An unknown path answers
401without a key, so probing tells a stranger nothing.
curl -s localhost:9480/api/books/search -H 'content-type: application/json' \
-d '{"query":"title:dune","fields":["title","author"],"limit":2}'
{"hits":[{"title":"Dune","author":"Frank Herbert","_score":9.4},
{"title":"Dune Messiah","author":"Frank Herbert","_score":8.3}],
"hits_returned":2,"total_hits":16,"took_ms":0, …}
POST /api/{index}/searchSearch one index readPUT /api/{index}/documentWrite one document writePOST /api/{index}/_bulkBatched writes, where the throughput is writePUT /api/{index}/_configCreate an index or change its schema index-adminGET /_cluster/healthThe one public route none