Connection and discovery
Connect a host to the MCP endpoint with OAuth, confirm its tools, and refresh them when the catalog changes.
Configure the full /mcp URL in a host that supports remote Streamable HTTP MCP with OAuth, sign in, and confirm its host-specific catalog. The default profile has thirteen tools. A connection Envoy identifies as Claude receives nine and omits report_checkout_result, report_checkout_step and the deprecated submit_answer and get_merchants. A connection Envoy identifies as ChatGPT receives eight: it also omits list_gift_card_merchants.
Support revision: envoy@2026-10. Last updated: 3 November 2026.
Connect the host
https://api.envoy.money/mcpDo not configure the endpoint as stdio, legacy SSE or a browser page. To make a first purchase, follow the MCP quickstart.
The same tools are also served over HTTP at POST /tools/{tool}, listed at GET /tools and described at /openapi.json. See the API reference.
Transport
Send each JSON-RPC message in its own POST. The response depends on the request.
| Request | Response | Content type |
|---|---|---|
Ordinary tools/call or other request | One JSON-RPC response | application/json |
Held get_purchase_status without _meta.progressToken | One JSON-RPC response | application/json |
Held get_purchase_status with _meta.progressToken | notifications/progress messages, then the result, on the same POST | text/event-stream |
| Batch of messages | 400 | Error |
GET or DELETE | 405 with Allow: POST | Error |
The progress messages are plain sentences. They never contain card details or purchase ids.
The endpoint is stateless. Envoy assigns no session id.
This is Streamable HTTP response streaming on a POST. It is not a legacy SSE endpoint and it opens no GET stream.
Send these headers: Authorization: Bearer <token>, Content-Type: application/json and Accept: application/json, text/event-stream.
Sign in with OAuth
An unauthenticated request gets 401 with protected-resource metadata in WWW-Authenticate. The host uses that metadata to run OAuth with PKCE. The host sends the user to Envoy to sign in. The owner reviews the terms and approves the connection. Connecting lets this assistant read your Envoy account and ask to buy. It does not approve a purchase. The user approves card-backed purchases in the Envoy app. If Envoy offers a gift-card payment link, the user pays it themselves. Follow the OAuth guide for registration, callbacks, scope and resource.
- Do not copy an OTP, access token, authorization code or callback URL into the conversation.
- Envoy derives the account, client and connection from the sign-in. A tool argument cannot choose another owner.
- Ordinary MCP connections use bearer authentication. A connection already bound to an installation key must keep sending its
Envoy-Installation-Proof; do not copy credentials into a host that cannot send that proof. - Before a tool call starts, a missing or invalid bearer returns HTTP
401withWWW-Authenticate. This transport error hasAUTH_REQUIREDin its body. The host renews once with its refresh token if it holds one. If renewal fails or it has none, the user signs in again. - A valid key-bound connection without the correct installation proof gets
INSTALLATION_PROOF_REQUIRED. The host sends a fresh proof from the original installation. If the key is lost, the user signs in again as a new connection. Envoy never falls back to bearer-only access. - After a tool call starts, an authentication failure reads as a plain sentence asking the user to reconnect. On the HTTP tool API, the reply has
error.codeUNAUTHENTICATEDandnext.actionreconnect. See connection recovery. - Disconnecting ends the agent's access. Disconnecting does not close a card Envoy already released. Envoy releases no further card details after a disconnect. Disconnecting does not cancel an open purchase: it stays in its state, and another connection of the same agent can read or report it. Cancellation is available before a checkout report, and again when Envoy reopens the card after a failed report.
Confirm the host-specific tools
After connecting, the host calls tools/list. The default catalog contains these thirteen tools:
| Tool | Use it to | Reads or changes | Needs the user in the Envoy app |
|---|---|---|---|
get_account | Read balance, services and any active purchase; with include, the profile or saved addresses. Never returns card details. | Reads | No |
list_transactions | Read the user's transaction history as the Envoy app shows it, with a cursor for the next page. | Reads | No |
list_purchases | Find a purchase without its ID: the purchases made through this agent, newest first, as Envoy last saw them. Check one with get_purchase_status before telling the user where it stands. Never returns card details. | Reads | No |
start_purchase | Start one purchase. Returns at once. | Changes (starts a purchase) | The user completes approval or payment in the app, or pays a returned gift-card link. Follow the reply. |
get_purchase_status | Read progress. Authorized ready replies can release the purchase's payment details. Host restrictions still apply. | Reads | The read itself needs no new approval. Follow any app step or payment-link task in the reply. |
answer_purchase_question | Send the user's reply to purchase.question, or optional feedback with a rating from 1 to 5. | Changes | No |
submit_answer | The deprecated name of answer_purchase_question: same input and result. Prefer answer_purchase_question. | Changes | No |
report_checkout_result | Report paid or failed after checkout. If you cannot tell, report failed with reason other. | Changes | No |
report_checkout_step | Show an agent checkout step in the Envoy app. Moves no money and returns no card. | Changes | No |
cancel_purchase | Cancel when the user changes their mind or the merchant total differs. | Changes (destructive) | No |
list_gift_card_merchants | See the gift-card guide. List the merchants a gift card can be bought for, with the face amounts on offer and the discount, which is "up to": it applies only if the user pays by payment link, and a user who already has an Envoy card pays the face value by card. The price is confirmed when the purchase starts. | Reads | No |
get_merchants | The deprecated name of list_gift_card_merchants: same input and result. Prefer list_gift_card_merchants. | Reads | No |
search_products | Search Elixir's own marketplace for a product when the user names no specific merchant, or asks for Elixir. Each product shows its price and the total for the quantity; the user picks one and the agent buys it with start_purchase. | Reads | No |
The Reads or changes column follows each tool's annotations. Only get_account, list_transactions, list_purchases, get_purchase_status, list_gift_card_merchants, get_merchants and search_products are read-only. start_purchase, report_checkout_result and cancel_purchase have destructive hints. Only start_purchase has the open-world hint. These annotations do not describe every downstream effect: a ready status read can release credentials.
The tools/list result carries _meta.contract (envoy@2026-10). Each tool has annotations (read-only, destructive, idempotent, open-world hints); hints describe a tool, they do not grant permission. Use the schemas the host discovered; a name on this page is not proof the host has it.
A connection Envoy identifies as Claude receives nine tools and omits report_checkout_result, report_checkout_step and the deprecated submit_answer and get_merchants, which still run there if called. The same applies in Claude's web, Desktop and Cowork connectors. Envoy completes checkout for those purchases, and get_purchase_status never carries card details. A connection Envoy identifies as ChatGPT receives eight tools, in ChatGPT Work too: it also omits list_gift_card_merchants, and it buys only from Elixir's marketplace: products found with search_products, started with their product_id. The HTTP API and default MCP catalog expose all thirteen.
Initialization also returns server instructions. Read the briefing first. Do what What to do says. Never show the JSON line, codes or ids to the user, because the user cannot use them. On the agent checkout route, pay once while ready. On the Envoy checkout route, Envoy completes checkout. Keep OTPs out of replies. The MCP reply format explains each result.
Refresh a stale catalog
If the host lists a different catalog than expected for that host, refresh it. The default profile should list the thirteen tools above; a connection Envoy identifies as Claude should list the nine tools described above, omitting report_checkout_result, report_checkout_step, submit_answer and get_merchants, and one identified as ChatGPT the eight, also omitting list_gift_card_merchants. Use the host's tool refresh or reconnect flow, then list the tools again in a fresh task. Calling a tool the server does not serve returns an MCP InvalidParams error, not a tool result.
Refreshing a skill or plugin package does not refresh tool schemas, and refreshing tool schemas does not change the account connection. No host has a verified universal refresh or memory behavior; Connect your assistant covers each host.