REST API and MCP

Use REST and MCP when a Gateway workflow must be repeatable, attributable, and independent of one operator’s browser. The automation owner maintains the client, resource owners approve its boundaries, and platform operators own runtime recovery. Success is a reconciled product outcome with durable evidence—not merely an accepted HTTP request or completed tool call.

The REST API exposes documented resource operations with session, API-token, or OAuth authentication as appropriate. Remote MCP provides task-oriented tools over the same scopes, validation, entitlements, and audit trail.

Automation should:

use a dedicated least-privilege identity;
treat 202 or task creation as accepted work, then poll durable state;
retry only idempotent operations or use the operation’s retry contract;
handle 401, 403, 409, 422, and node-offline failures distinctly;
avoid parsing UI text when a structured API field exists;
record resource IDs and request IDs without logging secrets.

Use the OpenAPI document served by the running Gateway instance for exact request and response schemas. The schema version must match the instance being automated; do not copy request bodies from a different release. Product guides describe the required resource ordering and operational consequences that schemas alone cannot capture.

Authentication and discovery

Choose a session, API token, or OAuth client according to the caller. Remote MCP clients authorize through OAuth and discover task-oriented tools filtered by the same scopes and product state. Tool presence is not proof that a particular resource mutation will be admitted.

Start automation by reading the target resource and capability state. Resolve stable IDs rather than scraping names from the UI. Keep the base URL, token, and environment separate so a development script cannot accidentally target production.

Connect Codex or Claude Code through MCP

Gateway exposes its authenticated remote MCP server at:

https://gateway.example.com/api/mcp

Replace gateway.example.com with the canonical public hostname of your Gateway installation. Use the same HTTPS origin that operators use to open Gateway. Do not append another /mcp, and do not point the client at the REST API root.

Once connected, the client can discover Gateway tools and perform only operations allowed to the signed-in user. MCP does not grant administrator access or bypass resource scopes, plan entitlements, confirmations, or audit logging.

Prepare Gateway

An administrator completes these one-time steps:

Open Settings, select Features, and find OAuth and MCP access.
Enable MCP server.
Keep Extended MCP compatibility enabled for normal clients. Disable it only when a client loads the entire tool catalog into its context and cannot handle its size.
Leave OAuth extended callback compatibility disabled for Codex and Claude Code. Their local loopback callbacks work with the safer default policy.
Grant the connecting user Use MCP (mcp:use) plus the ordinary scopes for the resources that client may read or change.

The user must also be able to sign in to Gateway in a browser. If the connection works but a tool or resource is missing, review group membership and resource scopes instead of broadening the OAuth callback policy.

Connect Codex

Add Gateway, complete OAuth login, and verify the connection:

codex mcp add good-gateway --url https://gateway.example.com/api/mcp
codex mcp login good-gateway
codex mcp list

The login command opens Gateway in your browser. Sign in as the intended Gateway user, review the requested access, and approve it. Codex stores the resulting OAuth credential; you do not create or paste an API token.

In the Codex desktop app or IDE extension, you can instead add a Streamable HTTP MCP server with the same URL and select Authenticate. The desktop app, CLI, and IDE extension share the Codex MCP configuration.

Connect Claude Code

Add Gateway as a remote HTTP server for your user account:

claude mcp add --transport http good-gateway --scope user https://gateway.example.com/api/mcp
claude mcp login good-gateway
claude mcp get good-gateway

You can also open an interactive Claude Code session, enter /mcp, select good-gateway, and complete authentication in the browser. Use --scope project instead of --scope user only when the repository should share the server definition through .mcp.json; each developer still signs in with their own Gateway account.

How the OAuth flow works

You do not need to register an OAuth client manually for Codex or Claude Code:

the client contacts /api/mcp and receives Gateway’s OAuth discovery information;
the client registers itself and starts Authorization Code with PKCE;
Gateway opens a browser sign-in and consent screen;
the user approves access bounded by their current Gateway scopes;
Gateway issues an OAuth access token for the MCP resource;
the client stores that credential and sends it to /api/mcp on later requests.

