MCP — the agent API

PrimDB exposes an agent-readable API over the Model Context Protocol (MCP). Point Claude Desktop, Cursor, or any MCP/agent client at it with a single project-scoped token and it can set up and fix a whole project — deploy and promote, read a failing build’s logs and diagnose it, update the start command or env, provision or delete managed databases, query your data, and read feedback notes — all scoped to one project.

1. Create a token

In the dashboard: your project → Settings → API tokens → New token. Copy the value shown once (format primdb_mcp_<project>_<random>). It is project-scoped: a token can only ever touch its own project. Revoke it any time from the same screen.

2. Connect

• Endpoint: https://mcp.primdb.com
• Auth: Authorization: Bearer primdb_mcp_...
• Transport: HTTP (JSON-RPC 2.0)
• Rate limit: 1000 requests/min per token (429 + Retry-After when exceeded)

Claude Desktop / Cursor (mcp.json)

{
  "mcpServers": {
    "primdb": {
      "url": "https://mcp.primdb.com",
      "headers": {
        "Authorization": "Bearer primdb_mcp_..."
      }
    }
  }
}

Direct HTTP (any agent)

curl -s https://mcp.primdb.com \
  -H "Authorization: Bearer primdb_mcp_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

3. Tools

Honest note. The Hosts tools are account-level: they act on your fleet, not a single project, so they need an account-scoped token rather than a project token. Use them to enroll your own server, pin services to it, and discover or adopt containers already running there. See Hosts.

Honest note. An agent can now take a project from broken to live on its own: get_deployment_logs to read a failing build, diagnose_deployment for a root-cause + fix, update_settings / set_env to correct the start command or env, create_data_service to provision the database the app needs, then deploy. Owner-only tools (settings, create/delete database, deploy) require a token whose creator owns the project. Data tools resolve the project’s relevant service automatically; pass serviceId only when a project has more than one of a kind.

Agent quickstart — prompts to paste

Once your MCP client is connected, tell your agent what you want in plain language. Some starters:

• “Deploy this repo to PrimDB and give me the preview URL.”
• “My last deploy failed — read its build logs, tell me why, and fix it.”
• “This app needs Postgres and Redis. Provision them and set the start command, then deploy.”
• “List my recent deployments and promote the latest passing preview to production.”
• “Run this SQL query against my PrimDB Postgres and summarize the rows.”
• “Set the STRIPE_KEY env var on my PrimDB project, then redeploy.”
• “Show the open preview feedback notes and resolve the one about the checkout button.”

Security

• A token is bound to one project — it can never reach another project’s deployments, data, env, or notes.
• Postgres / Redis / Storage access goes through the same per-tenant isolation the rest of the platform uses (DB roles, Redis ACLs, bucket scoping).
• Every tool call is audit-logged (mcp_<tool> plus the token id). Revoke instantly.
• Secrets (set_env values, connection strings) are never written to audit logs.

Every tool (112)

Grouped by what they touch. Names and descriptions come straight from the server, so this list is what your agent will actually see when it calls tools/list. Every tool is scoped to the project its token is bound to.

Apps and services (15)

