# Install Envoy in your agent

Skill and plugin release **0.4.15**, for the current Envoy tool contract (support revision `envoy@2026-10`). Last updated **3 November 2026**.

`pay-with-envoy` handles commerce; `check-envoy-account` handles explicit account questions. Each skill carries its own instructions and follows the `next` step in every Envoy tool reply; there is no separate guidance tool to load. Installing package files alone does not connect an account, select a default or authorize spending. This guide adds no payment, onboarding or recovery instructions.

Connecting lets this assistant read your Envoy account and ask to buy. It does not approve a purchase. You approve card-backed purchases in the Envoy app. For a gift card, follow the returned app approval/payment step or pay the returned link yourself. The app step alone does not identify the funding source. Follow the terms shown in that flow.

Envoy is not yet listed in the ChatGPT or Claude directories, and its ChatGPT submission is in preparation. Until then, add Envoy as a custom connector. Read [Data and permissions](https://agent.envoy.money/docs/get-started/data-and-permissions/), [Privacy](https://envoy.money/privacy) and [Terms](https://envoy.money/terms) before connecting.

## Downloads

| Artifact | Use |
| --- | --- |
| [envoy-pay-with-envoy-0.4.15.zip](https://agent.envoy.money/downloads/envoy-pay-with-envoy-0.4.15.zip) | Individual commerce skill |
| [envoy-check-envoy-account-0.4.15.zip](https://agent.envoy.money/downloads/envoy-check-envoy-account-0.4.15.zip) | Individual read-only account skill |
| [envoy-payments-plugin-0.4.15.zip](https://agent.envoy.money/downloads/envoy-payments-plugin-0.4.15.zip) | OpenAI portable plugin containing both skills; connection configured separately |
| [envoy-claude-plugin-0.4.15.zip](https://agent.envoy.money/downloads/envoy-claude-plugin-0.4.15.zip) | Claude plugin containing both skills and the remote MCP reference |

Verify downloaded archives against [SHA256SUMS](https://agent.envoy.money/downloads/SHA256SUMS) before installation. [skills-release.json](https://agent.envoy.money/downloads/skills-release.json) records the current filenames, URLs, hashes, skill names, endpoint and guide URL. Only the current supported archives are distributed.

## Installation matrix

| Host | Installation and availability |
| --- | --- |
| [Grok](#grok) | Remote connector and private skills. Grok Build is separate. |
| [Claude](#claude) | Paid-plan plugin upload in web Chat, Desktop Chat and Cowork. Separate skill ZIPs also supported; code execution required. Free allows one custom connector. |
| [ChatGPT](#chatgpt) | Developer-mode MCP connection plus approved plugin distribution. Standalone skills are desktop-only; local ZIPs are not web/mobile installers. |
| [ChatGPT Work](#chatgpt-work) | Web remote MCP and workspace-distributed skills; desktop also supports local marketplaces. Hosted Work needs separate verification from ChatGPT and Codex. |
| [Cursor](#cursor) | Remote Streamable HTTP MCP server with OAuth; setup uses `~/.cursor/mcp.json` or the reviewed Add to Cursor link. |

## Connection

Use this exact public **Streamable HTTP** MCP endpoint, with Envoy's existing OAuth flow:

```text
https://api.envoy.money/mcp
```

Configure `/mcp` and check the catalog for the host you connected. The default profile receives all thirteen tools: `get_account`, `list_transactions`, `list_purchases`, `start_purchase`, `get_purchase_status`, `answer_purchase_question`, `submit_answer` (its deprecated name), `report_checkout_result`, `report_checkout_step`, `cancel_purchase`, `list_gift_card_merchants`, `get_merchants` (its deprecated name) and `search_products`. A connection Envoy identifies as Claude receives nine and omits `report_checkout_result`, `report_checkout_step`, `submit_answer` and `get_merchants`. A connection Envoy identifies as ChatGPT receives eight: it also omits `list_gift_card_merchants`, and buys only from Elixir's marketplace (`search_products`, then `start_purchase` with its `product_id`). A different catalog is stale; refresh it as described in [upgrade and refresh](#upgrade-and-refresh). Complete OAuth through the host’s supported setup path. Packages contain no credentials, personal connection IDs or account state.

Open the authorization link generated by the host for this connection attempt. Complete sign-in and review the connection approval. Return to your agent and confirm that the connection is authenticated. Then call `get_account` with `{}` for a read-only check. If sign-in expires or fails, start a fresh sign-in through the host.

Do not paste OTPs, authorization codes, callback URLs containing codes, or access tokens into the conversation.

The tool catalog lists operations, not a promise that every merchant or payment service is available. Read `services` from `get_account` for account availability. Use `get_merchants` and `search_products` only for the discovery each tool supports. Follow the purchase reply for the available payment path.

When Envoy offers a gift-card payment link, the user pays that link. The agent never opens or pays it. The link task supplies the amount due, the gift-card value and the next action. Gift cards can also use an app approval or in-app payment; follow the returned task. The app step does not identify the funding source, and the app shows the actual payable before confirmation. Unused value stays on the gift card. This path does not release a one-time payment card. Its availability depends on the merchant, account and connection; it is not a way around a host restriction.

### Grok

On Grok.com, open **Connectors → New Connector → Custom**, enter the endpoint above and complete authentication if required. Connectors are available to all Grok users; Business/Enterprise administrators must first provision them. The server must be publicly reachable. [Official connector setup](https://docs.x.ai/grok/connectors), [administrator controls](https://docs.x.ai/grok/connector-management), [transport requirements](https://docs.x.ai/grok/connectors/custom-mcp-tunneling).

In Grok Bot, reuse its Envoy connector and provide the unchanged [commerce](https://agent.envoy.money/skills/pay-with-envoy/SKILL.md) and [account](https://agent.envoy.money/skills/check-envoy-account/SKILL.md) sources. Ask the Bot to save them as private skills; inspect the saved content under **Marketplace → Your plugins → Manage plugins and skills**, then verify a fresh task. [Private skills](https://docs.x.ai/grok-bot/skills-routines-and-automations), [management](https://docs.x.ai/grok-bot/settings-and-notifications).

### Claude

Open **Customize → Plugins** and upload `envoy-claude-plugin-0.4.15.zip`. Its `envoy-claude/` folder contains `.claude-plugin/plugin.json`, `.mcp.json`, `README.md` and both skills; its plugin name is `envoy-payments`. Complete OAuth when needed. Organization controls apply. [Consumer installation](https://support.claude.com/en/articles/13837440-use-plugins-in-claude), [referenced package format](https://code.claude.com/docs/en/plugins-reference).

These installation steps cover claude.ai web, Desktop and Cowork connectors. They receive nine tools, omitting `report_checkout_result`, `report_checkout_step` and the deprecated `submit_answer` and `get_merchants`, with no card details or checkout code. ChatGPT receives eight and also omits `list_gift_card_merchants`. Claude Code is a separate connection context and retains the default profile.

For separate installation, add the connector in **Customize → Connectors**, then upload each individual ZIP through **Customize → Skills → + → Create skill → Upload a skill** and enable both. Each ZIP contains one named skill folder. Enable code execution; organization owners may need to allow skills and provision the connector. The [prefilled Envoy connector form](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Envoy&connectorUrl=https%3A%2F%2Fapi.envoy.money%2Fmcp) still requires user review. [Skill setup](https://support.claude.com/en/articles/12512180-use-skills-in-claude), [ZIP structure](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills), [connector setup](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp), [prefill-link contract](https://claude.com/docs/connectors/building/directory-vs-custom).

### ChatGPT

**What Envoy does in ChatGPT.** Envoy checks out on the merchant's website after you approve the purchase in the Envoy app. ChatGPT never receives card details or checkout codes. Provide a delivery address when the purchase requires one. Envoy checks the merchant, amount and available services for each purchase. The same connection restrictions apply in ChatGPT Work.

On eligible web accounts, enable **Settings → Security and login → Developer mode**, then open **Plugins → +**, create a connection using the endpoint above and OAuth, review discovered tools and install the personal MCP plugin. Developer mode is documented for Plus, Pro, Business, Enterprise and Education; workspace policy still applies. [Official quickstart](https://developers.openai.com/plugins/quickstart), [connect and test](https://developers.openai.com/plugins/deploy/connect-chatgpt), [authentication](https://developers.openai.com/plugins/build/auth).

The separate `envoy-payments-plugin-0.4.15.zip` contains `envoy-payments/plugin.json`, `README.md` and both skills. It has no embedded MCP configuration or registered app ID: imported embedded-MCP bundles are Desktop only; app references require a real registered integration. Install through a [desktop local marketplace](#openai-local-marketplace) or [workspace distribution](#openai-workspace-distribution); on web and mobile, personal ZIP import is not a supported install path. MCP creation alone does not install the skills. [Skills by surface](https://learn.chatgpt.com/docs/build-skills), [import limitations](https://learn.chatgpt.com/docs/enterprise/plugin-management).

### ChatGPT Work

For web Work, connect through developer mode above, switch **Chat → Work**, and start a fresh task. Distribute the skills through the workspace route below, then verify both skills and the connection in Work. Local files are not hosted installation evidence; Work access does not expand developer-mode eligibility. [Work quickstart](https://developers.openai.com/plugins/quickstart), [hosted/local distinction](https://learn.chatgpt.com/docs/extend/mcp).

For desktop Work, install the skill bundle through the local marketplace below and verify its independently configured Envoy connection.

### Cursor

Use [Add to Cursor](https://cursor.com/link/mcp/install?name=Envoy&config=eyJ1cmwiOiJodHRwczovL2FwaS5lbnZveS5tb25leS9tY3AifQ%3D%3D) and review the server URL before accepting. Or add Envoy as a global MCP server in `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "Envoy": {
      "url": "https://api.envoy.money/mcp"
    }
  }
}
```

Cursor prompts you to authorize Envoy. Review the connection approval, then check that Cursor discovers the thirteen tools under [Connection](#connection). Call `get_account` for a first read-only check. A real Cursor connection has not been verified here. See Cursor's [MCP configuration](https://docs.cursor.com/context/model-context-protocol) and [install links](https://prod.cursor.com/docs/mcp/install-links).

#### Refresh Cursor tools

Refresh the Envoy MCP server in Cursor or start a fresh Cursor task after changing its configuration. Check that the current thirteen tools appear. A tool refresh does not sign you out or settle an open purchase.

#### Disconnect and remove Cursor

Remove only the Envoy entry from `~/.cursor/mcp.json` when you added it there, or remove the Envoy MCP server in Cursor's MCP settings when you used the install link. Disconnect Envoy separately through [connection removal](https://agent.envoy.money/docs/integrations/disconnect/) to revoke account access. Removing a server entry alone does not revoke consent, cancel a purchase or close a card. Check any purchase in progress before disconnecting.

#### Verify Cursor

In a fresh Cursor task, confirm the server has thirteen tools and ask for a read-only `get_account` call with `{}`. Check that the account reply succeeds. A successful read does not verify checkout or start a purchase.

### OpenAI local marketplace

1. Choose a dedicated local marketplace/repository root. Save [marketplace.json](https://agent.envoy.money/plugins/marketplace.json) as `.agents/plugins/marketplace.json` inside it.
2. Extract `envoy-payments-plugin-0.4.15.zip` into that root's `plugins/` directory. The resulting manifest is `plugins/envoy-payments/plugin.json`; the catalog's `./plugins/envoy-payments` path resolves from the marketplace root.
3. Open the root in desktop Work, restart the app, select the local source in **Plugins Directory**, and install **Envoy Payments**. Start a fresh task and verify both skills and the separately configured connection.

The marketplace is local/private and distinct from the public directory. Do not overwrite an existing personal catalog or edit an installed cache by hand. [Official marketplace installation](https://developers.openai.com/plugins/build/plugins).

### OpenAI workspace distribution

An authorized workspace administrator can choose either documented route:

- After local installation, open **Plugins → Personal → Envoy Payments → … → Publish** and choose workspace roles. This publishes within the workspace only; administrators can disable plugin sharing. [Workspace publication](https://developers.openai.com/plugins/build/plugins#publish-a-local-plugin-to-your-workspace).
- Put the marketplace tree above in a public/private GitHub repository. Open **Admin → Plugins → Add → Import marketplace**, enter the repository URL and optional path/ref, authorize GitHub, then review the import and role policies. [GitHub import](https://learn.chatgpt.com/docs/enterprise/plugin-management).

After role access is granted, open **Plugins → your workspace tab → Envoy Payments → +** to install if needed. Start a fresh ChatGPT/Work task and verify both skills and the separately connected MCP. [Member installation](https://learn.chatgpt.com/docs/plugins). On personal web, use workspace distribution or the desktop local marketplace; there is no personal web skill-install path.

## Upgrade and refresh

Retain the connection owner, authentication and any installation key in designated storage, plus purchase/request references and saved default. None belongs in the package.

- Verify the archive, then **replace the plugin folder, do not overlay it**; stale manifests/instructions must not survive. Refresh/reinstall through host controls and start a fresh task. Keep one copy of each supported skill.
- For Claude organization uploads, a ZIP with the same plugin name replaces the prior version. For GitHub-managed distribution, use the host's sync/update controls. Source changes alone do not prove the installed copy refreshed. [Claude updates](https://support.claude.com/en/articles/13837433-manage-plugins-for-your-organization), [OpenAI imports and sync](https://learn.chatgpt.com/docs/enterprise/plugin-management).
- **Package refresh is not tool-schema refresh.** Use connector discovery/refresh controls, then inspect a fresh task's catalog for the tools expected on that host under [Connection](#connection). ChatGPT developer-mode connections provide **Refresh**. Reconnect only for required authentication/owner/key recovery, revoked access, or an endpoint change the host cannot edit. Upgrading alone requires no reconnect. Claude connector edits require removal/re-addition. [ChatGPT refresh](https://developers.openai.com/plugins/deploy/connect-chatgpt), [Claude edits](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

Do not delete credentials, browser profiles, cookies, IndexedDB keys or connection records as package cleanup. Preserve unresolved purchases across updates and follow the current service recovery action; an upgrade does not start a replacement purchase.

## Removal

| Intent | Existing mechanism |
| --- | --- |
| Remove instructions | Disable/uninstall the plugin or individual skills in the host; remove only the dedicated package source when appropriate. |
| Revoke account access | Separately disconnect/revoke the Envoy connection using its supported controls. Removing skill files is not revocation. |
| Stop an active payment/card | Request `cancel_purchase` only when the current purchase permits it, and observe the returned state. If issuance has started and cancellation is refused, continue the same purchase as instructed. After a report, do not infer new cancellation or payment permission. Plugin removal or disconnection does not prove it stopped. |
| Cancel a merchant order | Use the merchant's cancellation process. Envoy card stop and merchant cancellation are separate outcomes. |

OpenAI documents that a separately connected integration can remain after plugin uninstall. Organization-required plugins may need administrator removal. [Plugin removal](https://learn.chatgpt.com/docs/plugins). Never turn removal into a new payment or authentication workflow.

For a local marketplace, uninstall in the host, remove only the Envoy entry from `.agents/plugins/marketplace.json`, then delete `plugins/envoy-payments/`. Keep unrelated entries and all separate connection/task storage. Removing a source folder alone does not uninstall a host-managed copy.

| Host | Where to remove or disable |
| --- | --- |
| Grok | Review **Marketplace → Your plugins → Manage plugins and skills** in Bot. Exact private-skill deletion UI is not publicly documented; verify removal in a fresh task. Grok.com organization administrators remove connectors through **console.x.ai → team → Grok Business → Connectors → Remove**. [Bot controls](https://docs.x.ai/grok-bot/settings-and-notifications), [admin removal](https://docs.x.ai/grok/connector-management). |
| Claude | Personal skills: **Customize → Skills → skill → … → Delete**. Plugins: manage the installed item in **Customize → Plugins**; organization owners delete managed items under **Organization settings → Plugins**. Connector removal is separate under **Customize → Connectors → Remove/…**. [Skills](https://support.claude.com/en/articles/12512180-use-skills-in-claude), [managed plugins](https://support.claude.com/en/articles/13837433-manage-plugins-for-your-organization), [connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). |
| ChatGPT / Work | Open **Plugins → Installed → Envoy Payments → Uninstall**; separately disconnect the MCP integration if revocation is intended. Managed copies require workspace controls. Removing a Git entry does not delete its imported copy. [Uninstall](https://learn.chatgpt.com/docs/plugins), [managed removal](https://learn.chatgpt.com/docs/enterprise/plugin-management). |

## Verify your installation

On each host you use — Grok, Claude, ChatGPT and ChatGPT Work — confirm, in a fresh task: the installed version, the host's expected catalog (thirteen tools for the default profile; nine when Envoy identifies the connection as Claude; eight for ChatGPT), that the skill is selected (explicitly invoking a skill is not the same as the host selecting it on its own), that your connected account carries over, and that a saved default is recalled.

## Browser agents

An agent that drives a browser can use `https://agent.envoy.money/agent-interactions` without installing a package. Follow the [browser agent guide](https://agent.envoy.money/browser.md), with notes for [Instinct](https://agent.envoy.money/instinct.md) and [Meta Muse](https://agent.envoy.money/muse.md).

Instinct opens `https://agent.envoy.money/agent-interactions/hosts/instinct`. The host-specific path survives dropped query parameters. Envoy retains the declared host through its browser hint, pending sign-in and per-host OAuth client. This label does not verify host identity or grant access.

The agent presses **Connect** and completes sign-in in its own browser. The flow goes through `auth.envoy.money` to `https://envoy.money/agent-login`. The user approves the sign-in in the Envoy app. If that page offers an SMS fallback, follow the current host guide for that sign-in code. This sign-in code is separate from a payment or bank OTP.

Keep the agent's browser profile and cookies between tasks. A saved browser handle does not guarantee that the session remains valid. If the page asks to connect again, complete a fresh sign-in. A temporary service error does not mean the account disconnected. Use **Disconnect** when you intend to revoke access and forget the browser connection. The old `browser.html` pairing does not work with the current tools. Card issuance still depends on the connection's permissions and available services.

### Instinct connection setup

Last updated **25 October 2026**. Connect your existing Envoy account before asking Instinct to make a purchase.

1. Open your chat with Instinct.
2. Copy the setup prompt below into the conversation.
3. Approve the sign-in in the Envoy app when asked.
4. Wait for Instinct to confirm that it can access your Envoy account.

```text
I have an Envoy account and want to connect it so you can help with purchases I approve. Please check what Envoy is and how its browser setup works using https://envoy.money and the current setup guide: https://agent.envoy.money/instinct.md?setup=20261025. Then help me sign in through your browser using my number. I’ll approve the sign-in in the Envoy app. Once connected, confirm that you can access my Envoy account and stop there—don’t start a purchase yet. If a step is blocked, use the guide's connection-report form to report it directly to Envoy. Tell me which step remains blocked and whether the report was queued.
```

The setup guide remains available at [Instinct setup](https://agent.envoy.money/instinct.md).
The `setup=20261025` query marks this prompt revision. It does not guarantee that Instinct refreshes cached instructions.

## Card, checkout code and OTP handling

The payment skill and the server's MCP instructions carry these rules. Envoy delivers only the one-time RuPay card issued for the purchase, never the user's prepaid Visa or other existing Elixir card. At the bank step, fetch the current card using `get_purchase_status`. Its `checkout_code` may be used only for the matching card's payment verification. Read the code's expiry when supplied. If it expires before payment submission, fetch status again for the same purchase and proceed only when ready. After a payment attempt, report the outcome and follow status; uncertainty stops another payment. An `enter_otp` step for the user happens only in the Envoy app; no Envoy tool accepts a payment or bank OTP. A merchant login code goes to Envoy only when Envoy's question asks for it: the user types it, and the agent sends it once with `submit_answer` and never keeps it. Envoy never asks for a merchant password, and no agent passes one through chat on any host. On agent checkout, `checkout_code` is the matching card's OTP: when the bank page asks for a code or OTP, enter it there once. The bank sends the user no code for this card, so never ask the user for one. If the bank rejects it, do not retry; report `failed` with `failure_reason: otp_failed` and follow Envoy's next instruction. Never retain the code in replies, files, logs, memory, reports or feedback.

Every MCP tool result carries an English briefing followed by slim JSON in one text item. Structured content contains the same slim object. While a purchase is ready, its purchase-specific card appears in `card`; the briefing never contains card values. See [MCP results](https://agent.envoy.money/docs/mcp/results/) for the exact format. There is no separate per-user text opt-in. Verified host identity, protected transport, purchase/card identity and fresh authority still control release. Host history may retain that text. Amount funding limits value but does not enforce merchant locking or true single use. Provider blocking is asynchronous, with no guaranteed immediate block after use or exact-time deactivation.