ZipPigeon technical whitepaper Updated Aug 2, 2026 3 min read

Preserve the delegated-access boundary

The Streamable HTTP adapter calls the same request, approval, grant, retrieval, and receipt operations as the native agent API. It cannot browse a case, accept wildcard artifacts, approve its own request, proxy decrypted file contents, or forward its OAuth token to another resource.

  • ZipPigeon acts as the MCP resource server, not the authorization server.
  • The case owner still reviews and rewraps exact file keys in the browser.
  • Retrieval returns an encrypted capability, not plaintext content.

Discover and authorize the exact MCP resource

Clients discover configured authorization servers and supported scopes from OAuth protected-resource metadata. The endpoint accepts a signed OIDC access token with typ at+jwt, the exact bound issuer and subject, exactly one MCP audience, bounded lifetime, client ID, JTI, issue time, expiry, and an eligible scope.

GET  /.well-known/oauth-protected-resource/api/mcp
POST /api/mcp

resource=https://files.example.com/api/mcp
scope=agent_access:request agent_access:consume

Require signed agent proof on every MCP call

OAuth token possession is not sufficient. Every MCP HTTP request also includes the ZipPigeon service-account ID, timestamp, unique nonce, and agent signature over the method, path, body digest, timestamp, nonce, and ID. ZipPigeon API and workload-exchange bearer tokens are not accepted in place of the MCP OAuth token.

  • Use an MCP client or gateway that can add custom signed HTTP headers.
  • Keep the agent signing bundle outside the language model prompt and tool arguments.
  • Reject access tokens minted for any other audience.

Use four narrow tools

The adapter exposes only the operations needed for delegated retrieval: request exact access, read that request status, issue an approved encrypted retrieval capability, and export its receipt. Consume tools require agent_access:consume and return a minimum-scope challenge when the token has only request scope.

zippigeon_agent_access_request      # agent_access:request
zippigeon_agent_access_status       # agent_access:request
zippigeon_agent_access_retrieval    # agent_access:consume
zippigeon_agent_access_receipt      # agent_access:consume

Benefits and use cases

MCP gives compatible assistants a standard tool-discovery and invocation surface while ZipPigeon keeps authorization purpose-built. It fits an incident copilot requesting named evidence, a compliance assistant waiting for owner approval, or an enterprise agent gateway that already obtains exact-audience OAuth tokens.

  • Incident copilot: request a bounded artifact list and poll only its request status.
  • Compliance assistant: export a receipt after approved encrypted retrieval is issued.
  • Agent gateway: centralize OAuth acquisition while preserving per-agent ZipPigeon key proof.

Enable the adapter only with its prerequisites

The MCP surface fails closed unless delegated access, workload federation, an exact public HTTPS MCP resource, and one or more trusted authorization servers are configured. Apply short access-token lifetimes, public-key retrieval protections, rate limits, no-store responses, and sanitized audit events before production exposure.

AGENT_DELEGATED_ACCESS_ENABLED=true
AGENT_WORKLOAD_FEDERATION_ENABLED=true
MCP_AGENT_ACCESS_ENABLED=true
MCP_AGENT_ACCESS_RESOURCE=https://files.example.com/api/mcp
MCP_AUTHORIZATION_SERVERS=https://identity.example.com