MCP for AI agents
Every NamiDB Cloud database has a Model Context Protocol endpoint, so an AI agent or coding assistant can read its schema and run Cypher as tools. There is nothing to install: it is a remote MCP server over HTTPS.
https://db.namidb.com/v1/<database>/mcpAuthenticate with an API key as a bearer token:
Authorization: Bearer nmdb_live_…Tools
| Tool | Input | Does |
|---|---|---|
schema | none | Returns the database’s labels, relationship types, constraints and indexes |
query | query (Cypher), params (object, optional) | Runs one statement and returns {columns, rows, write_outcome?} |
The tools are scoped to the database in the URL. With a read-only key,
query refuses writes (and announces itself as read-only, so clients can
show that), which is what most agents should get.
Tool failures (a Cypher error, a rate limit, a timeout) come back as tool
results with isError: true and the error JSON as text, so the agent can read
the reason and correct its query. Authentication and database errors are HTTP
errors.
Set up a client
Create a key first: API keys → Create key, Read only, scoped to the one database the agent needs, with an expiry.
Claude Code
claude mcp add --transport http namidb-movies https://db.namidb.com/v1/movies/mcp \ --header "Authorization: Bearer $NAMIDB_API_KEY"Clients configured with JSON
Most clients that support remote (Streamable HTTP) servers take a block like this; check your client’s documentation for the file and key names:
{ "mcpServers": { "namidb-movies": { "url": "https://db.namidb.com/v1/movies/mcp", "headers": { "Authorization": "Bearer nmdb_live_…" } } }}From your own agent
Any MCP client library that speaks Streamable HTTP works. To try it with
curl:
curl https://db.namidb.com/v1/movies/mcp \ -H "Authorization: Bearer $NAMIDB_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "query", "arguments": {"query": "MATCH (m:Movie) RETURN count(m) AS movies"}}}'Protocol details
- Transport: Streamable HTTP,
POSTonly, JSON responses. The endpoint is stateless: no session id and no server-sent event stream (GETandDELETEanswer 405). - Methods:
initialize,ping,tools/list,tools/call. - Protocol revisions
2025-06-18(preferred),2025-03-26and2024-11-05. JSON-RPC batches (up to 32 messages) are accepted from2025-03-26clients. - Limits, metering, IP allowlists and the spend cap apply exactly as on the
HTTP API: each
querycall is one request.
Keeping agents safe
- Give agents read-only keys unless they must write, and scope every key to the databases it needs.
- Add an expiry, and an IP allowlist when the agent runs from known addresses.
- Use a separate key per agent or tool, so you can see each one’s use and revoke it alone.
- Agents can write expensive queries: the plan’s query timeout and rate limits bound them, and the console’s Activity tab can cancel a runaway statement.
To run an MCP server next to a self-hosted engine instead, see
namidb-mcp.