SurrealDB Cloud MCP

The hosted Model Context Protocol server for SurrealDB Cloud. Point an MCP client at one URL, sign in, and an agent can manage organisations, deploy and inspect database instances, configure agent memory contexts, query your data, and chat with agent memory.

Endpoint

URL
https://mcp.surrealdb.com
Transport
Streamable HTTP: POST for JSON-RPC, GET with Accept: text/event-stream for the server stream
Auth
OAuth 2.1 with PKCE and dynamic client registration (RFC 7591)
Tools
About ninety, over the whole Cloud estate

There is no API key to create and nothing to configure beyond the URL. The first connection opens a browser window to sign in to SurrealDB Cloud.

Discovery

This host is its own authorization server. PKCE is required and S256 is the only challenge method; clients register themselves at /oauth/register as public clients, and the scopes are openid, profile, email and offline_access.

Neither needs a credential:

curl -sS https://mcp.surrealdb.com/.well-known/oauth-protected-resource

Connect a client

Claude Code

~/.claude.json, or .mcp.json in the project root with --scope project. Written by the CLI rather than by hand.

claude mcp add --transport http surrealdb https://mcp.surrealdb.com

# or commit it for a repository instead of just this machine:
claude mcp add --transport http surrealdb https://mcp.surrealdb.com --scope project

--transport http is required: without it Claude Code treats the URL as a command to run. Sign in with /mcp inside a session, then check with claude mcp list.

Claude Desktop and claude.ai

No file. Added through the Connectors screen, which stores it against your account.

https://mcp.surrealdb.com

Add it as a custom connector under Connectors in settings, or Organization settings on Team and Enterprise. Claude runs the sign-in. Leave the OAuth Client ID and Secret blank. The + menu in the composer lists the tools once it connects.

Cursor

~/.cursor/mcp.json for every project, or .cursor/mcp.json for one.

{
  "mcpServers": {
    "surrealdb": {
      "url": "https://mcp.surrealdb.com"
    }
  }
}

Reload the window, then open Settings, MCP and click Connect beside surrealdb; the indicator turns green after sign-in. Nothing account-specific is written to the file, so a project-level .cursor/mcp.json is safe to commit.

VS Code

.vscode/mcp.json for a workspace, or the user-level file that the "MCP: Open User Configuration" command opens.

{
  "servers": {
    "surrealdb": {
      "type": "http",
      "url": "https://mcp.surrealdb.com"
    }
  }
}

The top-level key is servers, not mcpServers, and the transport is spelled "type": "http", so a block copied from Cursor will not load. Confirm with "MCP: List Servers" in the Command Palette.

OpenAI Codex

~/.codex/config.toml globally, or .codex/config.toml for one project.

[mcp_servers.surrealdb]
url = "https://mcp.surrealdb.com"
auth = "oauth"

codex mcp add surrealdb --url https://mcp.surrealdb.com writes this entry for you. Then codex mcp login surrealdb signs in, and codex mcp list shows the result.

Zed

~/.config/zed/settings.json, which the "zed: open settings file" command opens.

{
  "context_servers": {
    "surrealdb": {
      "url": "https://mcp.surrealdb.com"
    }
  }
}

Zed calls these context_servers, not mcpServers. It prompts for sign-in on first use, and Settings, AI, MCP Servers then shows a green "Server is active".

OpenClaw

~/.openclaw/openclaw.json.

{
  "mcp": {
    "servers": {
      "surrealdb": {
        "url": "https://mcp.surrealdb.com",
        "transport": "streamable-http",
        "auth": "oauth"
      }
    }
  }
}

openclaw mcp set surrealdb writes the entry, openclaw mcp login surrealdb signs in, and openclaw mcp list shows what connected. The transport value is spelled streamable-http.

Zapier

No file. The "MCP Client by Zapier" connection form, under Apps, then Add connection.

Server URL:    https://mcp.surrealdb.com
Transport:     Streamable HTTP
OAuth:         Yes
Bearer Token:  (leave empty)

This is the MCP Client app, where Zapier is the client, not mcp.zapier.com, where it is the server. Set OAuth to Yes and leave Bearer Token empty. The Run Tool action then lists the SurrealDB tools.

Hermes Agent

~/.hermes/config.yaml, or $HERMES_HOME/config.yaml when that variable is set. Written by hermes mcp add rather than by hand.

mcp_servers:
  surrealdb:
    url: "https://mcp.surrealdb.com"
    auth: oauth

hermes mcp add surrealdb --url https://mcp.surrealdb.com --auth oauth writes this entry, hermes mcp login surrealdb signs in, and hermes mcp test surrealdb reports the result. Do not add a transport field: the only value Hermes accepts is sse, which would downgrade the connection.

Cloudflare

No file. The MCP Servers panel at playground.ai.cloudflare.com.

https://mcp.surrealdb.com

Enter it under MCP Servers, select Connect, and sign in to SurrealDB Cloud in the popup; the panel then reports Connected. Pick a model that supports function calling. The URL takes no path, unlike Cloudflare's own /mcp and /sse examples, which are Workers mounting a server on one. In a Worker, await this.addMcpServer("surrealdb", "https://mcp.surrealdb.com") from the agents SDK does the same job.

Any other MCP client

Varies. Most clients read an mcpServers object out of a JSON file.

{
  "mcpServers": {
    "surrealdb": {
      "url": "https://mcp.surrealdb.com"
    }
  }
}

Deviations worth knowing: VS Code uses servers with "type": "http", Zed uses context_servers, and Windsurf and Antigravity use serverUrl in place of url. To check any of them, ask the assistant to list your SurrealDB Cloud organisations.

Headless and unattended runs

Everything above signs in through a browser. When there is not one - CI, a container, a client that cannot open a window - create a personal access token, tick only the permissions the job needs, and send it as an ordinary header: Authorization: Bearer <your-token>. That means a headers object in the Cursor, Zed or generic JSON above, a headers mapping in Hermes's config.yaml, --header on claude mcp add, bearer_token_env_var in Codex's config.toml, or transport.headers in a Cloudflare Worker. Include read:cloud alongside any other permission, or the assistant cannot look up which organisation or instance to act on.

A personal access token stands in for your whole account. It expires only if you give it a duration when you create it, so a token made without one keeps working until you delete it. Keep it out of files you commit - notably a project-level .cursor/mcp.json or .mcp.json - and delete it in the account portal when the job is done.

API

mcp.surrealdb.com serves exactly one thing: the MCP endpoint at the host root, plus the OAuth machinery that protects it. It is the same mount the platform API serves at /api/mcp, so one token works on either origin.

Behind it, about ninety tools covering:

Protocol

Try it without signing in

curl -sS -X POST https://mcp.surrealdb.com/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

That answers 200 with an SSE frame carrying serverInfo, the declared capabilities, and the agent workflow guide the server ships as its instructions. No session id is minted, because the unauthenticated path is stateless. Swap initialize for tools/list and the whole tool list comes back, still with no credential.

The platform API

The REST API, and the API reference specification live at api.surrealdb.com:

Other SurrealDB endpoints

SurrealDB Cloud MCP holds no data directly, but brokers calls to database instances and agent memory contexts, proxying into the instance's own MCP server with call_instance_tool. Once an agent has picked an organisation and an instance or context through this server, data querying and agent memory chats run there.