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 with owner-level access.
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 for the comparison, and Embedded MCP for transports, editor setup, and security.
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 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.