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. Rather than one tool per endpoint, the server exposes three meta-tools — search_endpoints, describe_endpoint, and call_endpoint — so the agent discovers and invokes the API it needs without loading dozens of tool schemas up front.

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 (returns the three meta-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"}'

# 1. Find the operation you need
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": "search_endpoints",
      "arguments": { "query": "projects" }
    }
  }'

# 2. Invoke it by operation id
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": 4,
    "method": "tools/call",
    "params": {
      "name": "call_endpoint",
      "arguments": {
        "operation_id": "listProjects",
        "query_params": { "org_id": "org_abc123" }
      }
    }
  }'

Available tools

The management API has dozens of endpoints. Exposing each as its own MCP tool floods the agent's context with schemas it will never use, so the server instead exposes three meta-tools and lets the agent discover what it needs:

Tool	Purpose
`search_endpoints`	Find operations by intent. Returns a compact list (`operation_id`, `method`, `path`, `tag`). Optional `query` and `limit`.
`describe_endpoint`	Return one operation's full schema: parameters and request body. Takes `operation_id`.
`call_endpoint`	Invoke an operation. Takes `operation_id`, plus `path_params`, `query_params`, and `body` as needed.

The operation ids and shapes come from the OpenAPI spec. The typical flow is search_endpoints → describe_endpoint → call_endpoint. Both transports expose the same three meta-tools.

This is the management MCP

This server manages your PgBeam account (projects, databases, policies, credentials). To give an agent query access to a database, use the hosted agent-database MCP instead — a separate endpoint with query, list_tables, describe_table, and explain tools, held to your policies.

On this page