The SurrealDB MCP Server connects AI tools to your SurrealDB Cloud account. Add one URL to Claude, Cursor, or any other MCP client, sign in with your Surreal ID, and your assistant can work on your databases alongside you: deploy an instance, query the data inside it, look into why something is slow, and keep track of what it all costs.
https://mcp.surrealdb.comThe server is hosted for you, so there is nothing to install and nothing to keep running. It acts as you: it sees only the organisations you belong to, respects the role you hold in each one, and asks you to confirm anything that cannot be undone.
This page covers the hosted server for SurrealDB Cloud. To give an assistant tools against a database you run yourself, see Embedded MCP.
What is MCP?
Model Context Protocol is an open standard for connecting AI assistants to outside tools and data. A server publishes a set of tools, and a client such as Claude or Cursor calls them on your behalf. Instead of copying a connection string into a chat window and pasting query results back out, your assistant works with SurrealDB directly.
What you can do
Deploy and manage instances — create an instance, pause one you are not using, resize it as traffic grows, or upgrade it to a newer version of SurrealDB.
Work with your data — ask a question in plain language and let the assistant write and run the SurrealQL, or have it create tables and seed records while you build.
Look into problems — pull up instance status, metrics, and logs next to the query you were just writing.
Manage your team — invite people to an organisation, change what they can do, and withdraw invitations.
Keep an eye on cost — check usage and invoices, and estimate what an instance will cost before you create it.
Give agents long-term memory — create and manage Spectron contexts, then store and recall memories from them.
Connect your AI tool
Most clients need nothing but the URL. Follow the guide for your tool:
For anything else, add https://mcp.surrealdb.com as a remote MCP server. The usual shape is:
{
"mcpServers": {
"surrealdb": {
"url": "https://mcp.surrealdb.com"
}
}
}Some clients differ: VS Code uses a servers object with "type": "http", and Windsurf and Antigravity use serverUrl in place of url. Once the server is connected, ask your assistant to list your organisations. If it comes back with them, you are set up.
Signing in
With your Surreal ID
If your client supports sign-in, this is all it takes: the client opens a browser window, you sign in with the same Surreal ID you use for SurrealDB Cloud, and you approve the connection. No credentials go into a config file, and you can disconnect from the client whenever you like.
A signed-in connection can use every tool the server offers, limited only by your role in each organisation.
With a personal access token
Use a token when your client cannot open a browser, or when something runs unattended. Create one in the account portal, tick the permissions it should carry, and pass it to your client as a header:
{
"mcpServers": {
"surrealdb": {
"url": "https://mcp.surrealdb.com",
"headers": {
"Authorization": "Bearer <your-token>"
}
}
}
}A token carries only the permissions you selected when you created it:
| Permission | Lets your assistant |
|---|---|
read:cloud | See your organisations, instances, Spectron contexts, usage, and logs |
write:cloud-instances | Deploy, resize, pause, upgrade, and delete instances |
query:cloud-instances | Read and write the data inside your instances |
write:cloud-organization | Create organisations, and manage members, roles, and invitations |
write:cloud-billing | Update billing details and manage Spectron plans |
write:cloud-spectron | Create Spectron contexts and manage who may use them |
query:spectron-contexts | Store and recall agent memory in a Spectron context |
Include read:cloud alongside any of the others. Without it your assistant cannot look up which organisation or instance to act on, so the write permissions have nothing to work with.
A personal access token stands in for your whole account and does not expire on its own. Give it only the permissions the job needs, keep it out of files you commit, and delete it in the account portal when you are finished with it.
Available tools
You never call the tools by hand. Your assistant picks what it needs, and most clients show you the call before it runs. Read-only tools are marked as safe, so a client can approve them without asking you every time.
| Group | What your assistant can do |
|---|---|
| Profile and organisations | Check who you are signed in as, list the organisations you can work in, and create or rename one |
| Members and invitations | See who has access to an organisation, invite someone, change their role, or withdraw an invitation |
| Instances | List instances and their details, deploy a new one, pause, resume, resize, upgrade, adjust backups, or delete |
| Instance data | Run SurrealQL and record operations inside a running instance |
| Monitoring and usage | Read an instance's status, metrics, logs, and usage |
| Billing | Fill in billing details, check whether an organisation can deploy yet, and read usage and invoices |
| Catalogue | Look up the regions, instance types, and SurrealDB versions available to you |
| Terms | Fetch the SurrealDB Cloud terms and record your acceptance |
| Spectron contexts | Create and configure memory contexts, and control who may use them |
| Spectron memory | Store, search, recall, and reflect on what an agent has learned |
The regions, instance types, and versions are also offered as MCP resources, for clients that prefer them to tool calls. Clients with a prompt menu get a Deploy a Cloud Instance wizard, which walks through the choices, prices the result, and waits for your go-ahead.
To see the exact tool surface your client has, ask your assistant which SurrealDB tools it can use.
Working with your data
The same connection that manages an instance can also query it. Ask a question, and your assistant chooses the namespace and database, writes the SurrealQL, and shows you what came back. Example usages has prompts to try.
Two things have to be true first. The instance must be running, so resume it if you paused it. And it must be on SurrealDB 3.1 or later, the version that began answering these calls. If it is older, ask your assistant to upgrade it.
Inside an instance, these are the tools your assistant works with:
| Tool | What it does |
|---|---|
use | Choose the namespace and database to work in |
query | Run SurrealQL |
select, create, insert, upsert, update, delete, relate | Read and change records without writing a full statement |
run | Call a database function |
list | List namespaces, databases, tables, indexes, and users |
info | Describe the schema, or the engine itself |
A database you run yourself publishes the same set. See Embedded MCP for how they behave there.
Spectron contexts work the same way. Your assistant can remember, recall, reflect, forget, upload, and inspect against a context you own, described in the Spectron MCP tools reference.
Deploying an instance
Creating an instance costs money, so the server never quietly does it. Your assistant first checks whether the organisation is ready to deploy, and reports anything standing in the way: no free instances left on the plan, billing details missing, or no payment method on file.
Clearing those blockers is a conversation. The assistant asks for the billing contact and address it needs, then hands you a secure checkout link so you can add a card yourself. Card details never pass through the assistant. Once the payment goes through, it can check readiness again and deploy.
Ask for an estimate before it creates anything. The assistant can price a configuration, show you the monthly cost, and wait for you to agree.
What the server will not do
Delete an instance on a guess. Deletion is permanent and takes the instance's backups with it, so the assistant has to name the instance exactly as it stands right now. A stale or mistaken name is refused.
Handle your card. Payment details are only ever entered by you, on a secure checkout page. No tool accepts a card number.
Accept terms for you. Your assistant can fetch the documents and link you to them; the agreement is yours to give.
Show a secret twice. New Spectron keys and access tokens appear once, when they are created. Store them somewhere safe there and then.
Clients often let you auto-approve tools to save clicks. Reserve that for the read-only ones, and keep the confirmation step on anything that changes or removes something.
Troubleshooting
| What you see | What to do |
|---|---|
| Your client says the server needs authentication | Sign in again from the client, or check the personal access token still exists in the account portal |
| A tool reports a missing permission | Your token was created without it. Permissions are fixed once a token exists, so create a new token with that box ticked |
| Sign-in is refused because your email is not verified | Verify the email address on your Surreal ID, then sign in again |
| Your assistant loses the connection after a while | Idle connections are dropped. Reconnect in the client and carry on |
| An instance cannot be queried | It is paused or still starting. Wait until it reports as ready, or ask your assistant to resume it |
| An instance says it needs a newer version | Data tools need SurrealDB 3.1 or later. Ask your assistant to upgrade the instance |
| Your assistant cannot find an organisation you named | It is looking for the organisation's identifier rather than its display name. Ask it to list your organisations first |
Next steps
MCP in Claude — set it up in Claude Code, Claude Desktop, or the Claude app
MCP in Cursor — set it up in Cursor
Example usages — prompts that show what the server can do
Embedded MCP — the MCP server inside SurrealDB, for databases you run yourself
Agent Skills — teach your assistant SurrealQL and SDK patterns to go with these tools