---
title: "mcp"
description: "Start MCP server (stdio transport)"
canonical: "https://pgbeam.com/docs/cli/mcp"
last-updated: "2026-09-14T19:37:21.000Z"
---

# mcp

> Start MCP server (stdio transport)

URL: https://pgbeam.com/docs/cli/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

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

## Examples

## 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:

## Remote transport (Streamable HTTP)

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.

Any MCP client that supports Streamable HTTP can connect directly:

## Example: raw JSON-RPC

## 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 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 `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`.