--- title: "mcp" description: "Start MCP server (stdio transport)" canonical: "https://pgbeam.com/docs/cli/mcp" last-updated: "2026-10-29T19:01:20.000Z" --- # mcp > Start MCP server (stdio transport) URL: https://pgbeam.com/docs/cli/mcp {/* Auto-generated from CLI commands. Do not edit. Run `pnpm generate:cli-docs` to regenerate. */} 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 ```bash pgbeam mcp ``` > **Global options** > > All [global options](/docs/cli/global-options) (`--token`, `--profile`, > `--project`, `--org`, `--json`, `--no-color`, `--no-trunc`, `--debug`) are > also available on this command. ## Examples ```bash # Start the MCP server pgbeam mcp # Register it in .mcp.json (Claude Code, Cursor, VS Code) { "mcpServers": { "pgbeam": { "command": "pgbeam", "args": ["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. {/* @preserve */} ## 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 Code** ```json title=".claude/mcp.json" { "mcpServers": { "pgbeam": { "command": "pgbeam", "args": ["mcp"], "env": { "PGBEAM_API_KEY": "pbu_..." } } } } ``` **Cursor** ```json title=".cursor/mcp.json" { "mcpServers": { "pgbeam": { "command": "pgbeam", "args": ["mcp"], "env": { "PGBEAM_API_KEY": "pbu_..." } } } } ``` **Generic MCP** ```json { "mcpServers": { "pgbeam": { "command": "pgbeam", "args": ["mcp"], "env": { "PGBEAM_API_KEY": "pbu_..." } } } } ``` ### Remote transport (Streamable HTTP) ``` POST https://api.pgbeam.com/v1/mcp Authorization: Bearer Content-Type: application/json Accept: application/json, text/event-stream ``` The remote endpoint follows the [MCP Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) in stateless mode, and the protocol version is negotiated at `initialize`. Use it when the CLI isn't available or you need server-to-server integration. **Claude Code** ```json title=".claude/mcp.json" { "mcpServers": { "pgbeam": { "type": "url", "url": "https://api.pgbeam.com/v1/mcp", "headers": { "Authorization": "Bearer pbu_..." } } } } ``` **Cursor** ```json title=".cursor/mcp.json" { "mcpServers": { "pgbeam": { "url": "https://api.pgbeam.com/v1/mcp", "headers": { "Authorization": "Bearer pbu_..." } } } } ``` **Generic MCP** Any MCP client that supports Streamable HTTP can connect directly: ```json { "mcpServers": { "pgbeam": { "transport": "streamable-http", "url": "https://api.pgbeam.com/v1/mcp", "headers": { "Authorization": "Bearer pbu_..." } } } } ``` ### Example: raw JSON-RPC ```bash # Initialize curl -X POST https://api.pgbeam.com/v1/mcp \ -H "Authorization: Bearer pbu_..." \ -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 pbu_..." \ -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 pbu_..." \ -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 pbu_..." \ -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](/docs/api). The typical flow is `search_endpoints` → `describe_endpoint` → `call_endpoint`. The remote transport (`api.pgbeam.com/v1/mcp`) also exposes three read-only agent-skills tools, so an agent new to PgBeam can find and install a skill in the same session: | Tool | Purpose | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_skills` | List the installable PgBeam agent skills: name and description only. | | `get_skill` | Return one skill's full `SKILL.md` body. Takes `name`. | | `install_skill` | Return a skill's content plus its conventional target path (e.g. `.claude/skills//SKILL.md`) and a digest to verify it. This server cannot write to your filesystem, so it hands back content and path for the agent to write itself. Takes `name`. | Start with `pgbeam-connect` to see how an agent wires itself to Postgres safely. The CLI's stdio transport (`pgbeam mcp`) does not expose these three; it carries only the meta-tools above. > **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](/docs/mcp) instead, a separate endpoint with `briefing`, > `query`, `validate_sql`, `list_tables`, `describe_table`, `explain`, > `schema_catalog`, and `my_permissions` tools held to your policies, plus > `search_docs` and `read_doc`.