---
title: "MCP Server"
description: "Remote MCP endpoint for AI agent integration."
canonical: "https://pgbeam.com/docs/api/mcp"
last-updated: "2026-10-30T13:45:52.000Z"
---

# MCP Server

> Remote MCP endpoint for AI agent integration.

URL: https://pgbeam.com/docs/api/mcp

`POST /v1/mcp` is a remote [Model Context Protocol](https://modelcontextprotocol.io) 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, plus three read-only tools that serve PgBeam's agent skills.

See the [MCP command docs](/docs/cli/mcp) 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](/docs/mcp), a separate endpoint with `briefing`, `query`, `validate_sql`,
> `list_tables`, `describe_table`, `explain`, `schema_catalog`, and
> `my_permissions` tools enforced by your policies, plus `search_docs` and
> `read_doc`.

## Quick start

```bash
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": "my-agent", "version": "1.0" }
    }
  }'
```

## Protocol

| Property         | Value                                                                         |
| ---------------- | ----------------------------------------------------------------------------- |
| Transport        | Streamable HTTP, stateless (no session id)                                    |
| Protocol version | Negotiated at `initialize`                                                    |
| 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](/docs/api#authentication).

## Tools

`tools/list` returns six tools. Three meta-tools 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 operations and their shapes mirror the [OpenAPI spec](/docs/api), with ids spelled the way `search_endpoints` returns them: `ListProjects` for the spec's `listProjects`. A typical flow is `search_endpoints` → `describe_endpoint` → `call_endpoint`. Operations are not tools themselves: to list projects, call `call_endpoint` with `operation_id: "ListProjects"` and `query_params: { "org_id": "..." }`.

The other three tools are read-only and serve the installable agent skills: `list_skills` lists them, `get_skill` returns one skill's instructions by `name`, and `install_skill` returns its content plus the path to write it to.