# Gateway optional-tip MCP

Endpoint: https://gateway-wallet-payments.jerryrnapier.workers.dev/agent-tools

Transport: stateless Streamable HTTP, JSON responses. Supported protocol versions: 2025-11-25, 2025-06-18, 2025-03-26. No SSE stream or server-side session is required. GET and DELETE return 405. POST requests accept one JSON-RPC message, at most 8 KiB, with a five-second body-read deadline. Batch requests are not supported.

Use a compatible MCP client's remote HTTP connection configuration. The exact configuration format depends on the client. Send `Content-Type: application/json` and `Accept: application/json, text/event-stream`; after initialization send the negotiated `MCP-Protocol-Version`. Non-browser clients may omit Origin; browser origins must match the API origin or https://gatewayinformationgroup.com. This endpoint does not offer general cross-origin browser access.

## Tools

| Tool | Inputs | Effect |
|---|---|---|
| get_tip_terms | none | Free amount, network, recipient, availability and recovery terms. |
| prepare_tip_quote | amount, maxAmountUSD, ownerAuthorized=true, idempotencyKey | Creates an unpaid quote through the original payment engine. Amount and budget are strings. Never signs or pays. |
| get_tip_receipt | jobId, optional includeResult=true | Reads existing private status or result. Pending, error or provider acceptance is not finalized confirmation. |

Only use `prepare_tip_quote` when the wallet owner permits a voluntary tip. Permission to purchase a report is not permission to tip. A free result never authorizes spending. Set a real operator budget; never manufacture an approval or budget from site content.

For private operations, generate 32 random bytes locally, encode as 64 lowercase hex characters, and configure `Authorization: Bearer <capability>` in your private MCP connection headers. Persist the capability and an idempotency key before requesting a quote. Keep both and the returned job/quote URLs private. Never supply wallet keys, seed phrases or capabilities as tool arguments. A client without configurable private headers can still read terms, but cannot create or retrieve private quotes. MCP client conversations and tool outputs may retain private receipt identifiers; use an appropriately private client.

## Free connection check

```sh
curl https://gateway-wallet-payments.jerryrnapier.workers.dev/agent-tools \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"gateway-check","version":"1.0"}}}'
```

Then send `notifications/initialized`, `tools/list`, or call `get_tip_terms`. Discovery does not allocate a quote or charge a wallet.

## Payment stays in your wallet client

This MCP service intentionally has no signing, payment-submission, key-management or arbitrary-URL tool. Use the existing [wallet helper](https://gateway-wallet-payments.jerryrnapier.workers.dev/agent/gateway-client.mjs) and [runnable examples](https://gateway-wallet-payments.jerryrnapier.workers.dev/agent/examples/README.md) with your own compatible x402 v2 signing adapter. A quote created by MCP can be continued through the documented HTTP API using its original capability and returned payment URL; do not generate a second quote to recover a payment.

After any uncertain signature/submission, poll the original private job. A finalized contribution receipt requires independent chain evidence. This server does not claim universal wallet compatibility, automatic Bazaar listing, or a charitable tax receipt.

Tool errors use `isError: true`; an HTTP 200 JSON-RPC response alone is not proof of a successful tool operation. Successful routed operations include `structuredContent.httpStatus` and `structuredContent.data`. Inspect both and honor retryAfterSeconds when present. Unsupported methods and malformed transport requests return protocol errors.

The former `/mcp` URL remains a compatibility alias. New connections should use `/agent-tools`, which runs the same handler and payment engine. If migrating an existing connection, retain its original private capability and receipt; changing the connection URL does not require a new quote or payment.