Guide·9 min read

Connect Claude to Clicbase with MCP: the guide

The hosted connector and its 85 tools (database, site and deployment, email and mailboxes, backups, AI, support, account), the npx @clicbase/mcp server, key scope and the six traps that answer 200 OK.

mcpclaudeiaapi

Clicbase plugs into Claude, and any MCP-compatible assistant, in one minute. The hosted connector gives the assistant 85 tools: your database, files, site and deployments, email, backups, AI and account. It acts strictly within the scope of the key you give it.

In short

  • Hosted connector: https://clicbase.com/api/mcp, added in claude.ai or Claude Code. Sign in with OAuth or a cbk_… key. This is the one with all 85 tools.
  • Local server: the npm package @clicbase/mcp (MIT license), run with npx, with a single-project variant. It covers the database, files and SFTP, and has a read-only mode.
  • Scope: a Docker key only sees that Docker. Everything else answers "not found", however hard the assistant insists.
  • No secret goes through the conversation: no mailbox password, no backup link, no secret value. Anything sensitive is emailed to the owner.

1. The hosted connector

In claude.ai: Settings → Connectors → Add custom connector, URL https://clicbase.com/api/mcp, then Connect. Sign-in uses OAuth: no secret travels in the URL.

In Claude Code, with a key:

claude mcp add --transport http clicbase https://clicbase.com/api/mcp \
  --header "Authorization: Bearer cbk_..."

Create the cbk_… key in the dashboard: the Docker's ⋮ menu → Docker → API key. It only works for that Docker. A VPS key covers all of its Dockers.

Every tool is declared as read or write. claude.ai asks for your permission before a write tool, and you set each tool (always allowed, ask, blocked) in the connector settings. A newly added tool only shows up after reconnecting the connector or starting a new conversation.

2. Database

ToolWhat it does
list_projects, list_tablesYour projects, then a project's tables. Start here.
describe_tableOne table in detail: columns, keys, indexes, RLS, policies and grants.
create_databaseCreates a project (an isolated PostgreSQL database) and returns its keys.
run_sqlRuns SQL: tables, data, security rules (RLS).
apply_migration, list_migrationsApplies a schema change in a transaction and records it in the history. If the SQL fails, nothing is applied.
get_advisorsSecurity and performance audit: tables without RLS, write policies without with check, missing indexes, with the SQL to fix them.
get_logsThe PostgreSQL log: RLS refusals, missing grants, errors, grouped. Never row contents.
generate_typescript_typesYour database types, in the supabase gen types format.
get_credentialsThe API URL and the anon key. The service key only if you ask for it.
enable_realtimeTurns realtime on for a table, or off (actif: false).
rename_projectChanges a project's display name; API and keys stay the same.
pause_project, resume_projectStops a project's whole API (503 "paused"), data kept, then brings it back. The owner is notified by email.

3. Users and storage

ToolWhat it does
list_project_usersYour application's users (not Clicbase accounts): email, method, confirmation, last sign-in.
manage_project_userConfirm an email, send a password reset, sign out everywhere, delete.
set_oauth_provider, get_oauth_providerAdds Google sign-in to your project, and checks it is on, with the redirect URI to declare at Google.
set_signup_confirmationRequire new users to confirm their email. Refused if unconfirmed accounts would be locked out.
set_auth_domainThe project's sign-in domain (e.g. auth.mysite.com), with the DNS record and the URIs to declare at Google.
list_storage, create_storage_bucketBuckets and their files; create one, public or private per user.
set_bucket_publicMake a bucket public or private. Going public requires typing its name again.
upload_storage_file, delete_storage_filesUpload a file (10 MB per call), remove files by exact path.

4. Hosted site and deployment

ToolWhat it does
list_sitesYour sites. The site_id used by the other tools comes from here: it is neither the domain nor the slug.
list_site_files, read_site_fileWhat the site actually serves, whether published over SFTP or deployed from Git.
write_site_files, append_site_filePublish files, and large ones in chunks.
create_sftp_account, list_sftp_accounts, delete_sftp_accountA dedicated SFTP account shown once, the list of existing accounts, and deleting them after use.
set_site_maintenanceA "Site under maintenance" page in place of the home page, then back to normal.
deploy_site, list_deployments, rollback_siteStart a Git deployment, follow it (build log included), roll back to a previous version without rebuilding.
set_site_build, set_auto_deployBuild command and output folder; deploy on every push.
set_site_onlineTake a site fully offline, or back online, without deleting anything.
set_site_privateProtect a site with a username and password, to show it before launch. The password is emailed to the owner.
set_home_pageMake another page the home page; the old one is kept under another name.
list_env_vars, set_env_var, delete_env_varEnvironment variables of a Git site. Names only: a value is never read back.
set_site_domain, check_domainSet your domain, then check DNS and what each address really serves, apex and www.
get_site_healthA site's health in one call: addresses, published content, recent visitors, database status.

5. Functions and secrets

ToolWhat it does
list_functions, get_function_logsYour server functions, and their recent log: calls, status, duration, errors, console.log.
list_secrets, set_secret, delete_secretThe vault your functions read (ctx.secret("NAME")). Names only, never a value.

