Migrate from contract 1
Move an integration from the retired contract 1 tools to the tools of envoy@2026-10.
Contract 1 is retired. Its routes under /v1/ and its MCP endpoint /contracts/1/mcp no longer work. Move every client to envoy@2026-10. The new contract has thirteen tools.
Do these steps
- Point MCP hosts at
https://api.envoy.money/mcp. Rediscover the tools, because a host can cache the old catalog. - Point REST clients at
POST /tools/:tool. Remove/v1/from every path. - Replace each old tool call with the tool in the table below.
- Stop calling
get_instructions. Follow thenextfield in each reply instead. - Install skills
0.4.15. Skills0.3.4teach contract 1 and do not work. See the installation guide.
Tool mapping
| Contract 1 | Now |
|---|---|
get_account | get_account. Choose sections with include: balance, limits, services, active_purchase, agent, profile, addresses. |
get_user_info | get_account with include set to profile. It returns only a verified mobile number and email. |
list_delivery_addresses | get_account with include set to addresses. Pass the address id as address_id to start_purchase. Saved addresses are not available yet, so the reply lists addresses under unavailable. Send the address as one line instead. |
list_transactions | list_transactions. Use from, to, limit and cursor. |
request_virtual_card (new card) | start_purchase. Send idempotency_key, merchant_url, total, items and user_request. |
request_virtual_card with action: "stop" | cancel_purchase. |
get_purchase_status | get_purchase_status. Use purchase, after_revision and wait_seconds. |
report_checkout_outcome | report_checkout_result. Set outcome to paid or failed. The service rejects unsure with INVALID_INPUT and records nothing. If you can't tell whether payment completed, report failed with failure_reason: other. |
submit_feedback | submit_answer with type feedback. Send the feedback text as answer, with an optional rating from 1 to 5 and a required idempotency_key. |
get_instructions | Removed. Follow next. |
start_operated_purchase, get_operated_purchase_status, provide_purchase_input | Removed. Call start_purchase. When Envoy asks a question in purchase.question, send the user's reply with submit_answer. |
The two new tools are start_purchase and submit_answer. A purchase now starts in one call. Envoy asks the user for anything it needs in purchase.question, and submit_answer sends the reply.
What changes in replies
- MCP replies are briefings. A briefing is English text, then one line of JSON. Read
situation,nextandretry. Error codes, states and ids do not reach the MCP agent. Quote thesupport_refto support if you need help. - REST replies keep the full envelope. It has
next.action,error.code, reason codes andpurchase.state. - Follow
next. Passnext.argsunchanged tonext.tool.
Check your work
- Call
get_account. Confirm the reply lists theservicesyou expect. - Run a purchase end to end and follow
nextat each step. - Read the changelog for breaking changes.