🌐 US-Proxy
class="antialiased">
Skip to main content
Connect AI assistants to Bytebase using the Model Context Protocol.
New to the Bytebase MCP server? Follow the Connect an AI Assistant to Bytebase with MCP tutorial for a hands-on walkthrough.

​
Prerequisites

  • Configure the external URL — the MCP server uses it to tell the AI assistant where to authenticate. A local address such as http://localhost:8080 works for a local deployment; use the public address your AI assistant can reach for anything else. Without it set, the Integration > MCP page cannot show a usable endpoint URL.
  • OAuth authentication is required on first connection. Ensure you have appropriate Bytebase permissions.

​
Configuration

The Integration > MCP page in your Bytebase console shows the endpoint two ways: a JSON snippet for manual client configuration, and a ready-to-run CLI command for supported tools.

​
JSON configuration

Add this to your MCP client’s configuration file:

​
CLI commands

The console page provides a one-line command for Claude Code, Codex, Copilot CLI, Gemini CLI, and VS Code — copy the one for your client.

​
Authentication

Bytebase authenticates MCP clients via OAuth. On first connection, your browser opens to the Bytebase login page; sign in and authorize the client to access your account. Bytebase OAuth authorization screen for an MCP client Once authorized, the client stores the token and reuses it automatically until it expires.

​
Usage

Once connected, try asking your AI assistant:
  • “List all projects in my Bytebase instance”
  • “Show me the schema for database X”
  • “Generate a migration script to add a users table”

​
Important notes

Caution: Once connected, your AI assistant will inherit all your permissions in Bytebase, including making changes to database or updating settings (in the case of an admin). So be cautious when instructing AI assistant to apply any change via Bytebase.
Audit logging: any action taken by the AI assistant via MCP will be audit-logged in Bytebase under your account.

​
How changes work

A few behaviors are worth knowing before you work through an AI assistant:
  • 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.
  • Masking is enforced. Query results honor your data masking policies — masked values appear as ****** (full) or **rn** (partial). The assistant only ever sees what your policies allow.

​
Limitations

  • No standalone dry-run. Plan checks (SQL review, DDL simulation) run as part of creating the plan; there is no way to validate SQL without creating a change.
  • 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 in detailed mode; narrow with a schema or table name. Column masking details are shown only when a specific table is requested.
  • HTTP transport only. The server is reached over the /mcp HTTP endpoint; stdio transport is not supported.