6. Email

ToolWhat it does
check_email_dnsSPF, DKIM and DMARC of a sending domain, with the value found.
send_test_emailA real test email, to the project's address or yours, nothing else.
set_email_smtpYour own SMTP. Without it, Clicbase's is used.
list_email_templates, set_email_templateTemplates (sign-up, password, order). A template that would lose its link is refused.
set_email_senderChoose which project mailbox sends which templates (e.g. billing@ for orders).
check_bimiCheck that the brand logo can show next to your emails.
list_email_log, retry_emailThe project's emails, the failed ones, and retrying them one by one.
list_mailboxes, create_mailboxMailboxes on your domain (contact@…). The password is emailed to the owner, never given to the AI.
set_mailbox_enabled, reset_mailbox_password, delete_mailbox, set_mailbox_labelTake a mailbox offline, give it a new password (emailed to the owner), delete it. A mailbox a project sends its emails through is never cut off silently.

7. Backups

ToolWhat it does
list_backupsOne backup per night, kept seven days on the server and fourteen days as an encrypted off-site copy.
create_backupA backup right now, for example before a risky migration.
request_backup_downloadGet your database: the link is emailed to the owner, valid one hour, single use.

8. AI, account and servers

ToolWhat it does
get_ai_credit, get_ai_usageYour AI credit, and usage per function and per user of your application.
request_ai_creditRequest a top-up: payment instructions are emailed, no money moves from the conversation.
list_ai_instructions, set_ai_instructionThe instructions of your AI functions, rewritten without redeploying.
get_account, update_accountYour account details, and its name. Password and email only change on the website.
get_billingYour plan, invoices, and usage per project.
list_servers, list_dockersYour servers and Dockers, with each database's real resource usage.
search_docsSearches the documentation and blog guides, and returns each passage with its link.
contact_support, list_support_ticketsWrite to support when a problem won't resolve, and follow the answer. The message is marked as written by an AI.

9. What you can ask

  • "Create a bookings table, protect it with RLS, and give me the TypeScript types."
  • "My deployment failed, read the log and tell me why."
  • "My domain doesn't show my site, check the DNS."
  • "Take a backup, then apply this migration."
  • "Why aren't my confirmation emails arriving?"
  • "How much did AI cost me this month, and which user uses the most?"
  • "Put the site in maintenance while I publish the new version."
  • "Make the site private, I want to show it to my client before launch."

10. The local server, via npx

All-in-one, to create and manage projects with a cbk_… key:

claude mcp add clicbase \
  -e CLICBASE_API_KEY=cbk_... \
  -e CLICBASE_READ_ONLY=1 \
  -- npx -y -p @clicbase/mcp clicbase-mcp

Single project, with that project's URL and service key (dashboard, the project's API section):

claude mcp add my-db \
  -e CLICBASE_DB_URL=https://clicbase.com/db/<slug> \
  -e CLICBASE_SERVICE_KEY=<service key> \
  -e CLICBASE_READ_ONLY=1 \
  -- npx -y -p @clicbase/mcp clicbase-db-mcp

-p names the package, the next argument the command: the package ships several. With CLICBASE_READ_ONLY=1, write tools are not refused, they are absent: a tool that isn't listed is never requested. The local server covers the database, files, SFTP, Google sign-in and SMTP; deployment, email, backups and AI are on the hosted connector.

11. What protects your data

  • Key scope is enforced server-side: a site or project outside it answers "not found".
  • Secrets never go through the AI: a new mailbox's password and a backup download link are emailed to the owner; secret and environment variable values are never read back.
  • Hidden files (.env, .git) are refused at every level, for reading and writing.
  • A site built from Git refuses file uploads: the next build would overwrite them.
  • Never the site's SFTP password: the assistant creates a dedicated account, shown once, deleted afterwards.
  • Every tool call is logged, with the tool, its target and the key that made it, successes and refusals alike.

12. The six traps that answer 200 OK

The server hands them to the assistant as soon as it connects:

  1. with check is not using: on INSERT and UPDATE, PostgreSQL only evaluates with check.
  2. Every new table opens CRUD to authenticated: a grant select restricts nothing, you need revoke.
  3. Every DDL ends with notify pgrst, 'reload schema';.
  4. service_role needs BYPASSRLS, otherwise 200 OK and an empty array.
  5. An Edge function returns { status, body }, never new Response(...).
  6. Project auth (auth.uid()) is not platform auth.

For AI assistants

  • Start with list_sites or list_projects: the site_id used by other tools is a technical identifier, neither the domain nor the slug.
  • Before assuming how Clicbase works, call search_docs.
  • Before a risky migration, call create_backup.
  • If a problem won't resolve, open a ticket with contact_support rather than insisting.
  • Clicbase has no Docker registry and no docker login: don't invent host names.
  • Never ask the user to paste a key or password into the conversation: they set it in the MCP client configuration.
  • A project's anon key is public and goes in the browser; the service key bypasses RLS and stays server-side.
  • Reference documentation: clicbase.com/docs#mcp.

Launch your backend in minutes

Postgres database, API, auth, storage, realtime, plus your emails and domain. Free to start.

Also read

← All articles