• list_apps — List the apps the token can act on, each with its services (slug, kind, status, host, primaryDomain, health, uptimePct24h). health is the live up/down/unknown status; uptimePct24h is the rolling 24h uptime. An account token lists every app the user is a member of; a project token lists just its bound app.
• migrate_data_service — Copy a shared-cluster Postgres onto one of your own hosts (owner-only). The source is left running and untouched: the copy is verified row-by-row before anything switches over, and your app keeps its old connection string until you redeploy. Writes made during the copy are not carried over, so run it in a maintenance window. Postgres only.
• set_git_source — Point a project at a git repository that is NOT on GitHub (GitLab, Bitbucket, Gitea, or any https git host). Owner-only. Takes the https clone URL, a username and a read token; the token is stored encrypted and never returned. There is no push webhook for these hosts, so deploys are manual — call deploy_app or run the CLI from your CI. An ssh remote takes a passphrase-less deploy key instead. Pass url: null to go back to the GitHub App path.
• create_app — Create a new app owned by the token's user (slug globally unique). An app groups its services (web/api/worker/…), shared data services, and app-wide env. Optionally link an already-authorized githubRepo ('owner/repo') the services build from. Then add_service one or more times, add_data_service, add_domain, and deploy_service. Works for account + project tokens.
• delete_app — PERMANENTLY delete an app and EVERYTHING under it (owner-only, IRREVERSIBLE): all of its services, deployments, custom domains, env vars, and managed data services — including dropping each data service's tenant database/role/bucket and tearing down its running containers + routes. There is no undo and no confirmation flag: the account token + app ownership IS the gate. Address the app by appId or appSlug. Returns the deleted counts { appId, deletedServices, deletedDataServices, deletedDeployments }. Account-level.
• add_service — Add a service to an app (owner-only). kind: web|api|worker|cron|static. Pinned deploy config: rootDirectory (monorepo subdir), buildMethod ('auto'|'nixpacks'|'dockerfile'), dockerfilePath, install/build/startCommand, port (default 3000), healthCheckPath (default '/'), subdomain (<subdomain>.primdb.com; omitted → <app>-<service>). The service is the deploy-config source of truth; a backing project is created so deploy/domain/env plumbing works. Address the app by appId or appSlug.
• list_services — List an app's services (slug, kind, status, host, primaryDomain, health, uptimePct24h). health is the live up/down/unknown status; uptimePct24h the rolling 24h uptime. Address the app by appId or appSlug.
• update_service_settings — Update a service's deploy/build settings (owner-only): installCommand, buildCommand, startCommand, rootDirectory, buildMethod ('auto'|'nixpacks'|'dockerfile'), dockerfilePath, port, healthCheckPath, subdomain, deployMode ('approval'|'auto'), memMb (per-service RAM limit in MB, ${MIN_SERVICE_MEM_MB}–${MAX_SERVICE_MEM_MB}; null resets to your tier default — raise it for a heavy service that OOM-crash-loops). Pass a command/path/memMb as null to clear it. Address the service by serviceId, or appSlug + serviceSlug. Returns the updated fields.
• list_projects — List the projects the token can act on (id, slug, name, kind, role). An account token lists every project the user is a member of; a project token lists just its bound project.
• create_project — Compat: prefer create_app + add_service. Create a new project owned by the token's user (quota-checked, slug must be globally unique). kind 'app' (deployable, repo-led — default) or 'db' (standalone managed database). Optionally link an already-authorized githubRepo ('owner/repo'). For a MONOREPO, set rootDirectory (from detect_apps) so this project builds one subdir app, and pin buildCommand/startCommand — create one project per app, all sharing the same githubRepo. Works for both account and project tokens.
• get_project — Get a project (slug, name, linked GitHub repo). For a project token, the bound project. Compat: a project is one app+service — prefer list_apps / list_services.
• detect_apps — Scan this project's linked GitHub repo for deployable apps (monorepo support): subdirectories under apps/, packages/, services/ — plus the repo root — that carry their own package.json or Dockerfile. Returns each app's { path (use as rootDirectory), name, framework, appType (web|api|cli), suggestedBuild, suggestedStart }. To deploy a monorepo, enumerate these then call create_project once per app with the same githubRepo and its path as rootDirectory. Returns { detected:false, reason } when no repo/installation.
• list_repos — List the GitHub repositories the user's PrimDB GitHub App installation can see (to pass as githubRepo to create_project). Returns { connected:false, hint } when the App isn't installed — installing it is a one-time browser step in the dashboard.
• update_settings — Compat: prefer update_service_settings. Update this project's deploy/build settings (owner-only): installCommand, buildCommand, startCommand, rootDirectory, deployMode ('approval'|'auto'), defaultBranch, buildMethod ('auto'|'nixpacks'|'dockerfile'), dockerfilePath (repo-root-relative, e.g. 'Dockerfile.api'), port (the port the app listens on, default 3000), healthCheckPath (the HTTP path the deploy health check probes, default '/'; any HTTP response there — including 401/404 — marks the app healthy, so an auth-gated app deploys). buildMethod 'auto' uses your Dockerfile if present, else nixpacks; 'dockerfile' forces docker build with the whole repo as context (for monorepos). Pass a command/dockerfilePath/healthCheckPath as null to clear it. Returns the updated fields.
• set_app_base_domain — Attach a base-domain ZONE to an APP and auto-derive every service's public host from it (owner-only). Pass a bare apex you own, e.g. secondos.app: the app's web service takes the apex (secondos.app), and every other service takes <label>.<base> where label defaults to the service slug (so an api service → api.secondos.app). Each host is provisioned through the normal custom-domain path — if the apex's DNS is on a PrimDB-connected Cloudflare zone, PrimDB creates the per-host A records + issues TLS automatically; otherwise it returns pending_verify hosts to point at PrimDB. Idempotent: re-running skips hosts already bound to the same service and reports (never steals) a host owned by another app. Override a single service's label with the domainLabel on that service (@ = apex). Returns the resolved base + the per-service hosts with their status. (Set the derived host as a service's canonical primary with set_primary_domain once it's active.)

