Skip to content

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>/mcp

Authenticate with an API key as a bearer token:

Authorization: Bearer nmdb_live_…

Tools

ToolInputDoes
schemanoneReturns the database’s labels, relationship types, constraints and indexes
queryquery (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

Terminal window
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:

Terminal window
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, POST only, JSON responses. The endpoint is stateless: no session id and no server-sent event stream (GET and DELETE answer 405).
  • Methods: initialize, ping, tools/list, tools/call.
  • Protocol revisions 2025-06-18 (preferred), 2025-03-26 and 2024-11-05. JSON-RPC batches (up to 32 messages) are accepted from 2025-03-26 clients.
  • Limits, metering, IP allowlists and the spend cap apply exactly as on the HTTP API: each query call 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.