MCP Integration

Postgram exposes machine-agent tooling through MCP over Streamable HTTP.

What this page covers

MCP setup, remote OAuth connectors, tool surface, and output behavior for agent workflows.

Local and static-key clients

For a local client, use the Streamable HTTP endpoint:

http://127.0.0.1:3100/mcp

Authenticate suitable local or otherwise static clients with a bearer API key:

Authorization: Bearer <postgram-api-key>

The compatibility ?apiKey= form remains available for clients that require it, but bearer headers are the normal static-client configuration.

Use exposed tools for entity and task operations. Core tool names:

• store, recall, search, update, delete
• task_create, task_list, task_update, task_complete
• sync_push, sync_status
• link, unlink, expand

Use compacting for long-running or large responses:

{
  "full_response": true
}

for full REST payloads, and

{
  "toon": true
}

on list-like tools for compact text output.

Compact search results may include edge affordances:

{
  "edges": {
    "count": 3,
    "relations": [{ "relation": "mentioned_in", "count": 2 }]
  }
}

Treat these fields as a prompt-routing hint. Use expand_graph: true or the expand tool when the user needs causes, provenance, dependencies, blockers, ownership, involvement, related discussion context, or disambiguation.

Native remote connectors

Native remote connectors require OAuth and a publicly reachable HTTPS endpoint:

OAUTH_ENABLED=true
PUBLIC_BASE_URL=https://<your-postgram-host>

Configure this public connector URL:

https://<your-postgram-host>/mcp

Add it through Claude’s Connectors UI. ChatGPT can use it only when the account has custom-connector or developer-mode access. The authorization page asks for a Postgram API key once; OAuth tokens inherit that key’s scopes and stop working if the source key is revoked.

See the OAuth connector guide for the full setup flow.

Notes

• MCP transport is Streamable HTTP, not SSE. It does not change your persistence model or auth boundaries.
• Tool output defaults can be compact; the underlying API remains JSON.
• Remote connectors must reach Postgram over public HTTPS, either directly, through a tunnel, or through explicit allowlisting.