MCP endpoint

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.json in 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.
terminal
claude mcp add --transport http cameodb http://localhost:9480/mcp
the same endpoint, everywhere
.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-remote
https://<host>/mcpChatGPT and claude.ai, as a custom connector
Access

The 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 readOnlyHint and reaches this node’s own indexes alone, so a read key covers the whole surface.
  • The same key as the HTTP API One Authorization: Bearer header, one set of roles, one audit trail for people, services and agents.
terminal
claude mcp add --transport http cameodb \
  http://localhost:9480/mcp \
  --header "Authorization: Bearer $CAMEODB_KEY"

Sign in by URLOAuth

  1. 1
    Add the URLhttps://<host>/mcp as a custom connector.
  2. 2
    Approve on the nodeThe client opens the node’s approval page; paste your key once.
  3. 3
    A token that acts as the keyIt reads what the key reads, and ends when the key is revoked.
Self-learning

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-orchestrator prompt.
  • 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].text and let isError say whether to parse it. The same for every protocol revision.

An agent meets booksreal responses

  1. 1
    list_indexesbooks · 16,559 documents · 8 fields: “Plot summaries of 16,559 novels from Wikipedia, one document per book.”
  2. 2
    describe_indexpublication_date is a sortable date, taking ranges, comparisons and IN sets.
  3. 3
    validate_queryUnknown field ‘titel’. Did you mean: title (text)?
  4. 4
    search_indexgenres:"Science Fiction" AND publication_date:[1960 TO 1969] → 171 hits.
  1. 5
    search_across_indexesSeveral indexes at once, merged into one ranked list.
  2. 6
    get_catalog_statsTotals for everything the key can see.
Checked first

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_query reports 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: titel finds title, riskscore finds sandbox_risk_score.
  • Arguments checked too A misspelled argument fails by name, so a typo in limit never passes for the whole answer.
validate_query · output abridged
{ "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)?" ]
search_index · isError: true
{ "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.

Shape the index

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 /_config or in the first write, and pick the default_fields a bare term searches.
  • Choose types for the operators Dates and numbers sort on their fast column, string matches a whole value, indexed: false keeps a payload out of queries.
describe_index · books · output abridged
{
  "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.

Field types

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 an i64 field stores two values, each matched on its own.
  • Typed in the CSV header publication_date.date or price.f64 names a column’s type as the file loads.
  • Or detected for you schema detect reads a file and drafts its schema, and data load applies one as it ingests.
eleven types · every spelling
textWords, under the field’s tokenizer
string · exactThe whole value, as written
i64 · integer int number numeric signedPython, JavaScript, SQL
u64 · unsigned uintC, C++, Rust
f64 · float double decimalPython, SQL
date · datetime timestampSQL, Python
boolean · boolPython, Rust, C++
bytes · binary blobSQL
ipIPv4 and IPv6, with ranges
json · object documentJavaScript, Python
facet · category tagCommon terminology
Client

A 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.
Every command and flag →
cameodb client -i · output abridged
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 }, … }
}
HTTP API

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/stream returns NDJSON, one hit per line; /document/stream takes writes.
  • The key travels in the header An unknown path answers 401 without a key, so probing tells a stranger nothing.
terminal · output abridged
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 read
PUT /api/{index}/documentWrite one document write
POST /api/{index}/_bulkBatched writes, where the throughput is write
PUT /api/{index}/_configCreate an index or change its schema index-admin
GET /_cluster/healthThe one public route none