Deploy, promote, roll back (12)

• deploy — Trigger a production deploy of the default-branch head (owner-only). Returns the new deploymentId; poll get_deployment_status / read get_deployment_logs to follow it. Compat: prefer deploy_service (per app service).
• deploy_app — Trigger a production deploy of EVERY deployable service in an app (owner-only) — each service with a linked repo ships its default-branch head. Returns a per-service list of { serviceSlug, deploymentId } (or an error string per service). Address the app by appId or appSlug.
• deploy_service — Trigger a production deploy of a service's default-branch head (owner-only). Address it by serviceId, or appSlug + serviceSlug. Returns the new deploymentId; poll get_deployment_status / read get_deployment_logs to follow it.
• redeploy — Redeploy an existing deployment's EXACT commit (owner-only) — re-ships that build to production without picking up new default-branch changes. A project token targets its own project; an account token resolves the project from the deployment (pass just the deploymentId). Returns the new deploymentId.
• cancel_deployment — Cancel an in-flight deploy (owner-only): aborts the agent build + drops the queued job so it never reaches Live. Only meaningful for a queued/building deployment; a finished one returns a clean error without side effects. A project token targets its own project; an account token resolves the project from the deployment (pass just the deploymentId).
• list_deployments — List recent deployments for this project (newest first).
• get_deployment_status — Get one deployment by id. A project token is scoped to its project; an account token resolves the project from the deployment (you can pass just the deploymentId — you never need to know its projectId first).
• promote — Promote a ready preview deployment to production (gate-checked).
• rollback — Roll production back to the previous deployment.
• get_deployment_logs — Read the build/run log tail for a deployment — this is how you read a failed build to fix the start command / env, then redeploy. A project token reads its own project's deployments; an account token resolves the project from the deployment, so passing just the deploymentId is enough (no projectId needed).
• get_runtime_logs — Read the RUNTIME (container) logs + live state of a service's current prod deployment — this is how you diagnose a crash-loop / OOM at RUN time (distinct from get_deployment_logs, which returns BUILD logs). Address it by serviceId, appSlug+serviceSlug, or a deploymentId. Owner-only. Returns { containerStatus, oomKilled, exitCode, restartCount, logs }: the app's own stdout/stderr tail plus whether it was OOM-killed / its exit code / restart count. When the container is GONE (crash-loop cleanup removed it) it returns the last-known crash reason + the captured log tail (live:false) so you can still see WHY it died. For an OOM, raise the service memory (update_service_settings memMb) and redeploy.
• diagnose_deployment — Diagnose a FAILED deployment. ALWAYS returns the heuristic guidance first when one was classified at failure — a structured, LLM-free { code, title, detail, suggestedFix, fixable, action? } you can act on directly (e.g. fixable:'settings' + action 'set_env NIXPACKS_NODE_VERSION=20' → call set_env; 'set_start_command' → update_settings; 'regenerate_lockfile' → fix the lockfile in the repo and redeploy). When AI assist is enabled it ALSO adds a richer LLM diagnosis (root cause + fix steps). A project token targets its own project; an account token resolves the project from the deployment (pass just the deploymentId). Advisory only — changes nothing.

Data (23)

