Connect
Connect AI assistants (remote MCP)
Tested with:Source and client configuration documentation reviewed on 2026-10-16 (ZB-748, ZB-750); live OAuth and destructive-consent acceptance pending.
The hosted MCP server lets an AI assistant work with your Databasezy organization without an API key. You sign in once in the browser, choose what the assistant may do, and the client receives short-lived tokens that only work against the MCP server.
| Server URL | https://mcp.databasezy.com/mcp |
| Transport | Streamable HTTP (MCP 2025-06-18 and later) |
| Authorization | OAuth 2.1: authorization code with PKCE (S256 only); client ID metadata documents or dynamic client registration |
| Authorization server | https://api.databasezy.com (/.well-known/oauth-authorization-server) |
| Resource metadata | https://mcp.databasezy.com/.well-known/oauth-protected-resource/mcp |
| Scopes | mcp (full) and mcp:read (read-only) |
| Privacy policy | docs.databasezy.com/legal/privacy (also op_policy_uri and resource_policy_uri in the metadata) |
Connect a client
Section titled “Connect a client”Your client discovers everything from the server URL. You never paste an API key.
Claude (claude.ai and Claude Desktop)
Section titled “Claude (claude.ai and Claude Desktop)”- Open Settings > Connectors and choose Add custom connector.
- Name it
Databasezyand enterhttps://mcp.databasezy.com/mcp. - Choose Connect. A Databasezy sign-in and consent page opens; approve it.
Claude Code
Section titled “Claude Code”claude mcp add --transport http databasezy https://mcp.databasezy.com/mcpThen run /mcp in Claude Code and choose Authenticate for databasezy. Claude Code opens the browser and
listens on a loopback port (http://localhost:<port>/callback) for the result.
Cursor
Section titled “Cursor”Add the server to ~/.cursor/mcp.json (or .cursor/mcp.json in a project) and choose Connect in
Settings > MCP:
{ "mcpServers": { "databasezy": { "url": "https://mcp.databasezy.com/mcp" } }}VS Code (GitHub Copilot)
Section titled “VS Code (GitHub Copilot)”Run MCP: Add Server from the Command Palette, choose HTTP, and enter
https://mcp.databasezy.com/mcp. For the VS Code workspace format, use:
{ "servers": { "databasezy": { "type": "http", "url": "https://mcp.databasezy.com/mcp" } }}Start the server from its MCP configuration, complete the browser sign-in when requested, then select its tools
in agent chat. Newer Copilot versions also support a portable workspace-root .mcp.json with mcpServers
instead of servers; use the format selected by the guided setup. Do not put an org API key in the hosted
configuration. See the VS Code MCP setup and configuration formats.
Windsurf / Cascade
Section titled “Windsurf / Cascade”Open Cascade’s MCP configuration through its MCP controls (Open MCP config file) and add this entry to the file your installed version opens:
{ "mcpServers": { "databasezy": { "serverUrl": "https://mcp.databasezy.com/mcp" } }}Save, enable the server and complete OAuth when prompted. This is Cascade’s configuration; versions using a
different agent can have a separate configuration file. Use the client’s command to locate it rather than assuming
an old install path. The official Cascade MCP guide documents
remote serverUrl/url entries and OAuth support.
In Zed, open Zed’s own Settings → AI → MCP Servers (or run agent: open settings), choose Add Server,
then Add Remote Server, and enter https://mcp.databasezy.com/mcp. The equivalent entry in Zed’s settings is:
{ "context_servers": { "databasezy": { "url": "https://mcp.databasezy.com/mcp" } }}Leave Authorization unset so Zed offers the browser OAuth flow. Follow the sign-in, review the Databasezy
consent and enable the tools you want in your agent. See Zed’s remote MCP and OAuth configuration.
Other clients and redirect compatibility
Section titled “Other clients and redirect compatibility”Any client that implements the MCP authorization spec works: give it the server URL. A client identifies itself
with a client ID metadata document (its client_id is the https URL of a JSON document it publishes) or registers
with dynamic client registration (RFC 7591). Redirect URIs must be https://... or a loopback address
(http://127.0.0.1:<port>/..., http://[::1]:<port>/..., http://localhost:<port>/...); the only custom scheme
accepted is Cursor’s cursor://.
Client ID metadata documents (for client developers)
Section titled “Client ID metadata documents (for client developers)”The authorization server metadata says "client_id_metadata_document_supported": true. When /oauth/authorize
receives a client_id that starts with https://, Databasezy fetches that URL and uses the document as the
client’s registration:
The client_id URL | https://, a fully qualified host name (no IP address, no localhost or internal names), the default port, a path (not just /), no . or .. segments, no query, no fragment, no user name or password, at most 512 characters |
| Fetch | one GET with Accept: application/json, only to public addresses on port 443, redirects not followed, 5 seconds, HTTP 200 with Content-Type: application/json, at most 5 KiB |
| Required members | client_id equal to the URL, character for character; client_name (1-100 characters); redirect_uris (1-10, the rules above) |
| Refused | client_secret, client_secret_expires_at, a token_endpoint_auth_method other than none, grant_types other than authorization_code and refresh_token, response_types other than code |
| Ignored | every other member; logo_uri, jwks_uri and other URLs are never fetched, and client_uri is kept only on the client_id’s own host |
| Caching | per server, for the document’s Cache-Control: max-age, kept between 1 and 10 minutes (5 minutes without one); a document that fails a check is never cached |
| Limits | 10 document fetches a minute per IP address, 30 per client_id host, 300 in all (cached documents are not fetched again) |
The redirect_uri of each authorization request must be one of the document’s redirect_uris (a loopback URI may
change only its port). A refused document gets a plain error page that names the problem, never a redirect. Use the
same URL as client_id at the token and revocation endpoints. The consent page shows the host that published the
document and warns when the result goes to a loopback address, because any program on the computer can claim
a loopback client’s name.
What you choose on the consent page
Section titled “What you choose on the consent page”| Choice | Effect |
|---|---|
| Organization | The grant works in one organization only. Requests for any other organization are refused. |
| Project (optional) | The grant sees only that project: its instances, keys, sandboxes and apps. Organization-wide tools (usage, migrations, workspaces) are not offered. |
| Read-only | Only tools classified read-only by the grant catalogue remain; attempted write routes are refused (HTTP 403). mcp:read always enforces this. Sandbox file read/list are excluded because they mint sessions with POST; see below. |
| Destructive tools | Off by default. Explicitly allow the selected destructive tools and complete a recent second factor. Permission ends at most 15 minutes after that factor (earlier when organization policy uses a shorter window). |
| Tools | Untick tools you do not want the assistant to have. Only the ticked tools appear in the tool list. |
The current server has 52 tools, narrowed to your selection and scope.
sandbox_files_read and sandbox_files_list read file data, but each first creates a short sandbox session with
POST .../sandboxes/{id}/sessions. The grant catalogue therefore excludes them from read-only OAuth connections,
even though their MCP annotations describe reads. sandboxes_list still works. To use the file tools, reconnect
with write access and select them explicitly; each still mints only a files:read session, and selecting it does
not also select execution or file-writing tools.
The page also shows the application name and where your browser returns after you decide. A registered client’s
name is chosen by the client and is not verified; for a client with a metadata document the page shows the host that
published it. Check the return address before you approve, and approve a loopback (127.0.0.1, localhost)
return address only if you started the connection on this computer.
A grant never gives more than your own role: every call is checked against your current membership and
permissions in the organization, and stops working if you leave it. Credentials are never returned through MCP;
reveal them in the portal or with zb instances credentials reveal <id>.
Destructive consent
Section titled “Destructive consent”Deleting an instance, branch or workspace, resetting a branch, revoking a project key, rotating a project JWT key,
killing a sandbox, cancelling a job run, deleting a checkpoint and rolling back to a checkpoint require
confirm=true after you confirm that operation. Checkpoint rollback also requires confirm_name to match the
current instance name; its accepted response must be polled until completed_at is present. Hosted OAuth
connections also require short-lived destructive consent. This never reveals credentials or unlocks unrelated
administration tools, and ordinary read and write tools continue to use the original connection.
Checkpoint deletion and rollback use dedicated consent actions for those exact selected tools. This consent does not satisfy general backup restore or credential-reveal step-up. Checkpoint capability and physical-cleanup limits still apply; see the tool reference.
To renew consent, open Organization > Access & settings > MCP connections, find your own active connection and choose Authorize destructive tools. Review the organization or project and the exact tool list, then approve. If your second factor is stale, sign in again and review the confirmation once more. Approval lasts only for the remaining second-factor window; renewing or exchanging an assistant token cannot extend it. Your connection row shows the expiry time. When consent expires, the tool explains how to renew it; retry the operation only after confirming it again. Owners and admins cannot approve destructive consent for somebody else’s connection.
Existing connections need this explicit approval before their selected destructive tools work. A connection made without those tools must be reconnected to add them; renewal cannot add tools, broaden the project, or remove read-only mode. You can revoke the entire connection at any time.
Tokens and limits
Section titled “Tokens and limits”| Access token | 1 hour, usable only at https://mcp.databasezy.com/mcp (sending it to the REST API fails) |
| Refresh token | 30 days, replaced on every use; reusing an old one revokes the whole grant |
| Grant | 90 days, then you approve again |
| Authorization code | 60 seconds, single use; a second use revokes the grant |
| Requests per grant | 120 per minute (burst 60) on the MCP server; the API adds its own per-grant limit |
| Live grants | 25 per person per organization |
| Client registrations | 10 per IP address, then 1 per minute |
The MCP server never forwards your token to the API. It exchanges it for a separate five-minute token bound to the same grant (RFC 8693).
See and revoke connections
Section titled “See and revoke connections”In the portal, open Organization > Access & settings > MCP connections. You see the assistants you connected; owners and admins
(the apikeys:manage permission) see every member’s. Each row shows the application, where it signs in to, its
access (read-only or read and write, the whole organization or one project, the number of tools), when it was
connected and last used, and when it expires. Show expired and revoked connections adds the inactive ones.
Revoke asks for confirmation, then ends the connection at once: the API refuses the connection’s API tokens,
so every tool call that reaches the API fails, the token endpoint refuses its refresh token, and after the first
refused call the MCP server answers 401 to every further request. The MCP server keeps a verified access token
for up to one minute, so an assistant that makes no such call can still list the tool names for that minute; it
cannot use that revoked grant to read or change API data. To use the assistant again, connect it again. Every grant and revocation is recorded in the organization’s audit log
(mcp_grant.create, mcp_grant.revoke).
The same with the API (an org API key or a signed-in session; a token issued through MCP cannot manage grants):
# Your grants (members); everyone's with apikeys:manage. all=true adds expired and revoked ones.curl -H "Authorization: Bearer $ZB_API_KEY" https://api.databasezy.com/v1/orgs/$ORG/mcp-grants
# Revoke one now (idempotent): its access, refresh and API tokens stop working at oncecurl -X DELETE -H "Authorization: Bearer $ZB_API_KEY" https://api.databasezy.com/v1/orgs/$ORG/mcp-grants/mcpg_...A client that supports token revocation (RFC 7009) revokes the grant when it sends its refresh token to
/oauth/revoke, typically when you disconnect it.
Security events
Section titled “Security events”Refused tokens, writes attempted through read-only grants, tools outside a grant, requests for another organization
or project, reused codes or refresh tokens, and refused client registrations or metadata documents are recorded as
security events (mcp.token_refused, mcp.write_denied, mcp.tool_denied, mcp.scope_violation,
mcp.code_replayed, mcp.refresh_replayed, mcp.client_registration_refused). New clients, from a registration or
a new or changed metadata document, are mcp.client_registered; grants are mcp.grant_created and
mcp.grant_revoked. Destructive approval is recorded transactionally as the audit action
mcp_grant.destructive_consent and event mcp.destructive_consent_granted; expired or missing approval is
mcp.destructive_consent_required, and the API answers the tool call with 403 mfa_required and the renewal
steps before anything is changed. This feature has not been exercised live yet.