Skip to main content
Use an AI assistant (Claude Code, Cursor, etc.) to query data, inspect schemas, and propose database changes through Bytebase’s built-in MCP (Model Context Protocol) server. Your Bytebase permissions and the workspace MCP access policy limit what it can do. In this tutorial, you ask Bytebase questions in plain language, and the assistant picks the right MCP tool for each request.

​
Step 1 - Setup Bytebase

  1. Ensure Docker is running, then start the Bytebase container:
    dk-bb-running
  2. Open Bytebase in localhost:8080, fill in the fields and click Create admin account. You’ll be redirected to Workspace. account
  3. During workspace setup, choose the built-in sample data. setup-built-in-sample-data

​
Step 2 - Configure the external URL

The MCP server uses your external URL to tell the AI assistant where to sign in. For the local Docker setup, point it at localhost.
  1. Navigate to Settings > General > External URL.
  2. Set it to http://localhost:8080 and save.
On a real deployment, set the external URL to the public address your AI assistant can reach. See Configure external URL.

​
Step 3 - Connect your AI assistant

The MCP endpoint is your external URL followed by /mcp — here http://localhost:8080/mcp. We use Claude Code as the example client.
  1. Add the server:
  2. Verify it’s registered:
    You should see bytebase listed with ! Needs authentication. The next step signs you in.
For other clients (Codex, Copilot CLI, Gemini CLI, VS Code) or JSON configuration, see the MCP integration page.

​
Step 4 - Authenticate

  1. Start Claude Code:
  2. Run /mcp, select bytebase, and choose Authenticate. Your browser opens Bytebase.
  3. Sign in with the admin account you created. The authorization page then shows the workspace access policy and what this session may do. Click Allow.
  4. Claude Code stores the token and refreshes it automatically.
Once connected, the assistant acts as you. It can do what both your Bytebase permissions and the workspace access policy allow. On a new workspace the policy is Read-only, so for now it can read but not change anything. Be careful when you ask it to apply changes.

​
Step 5 - Inspect a schema

From here you interact with Bytebase in plain language. The quoted lines are example prompts; your wording can differ — just refer to databases by name.
  1. Ask the assistant to look at a schema:
    “Using Bytebase, show me the schema of the hr_test database.”
  2. Drill into a table:
    “Show me the full definition of the employee table in hr_test.”

​
Step 6 - Query data

  1. Ask a question that reads data:
    “How many rows are in the employee table in hr_test?”
  2. Try something more specific:
    “List the 10 most recently hired employees in hr_test.”
Query results honor Bytebase’s data masking policies. Masking needs the Enterprise plan, so on the Community plan used here, no values are masked.
If you only need the assistant to read and query, you can stop here. The next steps let it change the database.

​
Step 7 - Switch the access policy to Read-write

A new workspace starts with the MCP access policy at Read-only, which refuses changes.
Under Read-write, the assistant can do more than propose changes for review. It can also run DDL and DML statements directly on PostgreSQL and several other engines, within your permissions, without opening an issue. On the Community plan, where no approval applies, it can also deploy a proposed change itself.
To allow changes, switch the policy to Read-write:
  1. In Bytebase, go to Integration > MCP.
  2. Under Access policy, click Edit policy.
  3. Select Read-write and click Save policy.
The new mode applies to the assistant’s next request. You do not need to reconnect: the session you already connected gains write access.

​
Step 8 - Propose a schema change

When you ask the assistant to propose a change, it opens a change issue with automatic checks instead of running the SQL. The issue follows your normal review and deploy flow.
  1. Ask for a change:
    “In Bytebase, propose a change that adds a nullable nickname VARCHAR(50) column to the employee table in hr_test. Title it ‘Add nickname to employee’.”
    The assistant returns a link to the change issue. It may say the issue is waiting for approval. On the Community plan, Bytebase skips approval a moment later.
  2. Open the link and review the proposed SQL and the check results.
  3. In the Deploy section, click Run (the button names the stage, for example Run · Test). Wait for Deployed.
On the Enterprise plan, you can add a multi-step approval flow, for example routing higher-risk changes to additional approvers, before a change deploys. Deployment is configurable per environment: manual by default, or automatic.

​
Step 9 - Switch back to Read-only

When you finish, set the access policy back to Read-only, unless you still want the assistant to make changes:
  1. Go to Integration > MCP.
  2. Under Access policy, click Edit policy.
  3. Select Read-only and click Save policy.

​
Next Steps