---
title: "Native MCP Server: Why Your Database Should Be an MCP Tool Provider"
description: "Three transports, twelve auto-registered tools, streaming progress events, single-shot discovery. Claude Code, Cursor, Continue, Codex, and Aider connect to HeliosDB Nano with no glue server."
date: 2026-04-24
updated: 2026-04-24
tag: "Platform"
canonical: https://www.heliosdb.com/blog/native-mcp-server-database-tool-provider.html
---

# 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:](https://www.heliosdb.com/blog/nano-3-19-ai-native-retrieval-engine.html) the v3.19 release announcement. [Code-Graph deep-dive.](https://www.heliosdb.com/blog/code-graph-sql-callable-lsp.html) [Graph-RAG architecture.](https://www.heliosdb.com/blog/graph-rag-with-context-clause.html) Next, the platform side: the [HeliosProxy v0.4 release](https://www.heliosdb.com/blog/heliosproxy-0-4-programmable-data-plane.html).