• query_sql — Run SQL against the project's shared Postgres (SELECT/DDL/DML; 5s timeout, 200-row cap).
• list_tables — List public tables in the project's Postgres.
• list_data_services — Compat: prefer add_data_service + list_apps (app-level). List this project's managed data services (engine, name, status, host, port). linked:true marks a service shared IN from another of your projects (originProjectSlug names it); linked:false is owned by this project.
• create_data_service — Compat: prefer add_data_service (app-level). Provision a managed data service for this project (owner-only). engine: 'postgres'|'redis'|'meilisearch'|'storage'|'clickhouse'. ClickHouse (PrimDB Analytics) is dedicated-only and needs a Pro plan or higher. Idempotent-friendly: an existing live service of the same engine+name is returned instead of a duplicate.
• add_data_service — Provision a managed data service for an APP (owner-only), shared by every service of the app. engine: 'postgres'|'redis'|'meilisearch'|'storage'|'clickhouse'. ClickHouse (PrimDB Analytics) is dedicated-only and needs a Pro plan or higher. Idempotent-friendly: an existing live service of the same engine+name on the app is returned instead of a duplicate. Address the app by appId or appSlug.
• delete_data_service — Deprovision and delete one of this project's data services by id (owner-only).
• get_service_connection — Get the external connection string for one of this project's data services (the string you'd paste into psql / redis-cli). Scoped to this project's service.
• list_extensions — List the Postgres extensions enabled on one of this project's shared-Postgres services, plus the whitelist of extensions you can enable. Scoped to this project's service.
• enable_extension — Enable a whitelisted Postgres extension (e.g. vector, pg_trgm, uuid-ossp, citext, hstore, pgcrypto) on one of this project's shared-Postgres services (owner-only). Only whitelisted names are accepted; the change applies to this service's own database only.
• link_data_service — DEPRECATED (no-op). Data services are now shared automatically across every service in an app, so linking is no longer required — a sibling service already sees this project's databases. Kept only for backward compatibility; returns a deprecation notice and changes nothing.
• unlink_data_service — DEPRECATED. Data services are app-shared now, so there is nothing to unshare. Still honors a pre-M3 link row (removes it + pulls the injected env) so a legacy cross-app share can be revoked; otherwise a no-op. targetProjectId is the project to unshare from.
• backup_data_service — Take an on-demand backup of one of this project's data services (owner-only). Returns the created backup record. For an account token pass the target projectId. Scoped to this project's service.
• list_data_service_backups — List the backups of one of this project's data services (owner-only). For an account token pass the target projectId. Scoped to this project's service.
• rotate_data_service_credentials — Rotate the credentials of one of this project's data services (owner-only) — mints a fresh password and returns the updated service. Old connection strings stop working. For an account token pass the target projectId. Scoped to this project's service.
• set_data_service_suspended — Suspend (suspended:true) or resume (suspended:false) one of this project's data services (owner-only). Returns the updated service. For an account token pass the target projectId. Scoped to this project's service.
• redis_get — Get a key from the project's Redis (key must be under the project's prefix).
• redis_set — Set a key in the project Redis.
• redis_del — Delete a key in the project Redis.
• redis_keys — List the project Redis keys (own prefix only).
• storage_list — List objects in the project's storage bucket.
• storage_get_url — Get a presigned download URL for an object.
• storage_put_text — Write a text object to the project bucket.
• storage_delete — Delete an object from the project bucket.

Environment and domains (7)

