Native MCP Server: Why Your Database Should Be an MCP Tool Provider

Model Context Protocol is the discovery-and-invocation standard the major coding agents settled on. Claude Code, Cursor, Continue, Codex, Aider — all of them speak it. The protocol is JSON-RPC 2.0, the shape is tools/list + tools/call, and the abstraction it offers is "an agent can ask a server what tools exist and call them with structured arguments."

HeliosDB Nano speaks MCP natively. No wrapper process. No glue server. The same engine that serves your SQL traffic answers tools/list and dispatches tools/call, on three transports, with auto-registered tools.

Three Transports, Pick Per Caller

Transport	Path	Streaming	Best for
HTTP JSON-RPC	POST /mcp	single-shot	simple agents
WebSocket	/mcp/ws	full duplex	live UX, progress events
Server-Sent Events	/mcp/sse	server → client	browser-resident agents
stdio	N/A	full	sandboxed local agents

Hardened defaults: localhost + Unix-socket bind out of the box. public_bind requires explicit opt-in. JWT auth on the HTTP path; WS and SSE inherit the same model.

Auto-Registered Tool Catalogue

Adding a tool is a Rust function annotated with #[mcp_tool]. The macro registers via the inventory crate; on startup the dispatcher reads the inventory and the tool is callable. No central registration list, no boilerplate match arm.

The catalogue today (after v3.19's nine follow-ups):

Tool	Purpose
heliosdb_bm25_index	Build a BM25 index on a column
heliosdb_hybrid_search	RRF / MMR fusion over BM25 + vector
heliosdb_graph_add_edge	Insert a graph edge
heliosdb_graph_traverse	BFS / DFS traversal
heliosdb_graph_path	Shortest path
heliosdb_embed_and_store	Embed a string and persist the vector
helios_graphrag_search (v3.19)	Wraps graph_rag_search — flagship cross-modal query as a tool
helios_lsp_document_symbols (v3.19)	File outline, ordered by line
helios_lsp_rename_preview (v3.19)	Preview a rename refactor
helios_lsp_references_diff (v3.19)	Diff references between two AS OF refs
helios_lsp_body_diff (v3.19)	Diff symbol bodies between refs
helios_ast_diff (v3.19)	AST diff between refs

Streaming Progress (v3.19)

Long-running tools used to be a black box. v3.19 wires notifications/progress through the WS and stdio transports. Agents that opt in via _meta.progressToken receive structured progress events while the call is running.

# Client opens WS, sends a tools/call with progressToken
> { "jsonrpc": "2.0", "method": "tools/call", "id": 42,
    "params": {
      "name": "helios_graphrag_search",
      "arguments": { "seed_text": "auth flow" },
      "_meta": { "progressToken": 99 } } }

# Server emits progress notifications as it goes
< { "method": "notifications/progress",
    "params": { "progressToken": 99, "message": "seeding" } }
< { "method": "notifications/progress",
    "params": { "progressToken": 99, "message": "127 hits" } }

# Then the final tools/call response
< { "jsonrpc": "2.0", "id": 42, "result": { ... } }

The streaming dispatcher (mcp::call_tool_streaming) runs the sync handler on spawn_blocking and forwards events through an unbounded channel.

HTTP POST + SSE Pairing

HTTP POST is request/response, which makes streaming awkward. v3.19's solution: the client opens an SSE channel with an Mcp-Session-Id header, then makes its POST /mcp calls with the same header. A process-static session table forwards progress events to the SSE stream; the POST returns the final response normally.

Single-Shot Discovery (v3.19)

• tools/list?verbose=true — full tool catalogue with input schemas, output schemas, descriptions.
• helios/info JSON-RPC method — serverInfo + capabilities + verbose tool catalogue + resource list.
• GET /mcp/info — HTTP route returning the same payload.

Connecting Coding Agents

Every major MCP-aware agent connects with a few lines of config. Claude Code:

{
  "mcpServers": {
    "heliosdb-nano": {
      "url":  "http://localhost:8080/mcp",
      "auth": {"type": "bearer", "token": "$HDB_TOKEN"}
    }
  }
}

Cursor uses the same shape under .cursor/mcp.json; Continue ships an mcpServers block; Aider supports MCP via its tool-use config.

Why This Composition Matters

The conventional path is "agent ↔ agent backend ↔ database." The agent backend exists because the database does not speak the agent's protocol. It is glue.

Native MCP collapses the layer: agent ↔ database. Tool discovery, tool invocation, structured arguments, streaming progress, JWT auth — all on the same engine that serves your SQL traffic. The blast radius of any tool is the database's authorisation model. The latency floor is one network hop, not two.

Earlier in this series: the v3.19 release announcement. Code-Graph deep-dive. Graph-RAG architecture. Next, the platform side: the HeliosProxy v0.4 release.

← Back to Blog