mcp | CLI commands

Available since: v3.1.0

The surreal db 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 with owner-level access.

For HTTP-based clients against a running server, use surreal db start and connect to the /mcp endpoint instead. See When to use surreal db mcp vs surreal db start for the comparison, and Embedded MCP for transports, editor setup, and security.

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 db mcp [OPTIONS] [PATH]

Arguments

Name	Default	Environment variable	Description
`[PATH]`	`memory`	`SURREAL_PATH`	Database path for the embedded datastore.

Options

Name	Environment variable	Description
`--ns<NAMESPACE>`	`SURREAL_MCP_NS`	Initial namespace.
`--db<DATABASE>`	`SURREAL_MCP_DB`	Initial database.
`--username, -u<USERNAME>`	`SURREAL_USER`	Root username. Requires `--password`, and applies only if no root user exists yet.
`--password, -p<PASSWORD>`	`SURREAL_PASS`	Root password.

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

Usage

surreal db mcp --ns main --db main memory

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

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

Limits

Process-wide MCP limits use the SURREAL_MCP_* variables documented in Environment variables and on Embedded MCP. For HTTP /mcp on a non-loopback hostname, set SURREAL_MCP_ALLOWED_HOSTS (or SURREAL_MCP_ALLOW_ALL_HOSTS behind a trusted proxy). See those pages for details.