Connect MCP to your coding assistant

This tutorial walks you through connecting a coding assistant to SurrealDB using the Model Context Protocol (MCP). If MCP is new to you: it is a standard way for a coding assistant to call tools exposed by a server. SurrealDB's built-in MCP server publishes tools such as query, select, and use so your assistant can run SurrealQL and inspect schema without you copying SQL into a separate client.

For the full tool list, limits, and security model, see Model Context Protocol (MCP). This page focuses on getting a working setup you can verify in a few minutes.

Choose your setup

Both surreal start (to start a SurrealDB server) and surreal mcp (to start a SurrealDB MCP server) expose the same tools (query, select, use, …). Pick based on who shares the database and how auth should work. See When to use surreal mcp vs surreal start for the full comparison.

Stdio launches an embedded database in the same process as the MCP server — no separate terminal, no port, owner-level access. HTTP connects to a server you already run, with normal login and the option of least-privilege users.

Prerequisites

1. Install SurrealDB and confirm the binary is on your PATH.

If surreal is not on your PATH, use the full path from which surreal (macOS/Linux) or where surreal (Windows) as command.

2. An MCP-capable editor — Cursor, VS Code (1.99+ with Copilot agent mode or another MCP client), or Claude Desktop.

3. Optional smoke test — run the server manually once to confirm it starts:

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

You should see a log line that the MCP server is starting over stdio. Press Ctrl+C to stop; your editor will launch this command for you.

Path A — Local stdio (Cursor)

This is the fastest path: the editor spawns surreal mcp as a child process and talks to it over stdin/stdout.

Step 1 — Create or edit your MCP config

Cursor reads ~/.cursor/mcp.json (global) or .cursor/mcp.json (project). Add a surrealdb entry:

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

Persist data between sessions by replacing memory with a file-backed path:

"args": ["mcp", "--user", "root", "--pass", "secret", "--ns", "main", "--db", "main", "rocksdb://tmp/surreal-mcp"]

Create the directory first, or pick a path under your project. See surreal mcp for other storage backends.

Step 2 — Restart Cursor and verify

1. Open Settings → Features → MCP (or Cursor Settings → MCP).

2. Confirm surrealdb appears with a green / connected indicator.

3. Open chat and ask: "What MCP tools do you have for SurrealDB?"

You should see tools including query, select, create, insert, update, delete, list, use, and info.

Step 3 — First end-to-end task

Paste a prompt like this:

Using the SurrealDB MCP tools, create a task table with fields title (string) and done (bool). Insert two tasks — one done, one not. Then list tasks where done is false and show me the result.

The assistant should call MCP tools (often query or the CRUD helpers) against namespace main and database main as configured in your args. If something fails, check Troubleshooting below.

Other editors (stdio)

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

Path B — HTTP (surreal start)

Use this when SurrealDB already runs as a service and you want authenticated, network-accessible MCP.

Step 1 — Start the server

surreal start --user root --pass secret --bind 127.0.0.1:8000 memory

MCP is available at http://127.0.0.1:8000/mcp on the same listener as the REST API.

Step 2 — Configure your editor

Cursor example (global ~/.cursor/mcp.json):

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

Replace the header value with Base64-encoded credentials for your SurrealDB user (for example root:secret during local dev). In production, prefer a least-privilege DEFINE USER and TLS in front of the server — see MCP security.

VS Code uses the same URL but wraps it in servers:

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

After connecting, run the same verification prompt as in Path A.

What your assistant can do

Once connected, the assistant can use the published tools documented on the MCP overview. Typical workflows:

• Explore — list namespaces, databases, and tables; info for schema detail.

• Context — use to select namespace and database (stdio already sets --ns / --db, but use still helps when switching).

• Read and write — query for arbitrary SurrealQL, or select / create / insert / update / delete / relate for structured operations.

Permissions match those for the /sql endpoint: table PERMISSIONS, user roles, and server capability flags all apply.

Troubleshooting

Next steps

• Model Context Protocol (MCP) — transports, tools, environment variables, security

• surreal mcp CLI reference

• Agent Skills — teach assistants SurrealQL patterns alongside MCP

• Why SurrealDB for AI agents — memory, retrieval, and agent architecture