# Envoy documentation

Connect agents through the API or MCP. This documentation describes the Envoy tools of contract `envoy@2026-10`, served over MCP and `POST /tools/:tool`. Availability is described on its own page. Guidance never grants consent or spending authority.

- [Introduction](/docs/)
- [Connect Envoy to your assistant](/docs/markdown/get-started/mcp-quickstart.md): Add the MCP server, sign in and get a first read-only account reply.
- [Connect your assistant](/docs/markdown/integrations/hosts.md): Pick the connection path for your assistant, then finish at your first read-only account check.
- [Envoy in Claude](/docs/markdown/integrations/claude.md): Connect Claude to Envoy, install the skills, and refresh or remove your installation.
- [Envoy in ChatGPT](/docs/markdown/integrations/chatgpt.md): Connect ChatGPT to Envoy, install the skills, and refresh or remove your installation.
- [Envoy in ChatGPT Work](/docs/markdown/integrations/chatgpt-work.md): Connect ChatGPT Work to Envoy, install the skills, and refresh or remove your installation.
- [Envoy in Cursor](/docs/markdown/integrations/cursor.md): Connect Cursor to Envoy over MCP, verify the account read, and disconnect safely.
- [Envoy in Grok](/docs/markdown/integrations/grok.md): Connect Grok to Envoy, install the skills, and refresh or remove your installation.
- [Envoy in Meta Muse](/docs/markdown/integrations/muse.md): Use Envoy's browser pages in Meta Muse and distinguish that path from an unverified connector.
- [Disconnect or remove Envoy](/docs/markdown/integrations/disconnect.md): Four separate actions to stop using Envoy with a host, what each one does, and what none of them does.
- [Make a purchase, start to finish](/docs/markdown/payments/walkthrough.md): Start one purchase, follow its user task and checkout route, then read the purchase outcome and money status.
- [Before your first purchase](/docs/markdown/get-started/before-you-start.md): The checklist of what must be true before an agent can buy with Envoy, and how to fix each missing item.
- [Complete checkout after approval](/docs/markdown/payments/complete-checkout.md): Follow Envoy's chosen checkout route, report what happened and confirm the outcome.
- [Buy and follow a gift card](/docs/markdown/payments/gift-vouchers.md): Discover a supported merchant, start one gift-card purchase, and follow its money, voucher and next action without paying twice.
- [Recover a purchase](/docs/markdown/payments/recovery.md): The full procedure to read and reconcile a purchase after a lost reply, a timeout or a reconnect, without paying twice.
- [Reconnect and resume your task](/docs/markdown/troubleshooting/connection-recovery.md): Sign the agent in again, refresh a stale tool list, and pick up the same purchase without paying twice.
- [Follow next and refresh tools](/docs/markdown/integrations/guidance.md): Each reply says what to do next; tool schemas and skill packages update separately and are refreshed through the host.
- [Two focused skills](/docs/markdown/integrations/skills.md): One skill buys and recovers purchases, the other answers account questions; skills carry instructions and grant no authority.
- [Downloads for agents](/docs/markdown/integrations/downloads.md): Download the contract as OpenAPI, the MCP catalog, synthetic examples, the docs as Markdown and the 0.4.15 skill packages.
- [Data and permissions](/docs/markdown/get-started/data-and-permissions.md): What an Envoy connection lets an assistant read or change, and which records Envoy keeps.
- [Availability and limits](/docs/markdown/get-started/availability.md): Who can connect, what a purchase can be, and the request limits the service enforces.
- [API quickstart](/docs/markdown/get-started/api-quickstart.md): Call the Envoy tools over HTTPS with an OAuth bearer and read the account.
- [OAuth with PKCE](/docs/markdown/api/authentication.md): Discover the authorization server, register a public client, sign the owner in and renew or revoke the connection.
- [HTTP routes](/docs/markdown/api/tools.md): Every HTTP route the service mounts, what it needs and the status codes it returns.
- [Requests, pagination and retries](/docs/markdown/api/requests.md): Send strict inputs, keep the identifiers that make a purchase recoverable, page through history and retry only as told.
- [Request protection](/docs/markdown/api/security.md): Prove a key-bound request, and keep the one-time card out of logs, history and other replies.
- [Errors and reason codes](/docs/markdown/troubleshooting/errors.md): What each error code and reason code means, and the next step the reply gives your agent.
- [Tool reference](/docs/markdown/mcp/reference.md): Every tool of contract envoy@2026-10: inputs, success data and errors.
- [get_account](/docs/markdown/mcp/reference/get_account.md): Read account sections at task start or when the purchase reference is lost.
- [list_transactions](/docs/markdown/mcp/reference/list_transactions.md): Read the user's transaction history exactly as the Envoy app shows it, newest first, with an opaque pagination cursor.
- [list_purchases](/docs/markdown/mcp/reference/list_purchases.md): Use this when the user asks about a purchase and you lack its purchase_id: purchases made through you, newest first.
- [start_purchase](/docs/markdown/mcp/reference/start_purchase.md): Start a purchase when the user asks to pay with Envoy or has chosen Envoy as the default for this checkout.
- [get_purchase_status](/docs/markdown/mcp/reference/get_purchase_status.md): Omit purchase for the active/latest one; pass after_revision and the read holds up to `wait_seconds` (contract maximum 45 seconds, `HOLD_MAX_SECONDS`); the server may hold less; follow `next.args.wait_seconds`; call again as soon as it returns.
- [answer_purchase_question](/docs/markdown/mcp/reference/answer_purchase_question.md): Use this when a purchase is waiting on the user (needs_details or needs_answer): send their reply to purchase.question, or feedback after purchase.follow_up, or at any time.
- [submit_answer](/docs/markdown/mcp/reference/submit_answer.md): Deprecated name of answer_purchase_question; same input and result.
- [report_checkout_result](/docs/markdown/mcp/reference/report_checkout_result.md): Only when checkout_by is agent: report paid only on merchant confirmation; if completion is unclear, report failed with failure_reason other.
- [report_checkout_step](/docs/markdown/mcp/reference/report_checkout_step.md): Call at each step of your own checkout (checkout_by agent): the user watches it live in the Envoy app.
- [cancel_purchase](/docs/markdown/mcp/reference/cancel_purchase.md): Before any checkout report, request a stop when the user changes their mind or the merchant total differs.
- [list_gift_card_merchants](/docs/markdown/mcp/reference/list_gift_card_merchants.md): List merchants selling gift cards.
- [get_merchants](/docs/markdown/mcp/reference/get_merchants.md): Deprecated name of list_gift_card_merchants; same input and result.
- [search_products](/docs/markdown/mcp/reference/search_products.md): Search Elixir's marketplace when the user wants a product and names no merchant, or asks for Elixir or Envoy.
- [Changelog](/docs/markdown/releases/changelog.md): High-level features, changes and fixes, with required integration updates.
- [Migrate from contract 1](/docs/markdown/releases/migrate-from-contract-1.md): Move an integration from the retired contract 1 tools to the tools of envoy@2026-10.
- [Troubleshooting and support](/docs/markdown/troubleshooting.md): Find your symptom, follow the reply's next step, and reach support when the outcome is unclear.
- [Frequently asked questions](/docs/markdown/troubleshooting/faq.md): Short answers about test mode, missing cards, approval, card guarantees, KYC, limits, paying twice, support references and disconnecting an agent.
- [Host compatibility evidence](/docs/markdown/integrations/compatibility.md): What Envoy has and has not verified on each host, with dates. Read it before you rely on a host.
- [answer_purchase_question](/docs/markdown/api/reference/answer_purchase_question.md): Use this when a purchase is waiting on the user (needs_details or needs_answer): send their reply to purchase.question, or feedback after purchase.follow_up, or at any time.
- [cancel_purchase](/docs/markdown/api/reference/cancel_purchase.md): Before any checkout report, request a stop when the user changes their mind or the merchant total differs.
- [get_account](/docs/markdown/api/reference/get_account.md): Read account sections at task start or when the purchase reference is lost.
- [get_merchants](/docs/markdown/api/reference/get_merchants.md): Deprecated name of list_gift_card_merchants; same input and result.
- [get_purchase_status](/docs/markdown/api/reference/get_purchase_status.md): Omit purchase for the active/latest one; pass after_revision and the read holds up to `wait_seconds` (contract maximum 45 seconds, `HOLD_MAX_SECONDS`); the server may hold less; follow `next.args.wait_seconds`; call again as soon as it returns.
- [Tool reference](/docs/markdown/api/reference.md): Every tool of contract envoy@2026-10: inputs, success data and errors.
- [list_gift_card_merchants](/docs/markdown/api/reference/list_gift_card_merchants.md): List merchants selling gift cards.
- [list_purchases](/docs/markdown/api/reference/list_purchases.md): Use this when the user asks about a purchase and you lack its purchase_id: purchases made through you, newest first.
- [list_transactions](/docs/markdown/api/reference/list_transactions.md): Read the user's transaction history exactly as the Envoy app shows it, newest first, with an opaque pagination cursor.
- [report_checkout_result](/docs/markdown/api/reference/report_checkout_result.md): Only when checkout_by is agent: report paid only on merchant confirmation; if completion is unclear, report failed with failure_reason other.
- [report_checkout_step](/docs/markdown/api/reference/report_checkout_step.md): Call at each step of your own checkout (checkout_by agent): the user watches it live in the Envoy app.
- [Schemas](/docs/markdown/api/reference/schemas.md): The reply envelope, purchase, next action, errors and every tool's exact input and output schema.
- [search_products](/docs/markdown/api/reference/search_products.md): Search Elixir's marketplace when the user wants a product and names no merchant, or asks for Elixir or Envoy.
- [start_purchase](/docs/markdown/api/reference/start_purchase.md): Start a purchase when the user asks to pay with Envoy or has chosen Envoy as the default for this checkout.
- [submit_answer](/docs/markdown/api/reference/submit_answer.md): Deprecated name of answer_purchase_question; same input and result.
- [Who enters which code](/docs/markdown/concepts/credentials.md): Which person or program enters each Envoy credential, where it may go, and what to do when your host forbids entering a code.
- [Glossary](/docs/markdown/concepts/glossary.md): One definition for each Envoy term, purchase state, situation and money value, plus the support reference.
- [How Envoy works](/docs/markdown/concepts/how-envoy-works.md): Request a purchase, complete its user task and follow the checkout route and money outcome Envoy returns.
- [KYC and eligibility](/docs/markdown/concepts/kyc-and-eligibility.md): What KYC is, where the user completes it, and what an agent does when a purchase needs it.
- [First success](/docs/markdown/get-started/first-success.md): Every setup path ends with one read-only account call. Run it to confirm your connection works.
- [Connection and discovery](/docs/markdown/mcp/connection.md): Connect a host to the MCP endpoint with OAuth, confirm its tools, and refresh them when the catalog changes.
- [Replies and next steps](/docs/markdown/mcp/results.md): Read an MCP tool result: the briefing first, then What to do, then the data keys for the next call.
- [Account and transactions](/docs/markdown/payments/account.md): Read the balance, spendable amount, bank-held money, open purchase money, enabled services and open purchase, and list past transactions, without starting a purchase.
- [Pay from a saved-card vault](/docs/markdown/payments/saved-card-vault.md): Use the one-time card details as usual, or ask Envoy to save the card to the user's Instinct vault and pay from there.
- [Connection recovery](/docs/markdown/troubleshooting/connections.md): Reconnect the original account and preserve the purchase.
- [Recover a purchase](/docs/markdown/troubleshooting/payment-recovery.md): Find your symptom and recover a purchase without paying twice.
- [Recover a purchase](/docs/markdown/troubleshooting/payments.md): Find your symptom and recover a purchase without paying twice.

[Privacy](https://envoy.money/privacy) · [Terms](https://envoy.money/terms)