Skip to content

Connecting an AI assistant (MCP)

PocketBase Cloud runs an MCP server, so an AI assistant can manage your projects, PocketBase instances, deploys, domains and data for you. You sign in once and choose read-only or read and write access. Scripts and CI skip the sign-in and send a CLI access token instead.

The server URL is:

https://mcp.pocketbasecloud.com/mcp

Paste it exactly: the address ends in /mcp. Setup happens in your assistant.

Connect your assistant

Claude (claude.ai and Claude Desktop)

  1. Open Customize → Connectors and click Add custom connector
  2. Paste the server URL. If Claude asks how it should identify itself, choose Register automatically
  3. Click Add, then Connect next to the new connector

On a Team or Enterprise plan an Owner adds it instead, under Organization settings → Connectors → Add → Custom, and each member then clicks Connect under Customize → Connectors. The Free plan allows one custom connector.

ChatGPT

  1. Open Plugins, click + and choose Add custom MCP server
  2. Give it a name, enter the server URL under Connection, and choose OAuth authentication
  3. Confirm with I understand and want to continue, then Create as a plugin

In a new chat, type @ and pick the plugin to use it.

Claude Code

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

Then run /mcp in Claude Code and choose pocketbasecloud to sign in.

Cursor and VS Code

Use the Add to Cursor or Add to VS Code button on the MCP server page, then sign in when the editor asks. To add it by hand, create an HTTP MCP server named pocketbasecloud with the server URL.

Sign in and choose the access

When you connect, the assistant opens the portal at portal.pocketbasecloud.com. Sign in if you aren’t already. The page names the app that is asking and the site it returns you to. An app that only named itself shows Unverified app name — continue only if you just started connecting from that assistant. The page also shows the account you are signed in as; Switch changes it.

Choose what the assistant may do:

Access What it allows
Read and write (selected first) Everything Read only allows, plus creating projects and PocketBase instances, changing an instance’s settings and continuous backup, moving an instance to the compute your plan includes, adding and removing custom domains, deploying hooks and static sites, changing collections, API rules and records, running cron jobs and creating backups. Deleting anything waits for you to confirm that exact change
Read only Seeing your projects, instances, deploys and logs, your plan and the regions you can use, and the collections and records in your instances

Under Projects, keep All my projects or pick one project to keep the assistant inside it. Click Allow access and the portal returns you to the assistant; Cancel returns you without granting anything. If the app runs on your own computer, as Claude Code does, the same page warns you — continue only if you just started connecting from it.

Narrowing or widening a connection

Options in the server URL change what a connection offers:

Option What it does
?read_only=true Exposes only the tools that read. It can make an approved connection read-only, never lift it
?project_ref=<project id> Limits every tool to one project. With sign-in it may only repeat the project you approved
?features=<keys> Chooses which tool groups the assistant sees, by the comma-separated keys in Tools. The default is account,resources,deploy,domains,database,docs

Combine them with &, for example a read-only connection to one project:

https://mcp.pocketbasecloud.com/mcp?read_only=true&project_ref=<project id>

read_only and project_ref only narrow a connection. features widens it when you add one of the two opt-in groups:

  • env — list, set and delete environment variables. Values pass through the conversation, so set secrets with pbc env import on your own machine instead
  • database_admin — empty or delete a collection, remove fields, and restore or delete a backup. All but delete_backup back the instance up first unless told not to

Tools

Group Key Tools
Account & projects account list_projects, get_project, create_project, get_plan, list_regions, get_overview
Resources resources list_resources, get_resource, create_pocketbase, update_pocketbase_config, set_continuous_backup, move_resource, delete_previous_copy
Deploys & logs deploy get_logs, list_deployments, get_deployment, rollback_deployment, get_deploy_command, diagnose_resource
Cloud files deploy list_cloud_files, read_cloud_file, search_cloud_files, edit_cloud_file, write_cloud_files, download_cloud_files, create_upload_link; deprecated: list_hooks, get_hook, deploy_hooks, deploy_public
Version history deploy list_revisions, get_revision, compare_revisions, preview_restore_revision, restore_revision
GitHub deploy list_unpushed_changes, push_to_github
Custom domains domains add_domain, verify_domain, check_domain, remove_domain
Database (inside an instance) database list_collections, get_collection, list_records, get_request_logs, list_backups, list_crons, count_records, get_record, check_security, generate_types, preview_collections, check_performance, apply_collections, update_api_rules, create_record, create_records, update_record, create_backup, run_cron, delete_record
Test and settings (inside an instance) database call_pocketbase, create_test_user, get_pocketbase_settings, update_pocketbase_settings, send_test_email
Docs docs search_docs
Environment variables (opt-in) env list_env_vars, set_env_vars, delete_env_vars
Database admin (opt-in) database_admin truncate_collection, delete_collection, remove_fields, restore_backup, delete_backup

