PostGrid MCP

Standalone Vercel-native Model Context Protocol server for read-only PostGrid Print & Mail access. It exposes a small set of constrained tools over PostGrid's live API. No database, no external services beyond PostGrid itself.

Designed for Claude Cowork custom connectors (OAuth Individual sign-in).

What this is (and is not)

This MCP	PostGrid hosted MCP (postgrid.readme.io/mcp)
Constrained read-only tools	Arbitrary API executor
Server-held PostGrid key + Cowork OAuth	Pass-your-key patterns

Non-goals (v1): send/cancel mail, Address Verification, arbitrary raw GET, pricing/commission logic, data persistence.

Tools

• postgrid_ping
• postgrid_list_sub_orgs
• postgrid_schema_probe

Quick start (local)

npm install
cp .env.example .env.local
# fill OAUTH_TOKEN_SECRET, OPERATOR_PASSWORD, POSTGRID_API_KEY
npm run dev

• App: http://localhost:3000
• MCP: http://localhost:3000/api/mcp

Claude Cowork connect

1. Deploy to Vercel and set env vars from .env.example (PUBLIC_BASE_URL, MCP_ALLOWED_HOSTS, secrets).
2. In Claude Cowork: Settings → Connectors → Add custom connector
3. Remote MCP server URL: https://<your-deployment>/api/mcp
4. Leave OAuth Client ID / Secret blank (CIMD). Enable Individual sign-in.
5. Click Connect → sign in with OPERATOR_USERNAME / OPERATOR_PASSWORD.
6. Enable the connector in a Cowork conversation and run postgrid_ping.

Callback used by Claude: https://claude.ai/api/mcp/auth_callback.

Security

• OAuth access tokens are HMAC-signed; MCP route returns 401 + WWW-Authenticate when unauthenticated.
• PostGrid key never leaves the server.
• Sub-org impersonation can be constrained with POSTGRID_ALLOWED_ORG_IDS.
• Signed URLs are redacted before responses/logs.
• PostGrid list calls are throttled in-process (about 10/min per instance) to respect PostGrid's GET List rate limit.

See SECURITY.md.

Scripts

npm run dev
npm run build
npm run typecheck
npm test
npm run lint

License

MIT (see LICENSE). Keep private rate cards and customer data out of this repository.