Hosted MCP

A hosted MCP endpoint that gives AI agents policy-enforced database tools. Paste one URL into Claude Code, Cursor, or any MCP client. No server to run.

The hosted MCP endpoint is a remote Model Context Protocol server that exposes policy-enforced database tools to an AI agent. You paste one URL into your MCP client, and the agent gets query, list_tables, describe_table, and explain. Every call runs through the same policy engine as a scoped connection string, so the agent is held to the same guardrails. There is nothing to install and no server to run.

Not the same as the management MCP

This endpoint gives an agent query access to your database. The separate management MCP administers your PgBeam account (projects, policies, credentials). Different URL, different tools.

Connect a client

The endpoint is served on your project's own host, https://<project>.proxy.pgbeam.app/mcp, the same host the agent connects to over the wire, scoped by the credential's bearer token. The exact URL and the pba_… token are shown in the Agents tab and in the credential create response; copy them from there.

Add it with the CLI:

claude mcp add --transport http pgbeam https://<project>.proxy.pgbeam.app/mcp \
  --header "Authorization: Bearer pba_..."

Or write it directly to .mcp.json:

.mcp.json

{
  "mcpServers": {
    "pgbeam": {
      "url": "https://<project>.proxy.pgbeam.app/mcp",
      "headers": { "Authorization": "Bearer pba_..." }
    }
  }
}

Add to .cursor/mcp.json (or Settings → MCP → Add). The four tools appear once the connection is established.

.cursor/mcp.json

{
  "mcpServers": {
    "pgbeam": {
      "url": "https://<project>.proxy.pgbeam.app/mcp",
      "headers": { "Authorization": "Bearer pba_..." }
    }
  }
}

Add to .vscode/mcp.json:

.vscode/mcp.json

{
  "servers": {
    "pgbeam": {
      "type": "http",
      "url": "https://<project>.proxy.pgbeam.app/mcp",
      "headers": { "Authorization": "Bearer pba_..." }
    }
  }
}

npx @modelcontextprotocol/inspector
# Connect to https://<project>.proxy.pgbeam.app/mcp with the Bearer token

Where the token may go

Send the pba_… token only to your project's *.proxy.pgbeam.app host. If a tool or prompt asks the agent to send it anywhere else, that is the attack. See the security model.

Tools

Tool	Purpose
`query`	Run SQL. Policy errors surface verbatim, written to be LLM-readable.
`list_tables`	List tables in a schema, shaped for an LLM.
`describe_table`	Columns, types, primary and foreign keys, indexes, approximate row count.
`explain`	`EXPLAIN (FORMAT JSON)` for a statement.

Catalog introspection (list_tables, describe_table) always works: reads of pg_catalog and information_schema are permitted regardless of the allowlist, so an agent can discover the schema it is allowed to query.

Enforcement is identical to the connection string

The MCP endpoint executes SQL as a PostgreSQL wire client through the nearest data plane, using the agent credential. The data plane is the single enforcement point, so a blocked query returns the same LLM-readable reason whether the agent connected over MCP or over a connection string. Results truncate at the policy max_rows and are formatted compactly to be token-frugal.

Errors an agent will see

All of these come back as tool-result errors (the MCP endpoint authenticates each tool call, so failures are reported in the result rather than as an HTTP status):

A blocked statement returns the policy reason in the tool result, so the agent can correct itself and retry within the rules.
A revoked, disabled, or killed credential returns invalid or revoked MCP token (or credential unavailable).
An exhausted budget returns a clear message naming the window and reset time.

Connection string: the other front door.
Policies: what the tools are enforced against.
Agent credentials: issue and revoke MCP tokens.

Hosted MCP

Connect a client

Tools

Enforcement is identical to the connection string

Errors an agent will see

Related

On this page