Codex Agentic Gateway

Use when the user wants to query the Codex Supergraph and the server returns a 402 challenge. Pays per query via the MPP 402 challenge flow. Only supports queries, not mutations or subscriptions.

Codex Machine Payment Protocol (MPP)

Use this skill when the Codex Supergraph returns a 402 Payment Required response. The MPP challenge flow lets you pay per query without needing an API key. For higher volume, get an API key at dashboard.codex.io/signup — see docs.codex.io for details.

HTTP endpointhttps://graph.codex.io/graphql
Credential headerAuthorization: Payment <base64url-credential>

How it works

  1. Send a GraphQL query (no credential).
  2. Server returns 402 Payment Required with WWW-Authenticate: Payment ... challenges.
  3. Client solves one challenge and retries with Authorization: Payment <credential>.
  4. Server returns GraphQL data + Payment-Receipt header.

Constraints

  • Query only. Mutations and subscriptions return 403 in MPP mode.
  • If a valid API key or bearer token is also present, API auth takes precedence.

Rules

  • Never print raw credentials.
  • Only use MPP for query operations.
  • Before constructing any query, read references/query-templates.md below for the correct GraphQL schema. Do not guess query or field names.

References

FilePurpose
../codex-supergraph/references/query-templates.mdGraphQL query schema and examples — read before constructing queries
../codex-supergraph/references/gotchas.mdCommon query failure points
references/gotchas.mdMPP-specific failure points
rules/wallets.mdWallet setup: tempo wallet/request (Tempo)
references/mpp-flow.mdAuth matrix, challenge details, error codes

Links