MCP Server
Remote MCP endpoint for AI agent integration.
POST /v1/mcp is a remote
Model Context Protocol server using the
Streamable HTTP transport. It lets AI assistants manage PgBeam resources
(projects, databases, policies, agent credentials) through three meta-tools
rather than one tool per endpoint.
See the MCP command docs for full setup instructions covering both the CLI (stdio) and remote (HTTP) transports.
Two different MCP servers
This is the management MCP — it administers your account. To give an agent
query access to a database, use the hosted agent-database
MCP, a separate endpoint with query, list_tables,
describe_table, and explain tools enforced by your policies.
Quick start
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": "my-agent", "version": "1.0" }
}
}'Protocol
| Property | Value |
|---|---|
| Transport | Streamable HTTP (MCP spec 2025-03-26) |
| Wire format | JSON-RPC 2.0 |
| Auth | Authorization: Bearer <token> |
| Methods | initialize, notifications/initialized, tools/list, tools/call, ping |
Authentication
The MCP endpoint uses the same authentication as the REST API. Pass a bearer
token or API key in the Authorization header. See
Authentication.
Tools
tools/list returns three meta-tools that wrap the whole API. This keeps the
agent's context small — it discovers operations on demand instead of loading a
schema for every endpoint up front.
| Tool | Purpose |
|---|---|
search_endpoints | Find operations by intent (query, limit). Returns operation_id, method, path, tag. |
describe_endpoint | Full schema for one operation (operation_id): parameters and request body. |
call_endpoint | Invoke an operation: operation_id, plus path_params, query_params, and body as needed. |
The operation ids and shapes mirror the OpenAPI spec. A typical
flow is search_endpoints → describe_endpoint → call_endpoint.