SurrealDB ships a built-in Model Context Protocol server so agents and editors can list schema, run SurrealQL, and manipulate records through a standard tool surface. The same access-control rules as /sql and RPC apply: DEFINE USER permissions, table PERMISSIONS, and server capability flags all gate what tools can do.
Transports
HTTP (/mcp)
When you run surreal start, the server exposes POST /mcp (streamable HTTP) on the same bind address as the REST API. Authenticate with the same headers you use elsewhere, for example Authorization: Bearer <jwt> or HTTP Basic.
Run behind TLS in production. The mcp-session-id header acts like a bearer token for the lifetime of a session — anyone who holds it can replay tool calls as the bound subject until the session expires (idle timeout defaults to five minutes).
Stdio (surreal mcp)
For local IDE integrations (Cursor, VS Code, Claude Desktop, and similar), use the dedicated subcommand. It runs the MCP server in-process with an embedded datastore:
Stdio uses Session::owner() for every tool call. Do not expose this entry point to untrusted users — there is no per-request credential re-binding on stdio because there is no network handshake to attach headers to.
See surreal mcp for flags and environment variables (SURREAL_MCP_NS, SURREAL_MCP_DB, and the shared SURREAL_MCP_* limits below).
Published tools
tools/list exposes these tools (names are stable):
| Tool | Purpose |
|---|---|
query | Run SurrealQL and return serialised results |
select, create, insert, upsert, update, delete, relate | Data manipulation helpers |
run | Call a database function with typed arguments |
list | List namespaces, databases, tables, indexes, users, … |
use | Select namespace / database context |
info | Schema or engine information for a scope |
Legacy names such as list_tables, use_database, or version are not published anymore — use list and use instead.
Configuration
MCP-specific limits are read once from the environment (prefix SURREAL_MCP_). HTTP body size uses the server-wide cap.
| Variable | Default | Effect |
|---|---|---|
SURREAL_MCP_QUERY_TIMEOUT_SECS | 60 | Outer timeout on each tool execution (0 disables) |
SURREAL_MCP_MAX_RESULT_BYTES | 256 KiB | Cap on serialised tool output (0 disables) |
SURREAL_MCP_RUN_MAX_ARGS | 64 | Maximum arguments to run |
SURREAL_MCP_PARAMS_MAX_KEYS | 256 | Maximum top-level keys in parameter objects |
SURREAL_HTTP_MAX_MCP_BODY_SIZE | 4 MiB | Maximum HTTP body size for /mcp |
Full tables live under Environment variables. Observability metrics include surrealdb.mcp.* counters and histograms from 3.1.0.
Security checklist
Prefer a least-privilege
DEFINE USER(for example a custom role with table-levelPERMISSIONS) instead of root credentials for agent clients.Lock down capabilities (
--deny-funcs,--allow-net, …) so a hijacked session cannot reachhttp::*or other high-risk functions.Set
--allow-originexplicitly for browser-based MCP clients; avoid*in production.Forward the
surrealdb::mcp::audittracing target to your SIEM — audit records include tool name, subject, namespace, database, and outcome, but never query text or row payloads.
Next steps
Why SurrealDB for AI agents — memory, tools, and retrieval patterns
Agent Skills — installable SurrealQL and SDK skills for coding agents