Gateway accepts only OAuth access tokens issued for its MCP resource. Browser cookies, ordinary gw_ API tokens, gwl_ logging tokens, and gwi_ Gateway Inference tokens are rejected. The server rechecks the user’s current scopes and mcp:use, so removing access stops future MCP operations even if the client discovered the tools earlier.

Verify the connection

Start with a read-only request:

List the Gateway nodes I can access and summarize their current status. Do not change anything.

Confirm that the client reports good-gateway as connected, only expected resources are visible, a read succeeds, an action outside the user’s scopes is denied, and Gateway attributes the call to the expected user in the audit log.

MCP connection troubleshooting

The endpoint returns 404: enable Settings → Features → OAuth and MCP access → MCP server and verify that the URL ends in /api/mcp.
The client requires authentication: run codex mcp login good-gateway or claude mcp login good-gateway. In an interactive client, use /mcp.
Login succeeds but Gateway returns 403: the account needs mcp:use and at least one effective resource scope.
The client exhausts its context with too many tools: disable Extended MCP compatibility to use the compact initial catalog and category discovery.
Gateway rejects the OAuth callback: update the client and retry first. Normal Codex and Claude Code loopback callbacks do not require OAuth extended callback compatibility.
A saved connection stopped working: check whether the OAuth authorization, mcp:use, resource scopes, or canonical Gateway URL changed. Re-authenticate instead of substituting a normal API token.

Durable operations

Many infrastructure mutations return an accepted task or operation instead of a completed result:

submit the validated request;
store the returned resource, task, operation, and request IDs;
poll or subscribe to the durable operation state;
inspect structured failure details;
verify the resulting resource state independently;
retry only according to the operation’s idempotency contract.

Do not translate a transport timeout directly into a second create/delete request. The first request may have reached the owning daemon and be awaiting reconciliation.

Error handling

400 or 422: correct request shape or validation input;
401: refresh or replace authentication;
403: distinguish missing scope from missing plan entitlement;
404: verify resource visibility as well as existence;
409: inspect lifecycle conflict, quota, or current state;
429: apply bounded backoff and respect server guidance;
5xx or node offline: preserve request IDs and check durable task state before retrying.

MCP operating rules

Use MCP for goal-oriented operations where the tool schema adds safety and resource context. Read tool descriptions and returned warnings, pass exact resource identifiers, and treat external content as untrusted input. MCP calls are audited and must not be used to bypass confirmation, permission, entitlement, or lifecycle checks.

Verification

For every automation path, test one allowed action, one denied action, one validation failure, one asynchronous success, and one interrupted operation. Confirm audit attribution and make sure logs redact credentials and sensitive request fields.

Designing reliable clients

Model automation as reconciliation rather than a sequence of blind button presses. Read the current resource, compare it with the desired state, submit the smallest required mutation, and verify the resulting owner-reported state. Use stable IDs in stored state and human-readable names only for display. When an API exposes an operation or Task ID, persist it alongside the automation run so an operator can correlate a timeout with Gateway history.

Set bounded connection, request, and overall operation deadlines separately. A short HTTP deadline can coexist with a long-running durable Task. Retry reads and explicitly idempotent updates with capped exponential backoff and jitter. Do not automatically retry creates, deletes, migrations, restores, or credential rotation after an ambiguous timeout unless the API contract provides an idempotency key or the existing operation has been reconciled.

Version the client against the OpenAPI document and the Gateway releases it has actually tested. Reject unknown destructive fields and states rather than silently ignoring them. If a release changes a lifecycle contract, update the client and its acceptance tests before rolling it across all installations.

Safe rollout and rollback

Run new automation against a disposable Folder or resource set with production-like scopes. Capture the intended request, resulting Task, audit record, and independent state verification. Roll out to one installation or failure domain first, then observe errors and reconciliation lag before expanding.

Rollback normally means disabling the caller, stopping new submissions, and applying a supported product rollback to already changed resources. It does not mean deleting Tasks or editing desired state in PostgreSQL. Preserve request IDs and failed payload metadata with secrets removed so the product owner can distinguish a client defect from a Gateway or daemon failure.