mcp

Start a Model Context Protocol (MCP) server using stdio transport. This allows AI coding assistants like Claude Code, Cursor, and other MCP-compatible clients to manage PgBeam projects, databases, and cache rules directly. The server exposes PgBeam API operations as MCP tools.

Usage

pgbeam mcp

Global options

All global options (--token, --profile, --project, --org, --json, --no-color, --debug) are also available on this command.

Examples

# Start the MCP server
pgbeam mcp

# Use with Claude Code (add to MCP config)
pgbeam mcp

Output

Starts the MCP server and listens for JSON-RPC messages on stdin/stdout. The server runs until the process is terminated. No human-readable output is produced — all communication is via the MCP protocol.

Configuration

Two transports are available:

Transport	When to use
CLI (stdio)	Local dev — the AI tool spawns `pgbeam mcp` as a subprocess
Remote (Streamable HTTP)	Server-to-server, hosted agents, or when the CLI isn't installed

CLI transport (stdio)

Add the MCP server to your AI tool's configuration:

.claude/mcp.json

{
  "mcpServers": {
    "pgbeam": {
      "command": "pgbeam",
      "args": ["mcp"],
      "env": {
        "PGBEAM_TOKEN": "pbk_..."
      }
    }
  }
}

.cursor/mcp.json

{
  "mcpServers": {
    "pgbeam": {
      "command": "pgbeam",
      "args": ["mcp"],
      "env": {
        "PGBEAM_TOKEN": "pbk_..."
      }
    }
  }
}

{
  "mcpServers": {
    "pgbeam": {
      "command": "pgbeam",
      "args": ["mcp"],
      "env": {
        "PGBEAM_TOKEN": "pbk_..."
      }
    }
  }
}

Remote transport (Streamable HTTP)

POST https://api.pgbeam.com/v1/mcp
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json, text/event-stream

The remote endpoint follows the MCP Streamable HTTP transport (spec version 2025-03-26). Use it when the CLI isn't available or you need server-to-server integration.

.claude/mcp.json

{
  "mcpServers": {
    "pgbeam": {
      "type": "url",
      "url": "https://api.pgbeam.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer pbk_..."
      }
    }
  }
}

.cursor/mcp.json

{
  "mcpServers": {
    "pgbeam": {
      "url": "https://api.pgbeam.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer pbk_..."
      }
    }
  }
}

Any MCP client that supports Streamable HTTP can connect directly:

{
  "mcpServers": {
    "pgbeam": {
      "transport": "streamable-http",
      "url": "https://api.pgbeam.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer pbk_..."
      }
    }
  }
}

Example: raw JSON-RPC

# Initialize
curl -X POST https://api.pgbeam.com/v1/mcp \
  -H "Authorization: Bearer pbk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "1.0" }
    }
  }'

# List tools
curl -X POST https://api.pgbeam.com/v1/mcp \
  -H "Authorization: Bearer pbk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# Call a tool
curl -X POST https://api.pgbeam.com/v1/mcp \
  -H "Authorization: Bearer pbk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "listProjects",
      "arguments": { "org_id": "org_abc123" }
    }
  }'

Available tools

Tools are auto-generated from the OpenAPI spec. Every public endpoint becomes an MCP tool named after its operationId. Path and query parameters become tool arguments; mutating methods (POST, PATCH, PUT) accept a body object.

Both transports expose the same set of tools.

On this page