Embedded MCP

SurrealDB ships a built-in Model Context Protocol server, so agents and editors can list schema, run SurrealQL, and change records through a standard set of tools. The same access control applies as on /sql and RPC: DEFINE USER permissions, table PERMISSIONS, and server capability flags all decide what a tool can do.

This page covers the server inside the SurrealDB binary, for databases you run yourself. For SurrealDB Cloud, the hosted SurrealDB MCP Server reaches the same data tools remotely and adds organisation, instance, and billing management on top.

Both publish the same data tools. What differs is how your editor connects and who shares the database.

When to use surreal mcp vs surreal start

Use surreal mcp when you want the lowest-friction path on a machine you trust: paste a config, restart the editor, and experiment. Think of it as a self-contained database for your assistant.

Use surreal start and /mcp when the agent should work against a database that already exists, or one that other clients share. That is the right model for least-privilege users, TLS, audit logging, and anything beyond trusted solo development.

Transports

HTTP (/mcp)

When you run surreal start, the server exposes POST /mcp 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.

surreal start --user root --pass secret --bind 127.0.0.1:8000 memory
# MCP endpoint: http://127.0.0.1:8000/mcp

For a non-loopback hostname (a public FQDN, a Kubernetes service name, or a load-balancer host), the transport rejects the request with 403 Forbidden: Host header is not allowed until you opt in. Set SURREAL_MCP_ALLOWED_HOSTS to your hostnames, or SURREAL_MCP_ALLOW_ALL_HOSTS=true behind a trusted proxy. See Configuration.

Stdio (surreal mcp)

For local editor integrations, use the dedicated subcommand. It runs the MCP server in the same process as an embedded datastore:

surreal mcp --user root --pass secret --ns main --db main memory

Every tool call over stdio runs with owner-level access. There is no network handshake to attach credentials to, so there is nothing to narrow the permissions with. Do not expose this entry point to untrusted users.

See surreal mcp for its flags and environment variables, including SURREAL_MCP_NS, SURREAL_MCP_DB, and the shared SURREAL_MCP_* limits below.

Connect an editor

For stdio, the editor launches SurrealDB itself, so the config is a command and its arguments.

{
  "mcpServers": {
    "surrealdb": {
      "command": "surreal",
      "args": ["mcp", "--user", "root", "--pass", "secret",
          "--ns", "main", "--db", "main", "memory"]
    }
  }
}

If the editor cannot find the binary, use the full path from which surreal (macOS and Linux) or where surreal (Windows) as command.

For HTTP, point the editor at a server you are already running and attach credentials as headers:

{
  "mcpServers": {
    "surrealdb": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Basic <base64-encoded username:password>"
      }
    }
  }
}

Once connected, ask the assistant which SurrealDB tools it has. It should list query, select, use, and the rest of the set below.

Published tools

tools/list publishes these tools, and the names are stable:

Legacy names such as list_tables, use_database, and version are no longer published. Use list and use instead.

Configuration

MCP-specific limits are read once from the environment, with the prefix SURREAL_MCP_. HTTP body size uses the server-wide cap.

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-level PERMISSIONS) over root credentials for agent clients.

• •

  Lock down capabilities (--deny-funcs, --allow-net, …) so a hijacked session cannot reach http::* or other high-risk functions.

• •

  Set --allow-origin explicitly for browser-based MCP clients, and avoid * in production.

• •

  On a public hostname, set SURREAL_MCP_ALLOWED_HOSTS, or SURREAL_MCP_ALLOW_ALL_HOSTS only behind a trusted proxy. The default allowlist is loopback-only.

• •

  Forward the surrealdb::mcp::audit tracing target to your SIEM. Audit records include the tool name, subject, namespace, database, and outcome, but never query text or row payloads.

Troubleshooting

Next steps

• •

  SurrealDB MCP Server — the hosted server for SurrealDB Cloud instances

• •

  Example usages — prompts to try once an assistant is connected

• •

  surreal mcp CLI reference — flags and environment variables

• •

  Agent Skills — installable SurrealQL and SDK skills for coding agents

• •

  AI frameworks — using SurrealDB from LangChain, CrewAI, and others