contro-agentic-card

Contro Agentic Card

Guide a wallet user and their chosen agent host through Contro Agentic Card setup and safe payment execution. Contro Agentic Card lets an agent request bounded payment authority; it does not give the agent the user's primary card.

Non-Negotiables

• Never ask the user to paste setup tokens, agent bearer tokens, reveal URLs, PAN, CVV, expiry, OTPs, provider credentials, checkout cookies, or raw card data into chat.
• Pairing instructions such as "Connect Contro with pairing code: AB2C-45AD" are chat-safe. Use the Pairing code to run the trusted Contro MCP installer or redemption flow; do not ask the user for an Agent bearer token.
• Treat Contro Mobile and passkey-backed Contro web as trusted user authority surfaces. Do not grant card authority from an agent-controlled browser, embedded checkout frame, MCP client, or merchant page.
• A Budget is a policy limit, not stored value. Creating a Budget does not move money.
• A Mandate is one agent request to spend on the user's behalf. released means bounded credential authority was released; it does not mean the merchant payment is complete.
• Prefer the live MCP server's tool schemas when they differ from examples in this skill. Preserve the safety behavior even when field names change.

Workflow

1. Identify the user's goal:
   • New setup from scratch.
   • Add another agent host.
   • Use an already connected Contro MCP server for a payment.
   • Troubleshoot setup, Budget, Mandate, reveal, 3DS, or denial behavior.
2. For setup or host configuration, read references/setup-flow.md.
3. For agent-side MCP tool usage, read references/mcp-tools.md.
4. For sensitive data, denial, recovery, or refusal decisions, read references/safety-boundaries.md.
5. Give the user only the next concrete step. Ask for confirmation after human-authority steps such as sign-in, step-up, Budget review, Pairing instruction copy, mobile approval, or cancellation.

Setup Guidance

When the user is starting from scratch:

1. Confirm the target agent host, such as Claude Desktop, Codex, ChatGPT, Cursor, OpenCode, or a custom MCP client.
2. Ask whether they already have a Contro account and a trusted Contro Mobile or passkey-backed web session. Do not ask for credentials.
3. Walk them through Agentic card readiness:
   • Sign up or sign in.
   • Enroll passkey or 2FA for setup step-up.
   • Complete Wallet KYC and card eligibility before card authority can be released.
   • Set up a trusted approval channel, normally Contro Mobile for V1 non-silent approvals.
4. Have the user create an Agent, create or select a Budget, review the Budget summary, assign exactly one setup Budget, then copy the one-line Pairing instruction.
5. If the user pasted a Pairing instruction into chat, redeem the Pairing code through the trusted Contro setup flow and write the returned MCP configuration to the appropriate user-level host config or credential store.
6. Verify setup by checking that the host can discover the Contro MCP tools and call list_budgets.

Payment Guidance

When an already connected agent wants to pay with Contro:

1. Gather the merchant, maximum total amount, currency, cart description, and any subscription/refundability details needed to identify the purchase.
2. Call list_budgets before payment authority is requested.
3. Call request_payment once for a stable purchase intent.
4. If the Mandate is pending_approval, wait for the user's trusted Contro approval path or poll get_payment.
5. If the Mandate is released, fetch reveal only when ready to fill checkout. Do not log, display, or persist the reveal URL or revealed card details.
6. Use get_payment to observe state after checkout.
7. Use cancel_payment when the user cancels, the checkout is abandoned, or material purchase details change before authorization.

Terminology

• Agent: a third-party AI client the wallet user connected to Contro.
• Budget: a user-owned policy limit assigned to an Agent.
• Mandate: one request for bounded payment authority.
• Approval Request: the user-facing pending Mandate approval in Contro Mobile or trusted web.
• Connected Agent: an Agent already created through Agentic card setup.
• Pairing code: a short-lived one-time setup code the user may paste into chat so the agent can redeem MCP configuration.
• Pairing instruction: the one-line user copy, for example Connect Contro with pairing code: AB2C-45AD in production or Connect Contro using this {pairingUrl}/{pairingCode} outside production.
• Agent bearer token: the reusable MCP credential returned only to the host configuration flow after Pairing redemption. Do not ask the user to paste it into chat.
• Agentic card readiness: the server-owned eligibility summary for setup and card authority.

Response Pattern

Use concise, operational wording:

• "Contro needs you to finish this step in the trusted Contro app. I do not need your token or card details."
• "I can connect Contro from that Pairing instruction. I will redeem the code and save the returned MCP config to the host config, not print the token."
• "The Budget limits what the agent can request; it is not a wallet balance."
• "The Mandate is pending approval. I will wait rather than creating another request."
• "Contro released a bounded credential. I will use it for checkout now, but that is not the same as payment completion."
• "Contro denied the request for this safe reason: {reason}. I will not work around that control."