Native MCP Server: Give AI Agents Direct Database Access

What’s new since this post (v0.3.8). The tools have their current names: search_across_indexes, describe_index and get_catalog_stats. With security on, an agent connects with the same Authorization: Bearer key the HTTP API takes, sees exactly the tools and indexes that key allows, and tool calls can be rate-limited per key. The setup snippets below are the current ones for each client.

Built-In, Not Bolted-On

CameoDB ships with a native Model Context Protocol (MCP) server running in the same binary. No sidecars, no middleware. The moment you start CameoDB, your data becomes queryable by AI agents like Claude Code, Claude Desktop, Cursor, and Windsurf through the /mcp endpoint on port 9480.

What's Exposed: 6 Read-Only Tools

The MCP server exposes six tools, all read-only for security. Agents can discover, query, and validate, but never modify your data:

search_index

Full-text search on a single index with Tantivy query syntax.

search_across_indexes

Federated search across multiple indexes with merged results.

list_indexes

Discovery: every index the key can see, with its description, document count and field names.

describe_index

Schema inspector with types, per-field operator hints, descriptions and the index's own numbers.

validate_query

Query linter with syntax validation and "did you mean" suggestions.

get_catalog_stats

Totals across every index the key can see: indexes, documents, fields and bytes.

Query Syntax: Tantivy-Powered

The search_index tool supports the full Tantivy query language:

// Field targeting
title:rust

// Phrases with proximity
body:"small bike"~2

// Boolean operators (UPPERCASE required)
title:rust AND author:doe
(title:rust OR title:go) AND year:[2020 TO 2024]

// Range queries
score:>=100
date:[2024-01-01 TO 2024-12-31]

// Boosting for relevance
title:rust^3 OR body:rust

// Set operations
status: IN [active pending review]

Anti-Hallucination Rule

Every session starts with a clear instruction: "Answer only from what the tools return. Never fill a gap from prior knowledge, and never present an incomplete result as a whole one." The same rule leads the cameodb-orchestrator prompt. This keeps agents factual and grounded in your data.

Field Type Awareness

The MCP server provides per-field operator hints based on data types:

text: phrases, slop, prefix, IN, comparisons, range, boost
string: exact match, prefix, IN, comparisons, range, boost
numeric: exact, comparisons (>, <), range, IN, boost
date: exact, comparisons, range, IN, boost
boolean: true/false, IN, boost
ip: exact address, range, boost
json: any key or value inside it (field:value)

Setup: One Endpoint, Every Client

The MCP server speaks Streamable HTTP on a single /mcp endpoint, with the SSE transport at /mcp/sse for clients that use it. Each client names the endpoint its own way:

Claude Code

One command, or a "type": "http" entry in .mcp.json:

claude mcp add --transport http cameodb http://localhost:9480/mcp

Cursor

Add to .cursor/mcp.json:

{
 "mcpServers": {
 "cameodb": { "url": "http://localhost:9480/mcp" }
 }
}

Windsurf

Add to mcp_config.json:

{
 "mcpServers": {
 "cameodb": { "serverUrl": "http://localhost:9480/mcp" }
 }
}

Claude Desktop

Through mcp-remote in claude_desktop_config.json:

{
 "mcpServers": {
 "cameodb": {
 "command": "npx",
 "args": ["-y", "mcp-remote", "http://localhost:9480/mcp"]
 }
 }
}

Restart your AI tool after configuration. The agent will automatically discover your indexes and schemas.