mcp | SurrealDB Docs

Start SurrealDB's Model Context Protocol server over stdio for local IDE and agent integrations.

Available since: v3.1.0

The surreal mcp subcommand starts the built-in Model Context Protocol server on stdio, suitable for Cursor, VS Code, Claude Desktop, and other MCP clients. It opens an embedded datastore at the path you pass (default memory) and runs every tool call under Session::owner().

For HTTP-based clients against a running server, use surreal start and connect to /mcp instead. See Model Context Protocol (MCP) for transports, tools, and security guidance.

Warning

Stdio MCP is intended for a trusted operator on the same machine. Do not expose this process to untrusted users — there is no per-call HTTP authentication surface to re-bind credentials.

Usage

surreal mcp --ns main --db main memory

Optional root credentials apply only when no root user exists yet (same semantics as surreal start):

surreal mcp -u root -p secret --ns main --db main memory

Options

Argument / flag	Environment	Description
`path` (positional)	`SURREAL_PATH`	Database path (`memory` by default)
`--ns`	`SURREAL_MCP_NS`	Initial namespace
`--db`	`SURREAL_MCP_DB`	Initial database
`-u` / `--username`	`SURREAL_USER`	Root username (requires `--password`; only if no root exists)
`-p` / `--password`	`SURREAL_PASS`	Root password

Database tuning flags from surreal start are also available via the shared dbs option group (see surreal mcp --help).

Limits

Process-wide MCP limits use the SURREAL_MCP_* variables documented in Environment variables and on MCP for AI agents.