• list_env — List the project env var names (values are never returned).
• set_env — Set an env var (UPPER_SNAKE_CASE). App-native: pass appId/appSlug to set it APP-WIDE (shared by every service of the app — the default), or serviceId (or appSlug+serviceSlug) to set a per-SERVICE override (wins over the app-wide value at deploy). Passing a legacy projectId (or using a project token) still works and writes app-wide via that project (compat).
• delete_env — Delete a user-set project env var (managed vars are protected).
• add_domain — Bind a custom hostname to a SERVICE (owner-only). App-native: pass serviceId (or appSlug+serviceSlug) to bind it to that service; a legacy projectId (or a project token) binds it to that project's service (compat). If the hostname's DNS is on a PrimDB-connected Cloudflare zone, PrimDB creates the A record and issues TLS automatically (status → pending_tls, managed:true). Otherwise it returns the CNAME + TXT records to publish (status pending_verify, managed:false); verify happens automatically once they resolve. A hostname can belong to only ONE service — a hostname already claimed is denied.
• list_domains — List the custom domains bound to a SERVICE (hostname, status, tlsIssuedAt, lastError, isPrimary). App-native: pass serviceId (or appSlug+serviceSlug); a legacy projectId/project token targets that project's service (compat). isPrimary:true marks the canonical primary domain — the one host that serves the app while every other host 308-redirects to it (set with set_primary_domain).
• set_primary_domain — Set (or clear) a SERVICE's canonical PRIMARY domain (owner-only). App-native: pass serviceId (or appSlug+serviceSlug); a legacy projectId/project token targets that project's service (compat). Pass a hostname that is one of the service's ACTIVE custom domains to make it primary: every OTHER host — the platform <subdomain>.primdb.com and any non-primary custom domains — then 308-redirects to https://<primary>$uri (Vercel-style canonical), and only the primary serves the app. Pass null to clear it (all hosts serve directly again). The redirect takes effect on the next deploy/promote. A hostname that isn't an active custom domain of this service is rejected.
• remove_domain — Unbind a custom hostname from a SERVICE (owner-only). App-native: pass serviceId (or appSlug+serviceSlug); a legacy projectId/project token targets that project's service (compat). Stops routing + tears down its TLS.

Your own servers (11)

