surrealmcp

Authenticate this MCP server so the user can access all of its tools. When STATUS.md indicates this server needs authentication, you must call this tool through your MCP tool-calling interface. Do not guess credentials — direct the human to complete OAuth in their MCP client (Cursor: Settings → MCP …

List available Cloud regions. Each entry is a region slug — pass it as `configuration.region` for deploy_instance / estimate_instance_cost (slug and id are the same value).

List available Cloud instance types. Each entry includes a **`slug`** string — put that slug in **`deploy_instance` / `estimate_instance_cost`** as **`configuration.specs.slug`** (not `type_slug`).

SurrealDB versions available for new instances. Use the chosen version string inside **`configuration.specs.version`** (not top-level `version`).

List countries available for Cloud billing profiles.

Search the published SurrealDB documentation. Returns results grouped by page: each result is the best match on that page, with further matches on the same page under `more`. Every `url` is a path on surrealdb.com, so prefix it with `https://surrealdb.com` to cite it. Use this before answering quest…

List SurrealDB Cloud legal documents the user must review before accepting terms (name + URL for each). Present these links to the human user before calling accept_cloud_terms_and_conditions.

Check whether the current user has accepted Cloud terms (terms_accepted_at / marketing_accepted_at from the Cloud session).

Record the user's acceptance of Cloud terms. Call get_cloud_terms_and_conditions first and share the links. Requires confirm_use_terms: true (only after the user explicitly agrees). Marketing is opt-out: ask whether they want to opt out of marketing emails; omit marketing_opt_out unless they explici…

Get the current user's SurrealDB Cloud profile.

List organisations for the authenticated user (**GET `/organizations`**). Each result includes an alphanumeric **`id`** — use it as **`organization_id`** when calling **`list_organization_instances`**, **`list_organization_spectron_contexts`**, **`get_spectron_context`**, **`call_spectron_tool`**, a…

Get a SurrealDB Cloud organisation by id (read-only). Includes billing_info and payment_info flags — call get_organization_deployment_readiness for a deployment checklist with blockers and remediation.

Create a new Cloud organisation. Returns the created org including its `id` and a `deployment` block with next steps. New orgs on the Start plan may have max_free_instances: 0 — call get_organization_deployment_readiness before deploy_instance. Requires write:cloud-organization.

Rename a Cloud organisation (PATCH name only). Requires write:cloud-organization.

List instances in one organisation (`organization_id` = org `id` from list_organizations).

Get a Cloud instance by id.

Create a Cloud instance (**POST `/instances`**). **write:cloud-instances** required. Call get_organization_deployment_readiness first to avoid quota and billing errors. Body: `name`, `org` (org id from list_organizations), `region`, `specs.slug` + `specs.version` (not top-level version/type_slug). O…

Pause a Cloud instance (stops resources; data retained).

Resume a paused Cloud instance.

Change the number of compute units for an instance.

Change storage size (GB) for an instance.

Change an instance's type slug.

Change the SurrealDB version running on an instance.

Update network access settings for an instance (e.g. public, private, dual).

Replace instance capability flags (PUT /capabilities).

Estimate cost before deploy (**PUT `/instance_cost`**). **write:cloud-instances** required.Same `configuration` as deploy_instance. Body: `name`, `org` (org id from list_organizations), `region`, `specs.slug` + `specs.version` (not top-level version/type_slug). Omit `specs.compute_units` for `free`.

Mint a database session token for a Cloud instance (GET /instances/{id}/auth). Highly sensitive — requires query:cloud-instances for PATs. Prefer call_instance_tool for agent queries.

Get backup retention policy for an instance (daily/weekly/monthly tiers and backup frequency). Use editable/min/max fields before calling update_instance_backup_policy.

Update backup retention for an instance. Call get_instance_backup_policy first and respect each tier's min/max and editable flags. Requires write:cloud-instances.

Permanently delete a Cloud instance and its backups — irreversible. Requires write:cloud-instances. You must set confirm_instance_name exactly to the instance's current display name from GET /instances/{id}. Optional confirm_instance_id must match instance_id when provided.

Proxy a tool call to a Cloud instance's built-in MCP server (https://{host}/mcp). Requires query:cloud-instances. Instance MCP tools (proxied via call_instance_tool / list_instance_tools): Common tools (see https://surrealdb.com/docs/build/ai-agents/mcp for the full list): - use — select namespace…

List MCP tools exposed by a Cloud instance's built-in MCP server. Requires query:cloud-instances. Use when a tool name or schema is not covered in the call_instance_tool reference. Instance MCP tools (proxied via call_instance_tool / list_instance_tools): Common tools (see https://surrealdb.com/do…

Get instance status (e.g. backup information).

Query metrics for an instance (metric, from_time, to_time ISO 8601; optional dummy_data).

Fetch instance logs for a time window (from_time, to_time ISO 8601).

Check whether an organisation can deploy instances before calling deploy_instance. Returns quotas, billing status, blockers with remediation, and a suggested next tool. Always call this after create_organization and before deploy_instance.

Return required billing contact fields, optional fields, snake_case aliases, and valid country codes. Billing setup workflow (required before paid instances): 1. get_organization_billing_requirements — list required fields and valid country codes 2. update_organization_billing — set billing contact …

Get billing contact details for an organisation. Billing setup workflow (required before paid instances): 1. get_organization_billing_requirements — list required fields and valid country codes 2. update_organization_billing — set billing contact + address (or copy_organization_billing_from) 3. get_…

Update billing contact and address (PUT /billing). Accepts PascalCase Cloud API keys (Name, Email, …) or snake_case aliases (name, email, address_line1, …). Does not add payment methods — use get_organization_payment_setup_url after contact is set. Billing setup workflow (required before paid instan…

Copy billing contact details from another organisation you belong to (contact info only — not payment methods). Unblocks get_organization_payment_setup_url on fresh orgs. Billing setup workflow (required before paid instances): 1. get_organization_billing_requirements — list required fields and vali…

Orchestrate billing setup before first instance deploy. Optionally copies billing from another org, updates billing contact, returns payment setup URL, and reports deployment readiness. Billing setup workflow (required before paid instances): 1. get_organization_billing_requirements — list required …

List billing invoices for an organisation.

List billing coupons applied to an organisation (read-only).

Get payment method summary for an organisation (read-only). Use with get_organization_deployment_readiness to verify payment_info after Stripe checkout.

Get a Stripe Checkout URL so the user can add a payment method in the browser (setup mode). Requires billing contact first — call get_organization_deployment_readiness to verify. Never collect card numbers in tool args. Billing setup workflow (required before paid instances): 1. get_organization_bil…

Alias for get_organization_payment_setup_url (same Stripe Checkout setup endpoint). Prefer get_organization_payment_setup_url for new integrations.

Get aggregated usage metrics for an organisation.

Get usage metrics for a specific instance.

List members of a Cloud organisation. Each member has a **`user_id`** Cloud id (opaque alphanumeric string; e.g. `0a1b2c3d4e5f6g7h8i9j0k1l2m3n4`) — use that value for remove/update-role tools.

List assignable organisation member roles.

Change a member's role within an organisation. `member_user_id` is each member's Cloud **`user_id`** from list_organization_members (not Auth0 `sub`).

Remove a member from an organisation. `member_user_id` is their Cloud **`user_id`** from list_organization_members.

List pending invitations for an organisation.

Invite a user to an organisation by email.

Revoke a pending invitation by invitation code.

List regions available for new Spectron contexts. Each entry has a `slug` — pass it as `region` when calling create_spectron_context.

List Spectron context packages in the public catalog (pricing, limits, billing period). Use `id` when assigning a package to an organisation.

List Spectron context packages assigned to an organisation (active subscriptions / trials).

Subscribe an organisation to a Spectron context package. Requires write:cloud-billing. Returns the org package record.

Cancel an organisation's active Spectron context package subscription. `package_id` is the catalog package id from list_organization_spectron_context_packages (not a separate row id). Requires write:cloud-billing.

List Spectron contexts in one organisation. Requires `organization_id` — the org `id` from `list_organizations` (not the display name). Each result includes `id`, `name`, `region`, and `host`.

Get a Spectron context by id (includes `host` for SDK / HTTP access).

Create a Spectron context in an organisation. `region` is a slug from list_context_regions. Requires write:cloud-spectron.

Rename a Spectron context. Requires write:cloud-spectron.

Delete a Spectron context and its data — irreversible. Requires write:cloud-spectron.

List API keys for a Spectron context (metadata only — secrets are not returned on list).

Revoke a Spectron context API key. Requires write:cloud-spectron.

Rotate a Spectron context API key. Response may include a one-time `key` secret — store it immediately; it is not shown again. Requires write:cloud-spectron.

Mint an admin-scoped API key for a principal. Optional `grants` attenuate permissions (must be a subset of the principal's grants). Response may include a one-time `key` secret — store it immediately; it is not shown again. Requires write:cloud-spectron.

Mint a short-lived access token for the calling user's own Spectron principal (for SDK use). Response may include a one-time `key` secret — store it immediately; it is not shown again. Any org member may call this (query:spectron-contexts). Default TTL ~3600s when omitted.

List principals (humans, agents, services) registered on a Spectron context, including optional `grants`.

Create a principal on a Spectron context (`kind`: human | agent | service | unknown). Requires write:cloud-spectron.

Update a Spectron principal display name and/or kind. Requires write:cloud-spectron.

Delete a Spectron principal. Requires write:cloud-spectron.

Replace all grants on a Spectron principal (full overwrite). Requires write:cloud-spectron.

Provision an organisation member as a human principal on a Spectron context. `user_id` is the member's Cloud `user_id` from list_organization_members. Requires write:cloud-spectron.

Proxy a tool call to a Spectron context's built-in MCP server (https://{host}/mcp). Requires query:spectron-contexts. Spectron MCP tools (proxied via call_spectron_tool / list_spectron_tools): - remember — persist a fact: { text, infer?, session_id?, scope?, labels? } - recall — ranked search over…

List MCP tools exposed by a Spectron context's built-in MCP server. Requires query:spectron-contexts. Use when a tool name or schema is not covered in the call_spectron_tool reference. Spectron MCP tools (proxied via call_spectron_tool / list_spectron_tools): - remember — persist a fact: { text, i…

Tombstone (soft-delete) a registered scope path on a Spectron context. Requires write:cloud-spectron and scope:delete on the data plane. Does not erase memory — use call_spectron_tool forget for that.

Create a Spectron chat session for multi-turn Playground-style conversations. Returns `id` to pass as `session_id` on call_spectron_chat.

Run a Playground-style chat turn: Spectron retrieves context, calls the configured LLM, persists the exchange, and returns the reply plus memory updates. Omit `session_id` to auto-create a session, or pass one from create_spectron_session.

Load structured memory overview for a context (`state` + `profile`) — similar to the SurrealDB Studio Memory State tab. Use before a session to see identity, knowledge, and context categories.

List memory entities in a Spectron context (type, name, labels) — similar to the SurrealDB Studio Memory Entities tab. Use call_spectron_tool inspect with entity:Type/Name for full detail.

List ingested documents in a Spectron context (paginated). For semantic search over document chunks, use search_spectron_documents.

Semantic search over ingested document chunks (authoritative knowledge). Distinct from call_spectron_tool recall, which searches the unified memory substrate.

List scope nodes registered on a Spectron context (paths, depth, value policies). To register a new path before writing memory, use create_spectron_context_scope.

Register a scope path on a Spectron context (register-then-use). Auto-vivifies missing ancestors. Requires write:cloud-spectron; the caller's Spectron principal needs scope:create (org owners/admins by default). Use before call_spectron_tool writes to a new scope path.

Get token usage for a Spectron context for the current billing period (breakdown by model and token kind).

Get Spectron context configuration (token limits, feature flags). Provider API keys are never returned.

List LLM providers and models configured for a Spectron context (no secrets).

List grant verbs available for Spectron principals and keys (e.g. memory:read, scope:create).