The two opt-in groups are off until you add their key to features.

The cloud file tools (kind: pocketbase for now) let an assistant work on a PocketBase instance’s pb_hooks, pb_migrations and pb_public the way it works on a local project: read and search files, edit part of a file, and create, overwrite, rename and delete files. Each change goes live at once as one revision and one deployment, and deleting asks for your approval first. Files with the same path are overwritten and everything else stays; migrations cannot be deleted or renamed, and list_cloud_files on pb_migrations shows which ones already ran, and compare_revisions with a path shows the lines a revision changed in that file (one that ran is never run again, so a change goes in a new migration). get_logs takes sinceRevision, since, contains and errorsOnly to read only what happened after a change. An instance that deploys from GitHub gets the changes only when you ask the assistant to push them (push_to_github).

With instance access on, the assistant can also test what it builds and set up email:

  • call_pocketbase sends a request to the instance as a visitor, as a user, or as the superuser (your own routes only), and returns the status and answer, so the assistant can check a route or an API rule
  • create_test_user adds a verified test user to act as
  • create_record and update_record fill file fields (an avatar, photos) from an https link or base64 content, up to 5 MB a file
  • get_pocketbase_settings and update_pocketbase_settings read and change the app name and URL, the sender, SMTP, storage, backups, rate limits and logs. Passwords and secrets are never shown; type them in the admin panel rather than in the chat
  • send_test_email sends a verification, password-reset or email-change email to check the mail settings

list_hooks, get_hook, deploy_hooks and deploy_public are deprecated: they still work, but the cloud file tools replace them.

Scripts and CI: use the CLI access token

A client that cannot sign in through a browser sends the CLI access token in its requests instead:

  1. In the portal, open Account and go to Deploy From CI
  2. Click Copy next to CLI access token

The token comes from the portal only — pbc has no command that prints one. Pass it as a header:

claude mcp add --transport http pocketbasecloud \
  "https://mcp.pocketbasecloud.com/mcp?read_only=true" \
  --header "Authorization: Bearer <CLI access token>"

The server forwards this token to PocketBase Cloud as it is. Anyone holding it can deploy, read and delete as you, and signing in again does not revoke it: keep it in an encrypted secret, never in a repository, and copy a fresh one when it expires. Assistants that can sign in should use the sign-in above instead.

Safety and your data

  • Tools that delete or restore ask for your approval first.
  • Database tools reach your instance through PocketBase Cloud. System collections and instance settings are never touched.
  • The server never stores records, files or logs from your instances. It passes them to your assistant and forgets them.

Disconnecting

Remove the connector in the assistant to stop using it. The server deletes the connection you approved after 30 days without use; to have it deleted sooner, email [email protected]. A connection made with the CLI access token lasts until that token expires.

What the server keeps

To keep you connected, the server stores the connection you approved, with your PocketBase Cloud session encrypted inside it, until it goes 30 days without use. For reliability it records each tool call — which tool, the instance or collection it targeted, whether it worked, a shortened error message and how long it took — with a pseudonymous account ID, and deletes those records after 90 days. The privacy policy has the details.

Troubleshooting

  • “This sign-in has expired” — the sign-in page stays valid for 10 minutes. Start connecting again from the assistant
  • A tool is missing — the connection may be read-only, limited to one project, or the tool may belong to an optional group
  • Creating or deploying is refused — the account’s plan does not allow it; the assistant says what the action needs