Advanced template on pgmi

API keys

Mon, 01 Jan 0001 00:00:00 +0000

Advanced Template: API Key Authentication#

Scope: advanced template only. This subsystem is scaffolded by pgmi init --template advanced (membership/08-api-keys.sql). It is not part of pgmi core and is not included in the basic template.

These API keys authenticate callers of the APIs generated by the advanced template. They are unrelated to PostgreSQL connection credentials or to any authentication used by the pgmi CLI itself.

Machine-to-machine authentication for agents, MCP clients, and CI pipelines calling your deployed application’s REST/RPC/MCP endpoints.

MCP gateway overview

Mon, 01 Jan 0001 00:00:00 +0000

Advanced Template: MCP Gateway#

Scope: advanced template only. This subsystem is scaffolded by pgmi init --template advanced. It is not part of pgmi core and is not included in the basic template. The generated SQL and gateway become application code that you own.

pgmi has two unrelated MCP surfaces — be sure you’re reading about the right one:

pgmi serve (part of the CLI, every install): exposes pgmi’s project-inspection commands as an MCP server over stdio, so a coding agent can drive pgmi itself. See the CLI reference .
The advanced-template MCP gateway (this section): exposes your deployed PostgreSQL application — its tools, resources, and prompts — to AI assistants over HTTP.

The Model Context Protocol (MCP) is an open standard that allows AI applications (Claude Desktop, VS Code Copilot, etc.) to connect to external systems. The advanced template implements MCP entirely in PostgreSQL, with a thin HTTP gateway for transport.

Run the MCP gateway

Mon, 01 Jan 0001 00:00:00 +0000

Run the MCP Gateway#

Scope: advanced template only. The gateway (tools/mcp-gateway.py) is generated by pgmi init --template advanced and becomes application code you own. New to this subsystem? Start with the overview .

Quick Start#

1. Deploy the Advanced Template#

pgmi init --template advanced myproject
cd myproject
pgmi deploy --connection "postgresql://user:pass@localhost:5432/mydb"

2. Start the HTTP Gateway#

The pgmi init --template advanced command generates a tools/ directory with the Python gateway:

cd tools
pip install -r requirements.txt
export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
python mcp-gateway.py

Requirements:

Author MCP handlers

Mon, 01 Jan 0001 00:00:00 +0000

Author MCP Tools, Resources, and Prompts#

Scope: advanced template only. Handlers are SQL functions in your project, registered with api.create_or_replace_mcp_handler. New to this subsystem? Start with the overview .

MCP Types#

Type	Purpose	Key Metadata
Tool	Executable actions	`name`, `description`, `inputSchema`
Resource	Data access via URI	`name`, `uriTemplate`, `mimeType`
Prompt	Message templates	`name`, `description`, `arguments`

Request and Response Types#

-- Request type (passed to your handler)
CREATE TYPE api.mcp_request AS (
 arguments jsonb, -- Tool/prompt arguments
 uri text, -- Resource URI
 context jsonb, -- Auth: {"user_id": "...", "tenant_id": "..."}
 request_id jsonb -- JSON-RPC id (string, integer, or null); must echo in response
);

-- Response type (JSON-RPC 2.0 envelope)
CREATE TYPE api.mcp_response AS (
 envelope jsonb -- {jsonrpc, id, result} or {jsonrpc, id, error}
);

request_id is jsonb across the MCP API so JSON-RPC 2.0 id types (string, integer, null) round-trip verbatim. Passing a raw text literal ('req-1') fails domain parsing — use '"req-1"'::jsonb or '42'::jsonb.

MCP SQL API reference

Mon, 01 Jan 0001 00:00:00 +0000

MCP SQL API Reference#

Scope: advanced template only. These functions are scaffolded into the api schema of your project. New to this subsystem? Start with the overview .

Core Functions#

Function	Purpose
`api.mcp_handle_request(request, context)`	Unified dispatcher — returns `NULL` envelope for JSON-RPC notifications (no response sent)
`api.mcp_initialize(params, request_id jsonb)`	Handshake handler
`api.mcp_ping(request_id jsonb)`	Keepalive response
`api.mcp_call_tool(name, args, context, id jsonb)`	Invoke a tool; handler exceptions → `result.isError=true` (not JSON-RPC error)
`api.mcp_read_resource(uri, context, id jsonb)`	Read a resource
`api.mcp_get_prompt(name, args, context, id jsonb)`	Expand a prompt
`api.mcp_list_tools(p_tags text[] DEFAULT NULL)`	Tool discovery; hides `requires_auth` tools when `auth.user_id` is unset; surfaces tags as `_meta.tags`; `p_tags` filter matches by overlap (NULL or empty array = no filter)
`api.mcp_list_resources()`	Concrete-resource discovery (`resources/list`); emits `uri` objects only; same auth-hide semantics
`api.mcp_list_resource_templates()`	Template discovery (`resources/templates/list`); emits `uriTemplate` objects (RFC 6570); same auth-hide semantics
`api.mcp_list_prompts()`	Prompt discovery; same auth-hide semantics
`api.mcp_request_policy(request, requested_isolation)`	Resolve a request’s transaction policy before opening the dispatch transaction — see transaction policy

MCP protocol compliance & limitations

Mon, 01 Jan 0001 00:00:00 +0000

MCP Protocol Compliance and Limitations#

Scope: advanced template only. This page specifies how the scaffolded MCP implementation behaves at the protocol level. New to this subsystem? Start with the overview .

Protocol Versions#

pgmi implements MCP using JSON-RPC 2.0:

Supported protocol versions: 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25 (an unknown-newer proposal negotiates down to the server’s best supported version)
Transport: HTTP POST to /mcp endpoint
Authentication: Context parameter (not HTTP headers)

Transport Behavior#

The gateway implements the Streamable HTTP transport’s request/response path:

Semantic MCP curation

Mon, 01 Jan 0001 00:00:00 +0000

Recipe: Semantic Agent-Tool Curation#

Scope: optional extension to the advanced-template MCP gateway. Prerequisites: a project scaffolded from the advanced template, its handler registry, a vector extension/provider decision, and enough MCP tools that curation is worth the machinery.

Use this only at tool-overload scale. When an agent has dozens of tools, exposing all of them at once dilutes the model’s attention and inflates token cost. This recipe surfaces the relevant subset for a given query. If your project has a handful of tools, skip it — expose handlers directly through the existing MCP/RPC routing and let the client list them all.

Transaction policy

Mon, 01 Jan 0001 00:00:00 +0000

Per-route transaction policy#

A handler declares what it needs — a minimum transaction isolation floor and whether the route is read-only — and the system resolves, opens, enforces, and publishes the resulting policy. No external configuration, no runtime surprises.

What a route declares#

Two metadata keys on any REST, RPC, or MCP handler:

Key	Values	Default
`minTransactionIsolation`	`read committed`, `repeatable read`, `serializable`	none (behaves as `read committed`)
`readOnly`	`true` / `false`	`false` (read-write)

Case- and separator-insensitive: READ COMMITTED, read-committed, and Read_Committed all normalize to read committed. read uncommitted folds onto read committed, matching PostgreSQL’s behavior — it implements no dirty-read level.