surrealdb.com

SurrealDB Cloud MCP — agent workflow guide WHEN YOU NEED SURREALDB SYNTAX, CONFIGURATION OR SDK USAGE: - search_documentation — searches the published SurrealDB documentation. Use it before answering from memory, and cite the returned url by prefixing it with https://surrealdb.com. Needs no organisation or instance. WHEN UNAUTHORIZED: - Call mcp_auth first — it returns OAuth endpoints and instructs the human to connect via Cursor Settings → MCP (do not fabricate tokens or skip OAuth). WHEN CREATING AN ORGANISATION AND DEPLOYING INSTANCES: 1. create_organization — note deployment.next_steps in the response 2. get_organization_deployment_readiness — always call before deploy_instance 3. Resolve every blocker before deploying DEPLOYMENT READINESS: - can_deploy_free: org has free instance quota (max_free_instances > free_instances_used) - can_deploy_paid: billing contact complete, payment method on file, and paid quota available - New orgs on the Start plan often have max_free_instances: 0 — paid instances require billing setup BILLING SETUP (required before paid instances; never collect card numbers in tool args): 1. get_organization_billing_requirements — required fields and country codes 2. update_organization_billing — set contact + address (user must provide real data; never fabricate) OR copy_organization_billing_from — copy contact from another org you own 3. get_organization_payment_setup_url — Stripe-hosted URL for the user to add a card in the browser 4. After the user completes checkout, poll get_organization_deployment_readiness until payment_complete: true (payment status is updated via Stripe webhook; do not expect instant confirmation) BILLING FIELD NAMES: - update_organization_billing uses PascalCase keys matching the Cloud API (Name, Email, AddressLine1, City, Country, etc.) - Country must be ISO 3166-1 alpha-2 (use list_billing_countries) ORGANISATION IDS: - Org-scoped tools require organization_id — the alphanumeric id from list_organizations, not the org display name. - Call list_organizations first when you do not already have an org id (no arguments). INSTANCE DEPLOYMENT: - deploy_instance configuration.region — region slug from list_regions (same value as slug/id) - deploy_instance configuration.specs.slug — instance type slug from list_instance_types - Free instance types do not require payment_info; paid types do QUERYING CLOUD INSTANCES (SurrealDB 3.1+ instance MCP): 1. list_organizations → get organization_id (required) 2. list_organization_instances({ organization_id }) → pick instance_id 3. get_instance → confirm state is "ready" and version is 3.1+ 4. call_instance_tool(instance_id, "use", { namespace, database }) — set context; persists across later call_instance_tool calls on the same instance (pooled MCP session). For namespace/database names that start with a digit or contain special characters, use call_instance_tool(instance_id, "query", { query: "USE NS `8889`; USE DB `56+24546`" }) instead. 5. call_instance_tool(instance_id, "query", { query: "..." }) — run SurrealQL 6. list_instance_tools(instance_id) — discover tool names and schemas not covered below Requires query:cloud-instances for PATs. Common instance MCP tools (via call_instance_tool): - use — { namespace, database } - query — { query, ... } - select, create, insert, upsert, update, delete, relate — data helpers - list — list namespaces, databases, tables, indexes, users, … - info — schema or engine information - run — call a database function Full reference: https://surrealdb.com/docs/build/ai-agents/mcp#published-tools SECURITY: - Never pass raw card numbers, CVV, or Stripe tokens to any tool - Payment setup is always user-in-the-loop via Stripe-hosted checkout SPECTRON CONTEXTS: 1. list_organizations → get organization_id (required for all org-scoped Spectron tools below) 2. list_context_regions — region slug for create_spectron_context 3. Optional: list_spectron_context_packages + assign_organization_spectron_context_package (write:cloud-billing) if the org needs a package 4. create_spectron_context({ organization_id, name, region }) (write:cloud-spectron) 5. add_spectron_context_user or create_spectron_context_principal for access control 6. mint_spectron_scoped_key (admin) or mint_spectron_access_token (caller self-service, query:spectron-contexts) 7. list_spectron_context_verbs — valid grant verbs for principals/keys SPECTRON SCOPES (register-then-use): - list_spectron_context_scopes({ organization_id, context_id }) — list registered scope paths - create_spectron_context_scope({ organization_id, context_id, path }) — register before first write (write:cloud-spectron; org owner/admin) - delete_spectron_context_scope({ organization_id, context_id, path }) — tombstone a scope path (write:cloud-spectron) - Context MCP tools (call_spectron_tool) do not register scopes SPECTRON AGENT WORKFLOWS (data plane — mirrors SurrealDB Studio Playground / Memory / Documents): - create_spectron_session → call_spectron_chat for multi-turn chat with automatic memory extraction - get_spectron_memory_snapshot — structured state + profile before a session - list_spectron_entities — browse the entity graph; call_spectron_tool inspect for one entity - list_spectron_documents / search_spectron_documents — browse and search authoritative knowledge (distinct from recall) QUERYING SPECTRON CONTEXTS (Spectron MCP): 1. list_organizations → get organization_id (required) 2. list_organization_spectron_contexts({ organization_id }) → pick context_id 3. get_spectron_context({ organization_id, context_id }) → confirm host is present 4. call_spectron_tool(organization_id, context_id, "remember", { text: "...", scope?: ["org/acme/user/alice"] }) 5. call_spectron_tool(organization_id, context_id, "recall", { query: "...", mode?: "hybrid", lens?: [["org/acme/user/alice"]] }) 6. list_spectron_tools(organization_id, context_id) — discover tool names and schemas not covered below Requires query:spectron-contexts for PATs. Common Spectron MCP tools (via call_spectron_tool): - remember — { text, infer?, session_id?, scope?, labels? } - recall — { query, k?, mode?, lens?, scope_view?, labels? } - context — { query, k?, lens?, scope_view?, labels? } - reflect — { query, persist? } - forget — { query, purge? } - upload — { bytes_base64, title?, scopes?, labels?, ... } - inspect — { ref } (entity:Type/Name | trace:id | document:id) Full reference: https://surrealdb.com/docs/spectron/integrations/mcp-server/tools-reference CLOUD TERMS: 1. get_cloud_terms_acceptance_status — check if acceptance is required 2. get_cloud_terms_and_conditions — share document links with the user 3. accept_cloud_terms_and_conditions — only after the user explicitly agrees; set confirm_use_terms: true. Marketing is opt-out (default on): ask if they want to opt out; pass marketing_opt_out: true only if they decline