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 external URL if you haven’t already.
  • OAuth authentication is required on first connection. Ensure you have appropriate Bytebase permissions.

​
Setup

Navigate to Integration > MCP in your Bytebase console. Choose one of the following options:

​
Option 1: JSON Configuration

Add this JSON to your MCP client configuration file: 
{
  "mcpServers": {
    "bytebase": {
      "type": "http",
      "url": "{https://your-bytebase-url.com}/mcp"
    }
  }
}

​
Option 2: CLI Commands

Alternatively, use the CLI command shown on the MCP integration page for your preferred tool (Claude Code, Codex, Copilot CLI, Gemini CLI, or VS Code).

​
Authentication

To connect to Bytebase, you need to finish the authentication process via OAuth by logging into Bytebase and authorizing the AI to access your Bytebase account. mcp-auth Your tool will be connected to Bytebase once you click the Allow button.

​
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.