• add_host — Enroll one of YOUR OWN servers as a PrimDB host you can deploy to (in addition to the shared platform host). Returns { host, enrollmentToken, installCommand } — the enrollmentToken is shown ONCE (store it; only its hash is kept) and the installCommand is the Docker run to paste on that server (mounts its docker socket, connects the agent to the relay with the token). The host shows up in list_hosts as pending until its agent connects, then active. Account-level (acts on your account).
• list_hosts — List the hosts you can deploy to: your enrolled servers plus the shared platform co-host (isPlatform:true). Each has { id, name, status (pending|active|offline), isPlatform, capabilities, protocolVersion, region, publicIp, lastSeenAt }. Never returns the enrollment token or the internal agent runtime id. Account-level.
• activate_host — #SH-07p2: activate one of YOUR enrolled hosts so it starts receiving deploys. A newly-enrolled host connects as pending and receives NO work until activated (a stolen enrollment token alone can't start deploying). Owner-only; the platform co-host is always active. Account-level.
• remove_host — Remove one of YOUR enrolled hosts (owner-only). The shared platform co-host cannot be removed. Stop the agent container on that server afterwards. Account-level.
• set_service_host — Pin a service to one of your hosts so its NEXT deploy lands there (owner-only). Pass hostId (from list_hosts) to target a host, or null to reset to the shared platform co-host (the default). Address the service by serviceId or appSlug+serviceSlug. The change takes effect on the next build/deploy of the service.
• discover_workloads — List the containers already running on one of YOUR enrolled hosts that PrimDB does NOT manage — a read-only inventory (the agent only lists; it never touches anything). Each returns { id, name, image, state, status, ports, orchestrator }. orchestrator (coolify/compose/swarm) flags a container another tool manages — adopting one of those risks two managers fighting over it. Blocked on the shared PrimDB host (its containers belong to other tenants). Returns { workloads: null } when the host's agent isn't connected. Account-level.
• adopt_workload — Adopt a container found by discover_workloads as an observe-only PrimDB app on one of YOUR hosts. PrimDB records it as an app+service pinned to that host but NEVER builds, deploys, or routes it — you keep managing the container with whatever runs it today; PrimDB just gives you a handle to see it. Pass the workload's name (and optionally its image). Blocked on the shared PrimDB host. If the workload is orchestrator-managed (coolify/compose/swarm per discover_workloads), adopting is still safe (observe-only) but do it deliberately. Returns { appSlug, serviceSlug }. Account-level.
• enable_shared_hosting — Fleet: turn one of YOUR enrolled active hosts into a shared-DB host (owner-only). The host's agent stands up a tenant Postgres + Redis on its own box and PrimDB stores the minted admin URLs (encrypted) so this host's OWN shared data services provision there. Does NOT add the host to the global placement pool (a customer box never receives other tenants' workloads). Requires a live agent. Idempotent. Account-level.
• list_managed_host_options — List the managed-server catalog PrimDB can provision on your behalf: the available locations (Hetzner regions) and serverTypes (each { id, label, vcpu, ramGb, diskGb, dedicated, upcoming, monthlyEur } — monthlyEur is the customer price). upcoming:true types are shown but not purchasable yet. Feed a serverType id + location into provision_managed_host. Account-level.
• provision_managed_host — Have PrimDB provision + manage a dedicated Hetzner server for you (owner-only), auto-enrolled as a host you can deploy to. Pass a serverType id + location from list_managed_host_options, and a name label. Billed at the customer monthly price. Returns { host, customerMonthlyEur }. Account-level. (Provisioning is temporarily unavailable until payment is wired — you'll get a clear 'launching soon' error.)
• security_events — #SH-15: the recent SECURITY STREAM for your account — security-relevant audit events across the projects you own plus platform-scoped events. Actions: env_reveal, token_created/revoked, app_deleted, domain_added/removed, and access DENIALS (agent_message_denied = a cross-host forgery attempt, agent_register_denied = a runtime-id hijack attempt). Each row: { action, projectId, userId, payload (never a secret VALUE), createdAt }. Pass limit (default 100, max 500). Account-level.

End-user auth (20)

• enable_auth — Enable PrimDB Auth (built-in end-user authentication) for this project (owner-only). REQUIRES the project to already have a ready Postgres data-service — Auth stores its users in your project's OWN Postgres; if there is none you get a clear 'add a database first' error. Mints an encrypted per-project JWT secret, bootstraps the auth_users/auth_sessions/auth_passkeys tables in your database (idempotent), and injects PRIMDB_PROJECT_ID + PRIMDB_AUTH_URL into your app's env. Idempotent — re-enabling re-asserts the tables + env and returns the existing config (never returns the secret).
• disable_auth — Disable PrimDB Auth for this project (owner-only). Removes the control-plane config (dropping the JWT secret) and the injected env. Your auth_users / auth_sessions / auth_passkeys tables are LEFT IN PLACE in your database (they are your data) — re-enabling reuses them. Idempotent.
• auth_status — Get PrimDB Auth status for this project: { enabled, canEnable, config }. canEnable is true once the project has a ready Postgres data-service (required to enable). config (when enabled) carries the enabled methods, access-token TTL, min password length, and magic-link rate — never any secret.
• update_auth_settings — Update a project's PrimDB Auth settings (owner-only). Toggle methods (emailPasswordEnabled / magicLinkEnabled / passkeyEnabled / mfaEnabled / samlEnabled), set accessTokenTtlSeconds, minPasswordLength, magicLinkRatePer15Min, and an emailProvider override ({ provider, from, apiKey } or null to clear). Numeric knobs are clamped server-side; at least one method must stay enabled. Requires Auth enabled. For an account token pass the target projectId. Returns the fresh Auth config view (never secrets).
• list_auth_users — List a project's END-USER auth accounts (PrimDB Auth admin; owner-only) with server-side search + filter + pagination. Filters: query (email substring), status ('active'|'suspended'), limit (default 25, max 100), offset. Returns { users, total, limit, offset }. For an account token pass the target projectId. Never returns password hashes or secrets.
• set_auth_user_suspended — Suspend (suspended:true) or unsuspend (suspended:false) a project's PrimDB Auth end-user (owner-only). Suspending also revokes every live session so they're locked out immediately. For an account token pass the target projectId. Returns { id, status }.
• delete_auth_user — Delete a project's PrimDB Auth end-user by id (owner-only) — cascades their sessions + passkeys and clears their Redis state. A user that isn't this project's is NOT_FOUND. For an account token pass the target projectId.
• revoke_auth_user_sessions — Revoke a PrimDB Auth end-user's session(s) (owner-only). Pass sessionId to revoke ONE session; omit it to revoke ALL of the user's sessions ('log out everywhere'). For an account token pass the target projectId. A missing session (single-revoke) is NOT_FOUND.
• rotate_auth_secret — Rotate a project's PrimDB Auth JWT signing secret (owner-only). Invalidates every live access token immediately (refresh tokens survive). For an account token pass the target projectId. Returns the refreshed Auth config view (never the secret).
• list_auth_oauth — List a project's configured OAuth social providers (owner-only): each { clientId, enabled, callbackUrl } — NEVER the client secret. For an account token pass the target projectId.
• set_auth_oauth_provider — Configure a project's OAuth social provider (owner-only). provider is the provider id (e.g. 'google', 'github'). Omitting clientSecret keeps the stored one (so you can toggle enabled without re-entering it). The secret is encrypted at rest and never echoed back. For an account token pass the target projectId. Returns the fresh (secret-free) providers view.
• delete_auth_oauth_provider — Disconnect a project's OAuth social provider (owner-only) — removes its config including the encrypted secret. provider is the provider id. Idempotent. For an account token pass the target projectId. Returns the fresh providers view.
• get_auth_saml — Read a project's SAML SSO config (owner-only): entity id + SSO url + enabled + the SP coordinates (metadata/entity id/ACS URL) to register with the IdP + whether the owner holds the SSO add-on. NEVER the IdP certificate. For an account token pass the target projectId.
• set_auth_saml — Set a project's SAML SSO config (owner-only, requires the SSO add-on). entityId = IdP entity id, ssoUrl = IdP SSO URL, certificate = IdP X.509 PEM (or base64 cert body). The cert is encrypted at rest and never echoed back. Enabling requires all three set. For an account token pass the target projectId. Returns the fresh (cert-free) view.
• delete_auth_saml — Disconnect a project's SAML SSO config entirely (owner-only) — removes it including the encrypted cert. Idempotent. For an account token pass the target projectId. Returns the fresh view.
• list_auth_webhooks — List a project's PrimDB Auth webhook endpoints (owner-only): each { url, enabled, eventTypes } + a secret last-4 HINT — NEVER the full signing secret. For an account token pass the target projectId.
• create_auth_webhook — Register a PrimDB Auth webhook endpoint (owner-only). Validates the URL (SSRF guard) and mints a signing secret returned EXACTLY ONCE as secret (store it — only its hash is kept). eventFilter optionally restricts which auth events are delivered (default: all). For an account token pass the target projectId. Returns { endpoint, secret }.
• update_auth_webhook — Update a PrimDB Auth webhook endpoint (owner-only): change its url (re-validated through the SSRF guard), enabled flag, or eventFilter. An endpoint that isn't this project's is NOT_FOUND. For an account token pass the target projectId. Returns { endpoint }.
• rotate_auth_webhook_secret — Rotate a PrimDB Auth webhook endpoint's signing secret (owner-only) — returns the new secret EXACTLY ONCE; old signatures immediately stop verifying. An endpoint that isn't this project's is NOT_FOUND. For an account token pass the target projectId. Returns { endpoint, secret }.
• delete_auth_webhook — Delete a PrimDB Auth webhook endpoint by id (owner-only). An endpoint that isn't this project's is NOT_FOUND. For an account token pass the target projectId.

Preview feedback (8)

• get_notes — List feedback notes for the project (optionally filtered by path/status).
• list_note_routes — List routes that have feedback notes, with open/total counts.
• create_note — Create a feedback note on a route (authored as the agent/dev).
• resolve_note — Mark a feedback note resolved.
• list_reviewers — List the project's review allowlist (magic-link overlay reviewers; owner-only). For an account token pass the target projectId.
• add_reviewer — Add a person to the project's review allowlist by email (owner-only) — widens who may open the preview overlay and leave feedback. For an account token pass the target projectId.
• remove_reviewer — Remove a reviewer from the project's review allowlist by id (owner-only). A reviewer that isn't this project's is NOT_FOUND. For an account token pass the target projectId.
• revoke_reviewer_sessions — Kill a reviewer's live overlay tokens (owner-only) — keeps them on the allowlist but invalidates any leaked link. A reviewer that isn't this project's is NOT_FOUND. For an account token pass the target projectId.

Team, tokens and audit (7)

• list_members — List a project's members (userId, email, name, role, addedAt). Any member may read. For an account token pass the target projectId.
• invite_member — Invite a person to a project by email (owner-only). Sends them an invite link and returns the pending invite. Supersedes any still-open invite for the same email. For an account token pass the target projectId.
• remove_member — Remove a member from a project by userId (owner-only). The owner cannot remove themselves (transfer ownership first). For an account token pass the target projectId.
• list_tokens — List the API tokens for a project (owner-only). Returns each token's { id, name, scope, lastUsedAt, createdAt, revokedAt } — never the plaintext. For an account token pass the target projectId; a project token lists its own project's tokens.
• create_token — Mint a new API token for a project (owner-only). Returns the plaintext token EXACTLY ONCE (store it; only its hash is kept). By default the token is BOUND to this project (scope 'mcp'); pass scope 'account' for an account-wide token that can act on every project you own. For an account token pass the target projectId.
• revoke_token — Revoke an API token by id (owner-only). For an account token pass the target projectId. A token that isn't this project's (or is already revoked) is NOT_FOUND.
• list_audit_log — List a project's audit log (deploys, member/token/data-service/auth changes) — most recent first. Any member may read. limit defaults to 200 (max 200). For an account token pass the target projectId. Returns each entry's { id, action, payload, createdAt, userId, userEmail } (userEmail is null for dispatcher-originated rows).

Billing (read only) (4)

• get_subscription — Get YOUR account's subscription: { tier, status, currentPeriodEnd, limits } (limits are the tier's plan caps). Creates a default free subscription on first read. Account-level.
• get_usage — Get YOUR account's usage for the current month: { month, tier, limits, buildMinutesUsed, commentsCreated }. Account-level.
• get_bill — Get YOUR computed monthly bill (platform base + BYO fee + managed servers) as line items + a USD total. Account-level.
• list_addons — List the à-la-carte add-on catalog + presets + YOUR current quantities + line items + the live monthly add-on total (USD). Account-level.

Analytics wiring (5)

• connect_gurulu — Connect the user's Gurulu account (analytics) via OAuth. Returns the current connection status; if not connected, returns a connectUrl the user opens in a browser to authorize (one-time). Once connected, call enable_analytics for an app. Returns { configured:false } when the Gurulu integration isn't set up on this PrimDB.
• enable_analytics — Enable Gurulu analytics for an app (owner-only). Requires a connected Gurulu account (call connect_gurulu first). By default provisions a NEW Gurulu workspace for the app; pass workspaceId to instead LINK an EXISTING Gurulu project of yours (list them with list_gurulu_workspaces) — one PrimDB app ↔ one Gurulu workspace. Either way it injects the workspace's public ingest key as the app-wide NEXT_PUBLIC_GURULU_WORKSPACE env (every service inherits it) and returns { workspaceId, snippet, dashboardUrl }. Idempotent — re-enabling returns the existing workspace; passing a different workspaceId RE-LINKS the app. Pass agentCli:true to also get the exact npx @gurulu/cli … init command to self-verify during the next build. Address the app by appId or appSlug.
• list_gurulu_workspaces — List the Gurulu projects (workspaces) in your connected Gurulu account so you can LINK an app to one with enable_analytics { workspaceId }. Requires a connected account (connect_gurulu first). Returns [{ workspaceId, name, domain, environment, status }] — never any ingest key. Account-level (acts on your Gurulu connection, not a specific app).
• analytics_status — Get Gurulu analytics status for an app: { configured, connected, enabled, workspaceId?, dashboardUrl?, wireMode?, wireStatus?, prUrl? }. wireMode (pr|build_time|manual) + wireStatus (none|pr_open|wired|failed) + prUrl describe whether the SDK snippet is wired into the code. Address the app by appId or appSlug. Never returns any token or ingest key.
• wire_analytics — Wire the Gurulu SDK snippet into an app's code so real events flow (owner-only; analytics must already be enabled). mode:'pr' opens a GitHub PR on the app's OWN repo (over the GitHub REST API) that inserts the self-contained CDN <script> tag into the app's HTML entry point (returns the PR url) — persistent. mode:'build_time' flips a flag so the NEXT deploy injects the snippet in the build context only — ephemeral (the repo is never touched, PrimDB-only). A read-only GitHub App returns a clear 'grant write + PR permission' error, never a crash. Address the app by appId or appSlug.