MCP Servers

MCP (Model Context Protocol) servers extend your AI coding agent with live access to external tools, databases, and APIs. Instead of copy-pasting context into your conversation, the agent can query live systems directly. The difference between a basic setup and a power-user setup is often the MCP servers.

Adding servers

The primary way to add MCP servers is through the agent mcp add CLI command. There are three transport types depending on where the server runs.

Remote HTTP server (recommended)

# Basic syntax
agent mcp add --transport http <name> <url>

# Example: Connect to GitHub
agent mcp add --transport http github https://api.githubcopilot.com/mcp/

# With an authentication header
agent mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Remote SSE server (deprecated)

SSE (Server-Sent Events) transport is deprecated in favor of HTTP. Use it only when a server does not support HTTP.

agent mcp add --transport sse asana https://mcp.asana.com/sse

Local stdio server

Stdio servers run as local processes on your machine. They are ideal for tools that need direct system access.

# Basic syntax
agent mcp add [options] <name> -- <command> [args...]

# Example: PostgreSQL via @bytebase/dbhub
agent mcp add --transport stdio db \
  -- npx -y @bytebase/dbhub --dsn "postgresql://user:pass@localhost:5432/dev"

# With environment variables
agent mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

Option ordering matters. All flags (--transport, --env, --scope, --header) must come before the server name. The -- separates the server name from the command that launches the MCP server process.

Adding from JSON

You can also add a server from a raw JSON configuration:

agent mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp"}'

agent mcp add-json local-tool '{"type":"stdio","command":"npx","args":["-y","some-package"]}'

Configuration files

MCP server configurations are stored in two files depending on scope. These are not the same as .agent/settings.json or .agent/settings.local.json, which are for your agent’s settings.

The .mcp.json format:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "postgresql://..."],
      "env": {}
    }
  }
}

Environment variables are supported in .mcp.json using ${VAR} or ${VAR:-default} syntax, so teams can share configs without hardcoding secrets.

Scopes

Use the --scope flag to control where a server configuration is stored:

# Add a server only you can see in this project (default)
agent mcp add --transport http stripe https://mcp.stripe.com

# Share with the team via .mcp.json
agent mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# Available in all your projects
agent mcp add --transport http hubspot --scope user https://mcp.hubspot.com

When the same server name exists at multiple scopes, precedence is: local > project > user.

Practical examples

Query a PostgreSQL database

agent mcp add --transport stdio db \
  -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:pass@localhost:5432/analytics"

Then ask the agent:

Show me the schema for the orders table.
Find customers who haven't made a purchase in 90 days.

Use read-only database connections by default. Only allow writes when explicitly needed.

Connect to GitHub

agent mcp add --transport http github https://api.githubcopilot.com/mcp/

Authenticate via /mcp inside the agent, then:

Review PR #456 and suggest improvements.
Show me all open PRs assigned to me.

Monitor errors with Sentry

agent mcp add --transport http sentry https://mcp.sentry.dev/mcp

Authenticate via /mcp, then:

What are the most common errors in the last 24 hours?
Which deployment introduced these new errors?

Management commands

# List all configured servers
agent mcp list

# Get details for a specific server
agent mcp get github

# Remove a server
agent mcp remove github

# Check server status inside the agent
/mcp

OAuth authentication

Many remote MCP servers require OAuth 2.0 authentication. The workflow is straightforward:

1. Add the server: agent mcp add --transport http sentry https://mcp.sentry.dev/mcp
2. Run /mcp inside the agent
3. Follow the browser login flow

Authentication tokens are stored securely and refreshed automatically. Use “Clear authentication” in the /mcp menu to revoke access.

For servers that require pre-configured OAuth credentials (no dynamic client registration), use --client-id and --client-secret:

agent mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Troubleshooting

• Server not starting: Check the command works directly (e.g., npx -y @bytebase/dbhub --help). MCP servers must run as long-lived processes.
• Connection closed on Windows: Wrap npx commands with cmd /c on native Windows: agent mcp add --transport stdio my-server -- cmd /c npx -y @some/package
• Timeout errors: Configure startup timeout with the MCP_TIMEOUT environment variable (e.g., MCP_TIMEOUT=10000 agent for 10 seconds).
• Output too large: Increase the token limit with MAX_MCP_OUTPUT_TOKENS=50000 agent (default is 25,000 tokens, warning at 10,000).
• Authentication errors: Run /mcp inside the agent to re-authenticate. Check that env vars are set correctly for stdio servers.
• Project server prompts: Your agent prompts for approval before using project-scoped servers from .mcp.json. Use agent mcp reset-project-choices to reset approvals.

Quick reference