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.

When an agent inspects the schema with info or list, any COMMENT on tables and fields is included. Put query-relevant detail in those comments (record-ID conventions, how to compare a field, graph paths) so the agent does not have to guess from names alone.

Each tool also carries annotation hints that clients use to decide what to auto-approve. gql is annotated as neither read-only nor safe, because the GQL dialect parses INSERT, SET, REMOVE, and DELETE as well as reads.

Protocol versions

The server states which MCP specification revisions it implements rather than inheriting them from the SDK it links against, and it advertises 2026-07-28. An unknown version in a request degrades to that revision.

2026-07-28 removes the initialize handshake and protocol sessions: a request carries its own protocol version, identity, and capabilities, and anything spanning requests must be named on each one. Earlier handshake-based revisions are served on the same endpoint, so clients built against them keep working unchanged.

Selecting a namespace and database per call

Because a stateless request has no session to hold a selection, every tool except use takes optional namespace and database arguments. Resolution takes the first value it finds, filling each part independently:

1. 1.

   The tool call's own namespace and database arguments

2. 2.

   The surreal-ns and surreal-db request headers

3. 3.

   The handshake session's use selection, on the revisions that still have one

4. 4.

   The server's configured defaults

A call may therefore override the database while inheriting the namespace. A request that names its own scope never changes the connection's state, so the override cannot leak into a later call.

use stays in tools/list under every revision so the tool surface does not vary by protocol version. Under 2026-07-28 it returns an error pointing at the per-call arguments instead of selecting anything.

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