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)
- Open Customize → Connectors and click Add custom connector
- Paste the server URL. If Claude asks how it should identify itself, choose Register automatically
- 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
- Open Plugins, click + and choose Add custom MCP server
- Give it a name, enter the server URL under Connection, and choose OAuth authentication
- 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 withpbc env importon your own machine insteaddatabase_admin— empty or delete a collection, remove fields, and restore or delete a backup. All butdelete_backupback 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_pocketbasesends 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 rulecreate_test_useradds a verified test user to act ascreate_recordandupdate_recordfill file fields (an avatar, photos) from an https link or base64 content, up to 5 MB a fileget_pocketbase_settingsandupdate_pocketbase_settingsread 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 chatsend_test_emailsends 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:
- In the portal, open Account and go to Deploy From CI
- 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