gopigeon

@gopigeon/mcp

MCP server for Gopigeon — anonymous form endpoints + durable queues for AI coding agents. Nine stdio tools, zero signup.

Tools

Nine stdio tools across three surfaces.

Forms (3 tools)

• create_endpoint — no auth; create an anonymous Gopigeon endpoint (supports dry_run: true for forward-compat — see note below)
• get_submissions — requires GOPIGEON_API_KEY; read submissions you own
• list_endpoints — requires GOPIGEON_API_KEY; list endpoints you own

Queues (5 tools, post-v1.0 surface)

• create_queue — no auth; returns queue_api_key ONCE
• publish_to_queue — requires GOPIGEON_QUEUE_API_KEY (supports dry_run: true for routing preview)
• pull_queue — requires GOPIGEON_QUEUE_API_KEY
• ack_queue — requires GOPIGEON_QUEUE_API_KEY
• subscribe_form_to_queue — requires GOPIGEON_API_KEY (forms-side, not queue-side)

Utility (1 tool, works with both surfaces)

• inspect_endpoint — no auth; no-side-effect probe; prefix-dispatches on f_* (form) / q_* (queue) IDs; v1.3 verifiability primitive paired with dry_run

Quota

Free tier: 100 messages/month per user across all queues.

On exceed, publish_to_queue returns HTTP 402 with auto_enqueued: true — the envelope is durably persisted server-side and will replay automatically when you (or the queue owner) upgrade to Pro. No envelope is silent-dropped.

For owned (Bearer-claimed) queues, the counter is per-user across every queue they own. For anonymous (unclaimed) queues, a separate per-source-IP counter applies; the envelope still persists, but replay requires the queue to be claimed AND the owner to upgrade.

Read the full Free vs Pro section at /docs/queues#free-vs-pro.

Verifiability (v0.3.0+)

Before consuming the one-shot claim event, agents can verify endpoint wiring without side effects. Two mechanisms — one is a flag on the existing tools, the other is a new probe tool.

Dry-run mode — dry_run flag on existing tools

Pass dry_run: true to create_endpoint or publish_to_queue. The tool appends ?dry_run=1 to the outgoing request; the backend runs the full guard cascade (CORS, rate-limit, honeypot, quota read for forms; Bearer auth, body-size guard, read-only quota preview for queues) and returns a routing preview only — sends nothing, no claim email, no funnel event, no quota counter, no AMQP publish.

// MCP tool call (Claude Code):
{
  "tool": "publish_to_queue",
  "args": {
    "queue_id": "q_abc123",
    "payload": { "hello": "world" },
    "dry_run": true
  }
}
// → structuredContent: { dry_run: true, would_route_to: [...], would_have_counted: {...} }

The dry_run field is z.boolean().optional().default(false) — agents using older @gopigeon/mcp@^0.2.0 that omit the field continue to work; the URL has no ?dry_run=1 suffix (a regular real-submission call).

Dry-run is a routing preview — sends nothing. Not a sandbox tier.

Claim-status probe — inspect_endpoint tool

inspect_endpoint is a no-side-effect probe that prefix-dispatches on the endpoint ID:

• f_* IDs route to GET /f/{id}/status
• q_* IDs route to GET /q/{id}/status
• Other prefixes return a structured error WITHOUT making an HTTP call

Returns {exists, claimed, active} on 200, or {exists: false} on 404 (treated as a valid "not found" answer, not an error). The tool advertises readOnlyHint: true, idempotentHint: true so agent runtimes can safely cache or reorder calls. Shares the 60/min/IP rate-limit bucket with ?dry_run=1 requests.

// MCP tool call:
{
  "tool": "inspect_endpoint",
  "args": { "endpoint_id": "f_abc123def456xyz0" }
}
// → structuredContent: { exists: true, claimed: false, active: true }

Use this BEFORE consuming the claim event with a real submission — it tells you whether the form exists and whether the one-shot claim slot is still available.

Response shapes

Tool	Real call returns	Dry-run / probe returns
create_endpoint	{form_id, endpoint_url, claim_note}	{dry_run: true, would_route_to, ...}
publish_to_queue	{seq, id}	{dry_run: true, would_have_counted: {quota_used, quota_remaining}}
inspect_endpoint	(no real-call variant — always probe)	{exists, claimed, active} or {exists: false}

Install as a Claude Code plugin

The quickest way to get both the connector and the gopigeon skill — which teaches agents how to use it — is the plugin:

/plugin marketplace add arvaer/gopigeon-mcp
/plugin install gopigeon@gopigeon-mcp

That wires up the MCP server and installs the skill in one step. Set GOPIGEON_API_KEY / GOPIGEON_QUEUE_API_KEY in your environment first if you need the authenticated tools (see Environment).

Prefer to wire the MCP server up by hand? The manual installs are below.

Install (Claude Code)