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 the /mcp endpoint instead. See When to use surreal mcp vs surreal start, Model Context Protocol (MCP) for transports and security, or Connect MCP to your coding assistant for a step-by-step setup.
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 memoryOptional 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 memoryOptions
| 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.