Model Context Protocol (MCP)

​

Prerequisites

• Configure the external URL. Bytebase uses it to tell the AI assistant where to sign in, and binds each MCP token to it. Without it, sign-in fails. A local address such as http://localhost:8080 works for a client on the same machine, such as Claude Code. Otherwise, use a public address your AI assistant can reach.
• The workspace access policy must not be Disabled. A new workspace starts at Read-only.

​

Connect a client

• Claude Code, Codex, Copilot CLI, Gemini CLI, and VS Code each get a one-line command.
• Claude Desktop gets the endpoint URL. Add it as a custom connector under Customize > Connectors on claude.ai.
• JSON gets a configuration snippet for other clients:

{
  "mcpServers": {
    "bytebase": {
      "type": "http",
      "url": "<external_url>/mcp"
    }
  }
}

​

Sign in

​

Try it

• “List all projects in my Bytebase instance”
• “Show me the schema of the <database> database”

​

Access policy

​

Set the access policy

1. Go to Integration > MCP.
2. Under Access policy, click Edit policy.
3. Select a mode and click Save policy.

curl --request PATCH "<bytebase_url>/v1/settings/MCP?allow_missing=true&update_mask=value.mcp.capability" \
  --header 'Authorization: Bearer <access_token>' \
  --data '{"value":{"mcp":{"capability":"READ_ONLY"}}}'

​

Read-only queries

​

Read-write changes

• Propose a change. The change tool (propose_database_change) creates a sheet, a plan with plan checks, and an issue. The issue follows the project’s review and rollout flow.
• Run a statement directly. The query tool (query_database) runs INSERT, UPDATE, DELETE, CREATE, ALTER, and DROP without an issue, within your permissions. This works on MySQL, PostgreSQL, Oracle, SQL Server, TiDB, Snowflake, Spanner, BigQuery, MongoDB, and Elasticsearch.

​

What no mode allows

• Change workspace settings, including the MCP access policy itself.
• Approve or reject an issue.
• Mint, reset, or rewrite credentials, its own or anyone else’s.
• Read or change users and groups, roles and IAM policies, identity providers and service accounts, workspace policies, billing, or the audit log.
• Create, change, or delete projects and instances, or manage project webhooks. Reading project and instance details is allowed.
• Open an Admin mode session in SQL Editor.
• Read other people’s query history.
• Send data to a third party through a stored workspace credential, such as Bytebase’s built-in AI chat, which uses the workspace AI API key, or a webhook test.
• Request access or a role through an issue. Only database change issues can be created over MCP.

​

Masking

curl --request PATCH "<bytebase_url>/v1/settings/MCP?allow_missing=true&update_mask=value.mcp.ignore_masking_exemptions" \
  --header 'Authorization: Bearer <access_token>' \
  --data '{"value":{"mcp":{"ignoreMaskingExemptions":true}}}'

​

Audit

​

How changes work

• One database per change. A proposed change targets a single database. For changes across multiple databases, the assistant uses the batch workflow and the underlying APIs.
• Each change creates a new issue. A proposed change always creates a fresh sheet, plan, and issue — it does not edit an existing one. Iterating on SQL across several turns produces multiple issues, so settle on the statement before proposing, and close any superseded issues.

​

Limitations

• No dry-run tool. The change tool always creates a change. Plan checks (SQL review, DDL simulation) run when it creates the plan.
• Query results are capped. Queries return 100 rows by default and 1,000 at most, with a 30-second timeout. Larger result sets are truncated.
• Schema output is capped. Schema inspection returns up to 200 tables per schema when it includes columns or details; the default summary lists every table. Narrow it with a schema or table name.
• HTTP transport only. The server is reached over the /mcp HTTP endpoint; stdio transport is not supported.
• Request size is capped. Bytebase refuses requests over 4 MiB with HTTP 413. Send very large migration statements through the console instead.