mcpField
C
codex-gateway

codex-gateway

github.com/codex-dataData & databases0367 installsUpdated 2w ago
Repository

About codex-gateway

codex-gateway is an agent skill for using Codex’s Machine Payment Protocol when the Supergraph API returns a 402 response. It guides clients through paying for individual GraphQL queries without an API key.

Key features

  1. 01402 challenge-response flow
  2. 02Per-query payment without an API key
  3. 03Payment receipt handling
  4. 04GraphQL query-only mode

Use cases

  1. 01Retry a query after a 402 response
  2. 02Access Codex data without API-key authentication

MCP support

The skill concerns payment access to the Codex GraphQL API and does not describe MCP functionality.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/codex-data/skills --skill codex-gateway

After installing, type/codex-gatewayin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
gotchas.md
mpp-flow.md
rules/
wallets.md

Details

From the project README

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 (one-time $1 activation, no recurring cost on the entry plan) — 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

Comments

Markdown supported