# Payrail Agent

Payrail Agent gives AI agents a secure Payrail Agent Card, Memory, approval, and checkout layer for real purchases while keeping sensitive data and final payment approval under user control.

Use the exact public names **Payrail Agent** for the platform and **Payrail Agent Card** for its payment tool in replies, confirmation labels, and top-up guidance. Keep both spellings intact; do not shorten or respell them.

Complete setup when asked; a repeated prompt does not request a reinstall or another sign-in. Discover current-task tools first, preserve a correct installation, and authenticate its remote Payrail Agent MCP only when needed. Then verify readiness or give the observed phase and next action.

Normal path: **discover → install if absent → sign in if needed → verify here**. Installation, activation, OAuth, and readiness are separate. For missing tools after successful sign-in, follow the host recovery under Connect. Do not ask the user to repeat the setup prompt.

Keep setup messages concise: describe the next user action and the verified result. During routine setup, keep environment checks, staging/development references, plugin/catalog IDs, version numbers, and build revisions out of user-facing narration. Use those details internally to select and verify the requested connection. Preserve any exact endpoint required by the host's native confirmation. If blocked, explain the failed phase (installation, sign-in, tool loading, or readiness), the observed problem, and the next action in plain language. Include technical identifiers only when the user explicitly asks for troubleshooting details; never expose credentials or account identifiers.

Missing tools do not establish installation or auth state; inspect before acting. Install/Add is only for confirmed absence. A service failure is not evidence that the plugin is absent.

When authentication is needed, start one browser OAuth flow for both account verification and MCP authorization. That same flow collects the email and OTP, grants MCP access, and redirects to the host. Reuse a valid existing connection; do not start OAuth just because tools are missing.

Do not ask the user to send an email or OTP in chat, and do not run a separate Payrail Agent account setup or login flow.

Existing production connections may use `https://payrail-agent-chatgpt-app-prod.onrender.com/mcp`, the supported legacy alias of this same production service. Accept that exact alias when checking an existing connection against the endpoint below; preserve its installation and authorization. It is not staging or a channel mismatch. Use the new bundled endpoint for fresh installations. Do not rewrite an existing connection or repeat sign-in solely to change its URL.

# Explain and connect

For a first-time setup that needs OAuth, explain: "Payrail Agent is a payment method redesigned for AI agents. It gives me a secure way to prepare payments, top up Payrail Agent Card, and request approvals while keeping sensitive payment details out of chat."

When OAuth is needed, describe the actual next host action: say you will open a secure Payrail Agent window only if you can initiate it; otherwise try the host tool-triggered connection prompt below before naming a manual fallback. An absent Connect tool alone does not require manual setup. Tell the user to enter email and OTP only in that window, not in chat. Verify host-reported authorization before readiness; a closing window is not completion.

# Install

Install exactly one `payrailAgent` plugin for the current host through that host's own plugin manager. Use only the actions in the block for the host you are running in.

- Codex: First discover current-task Payrail Agent tools, including deferred tools. When get_payrail_agent_capabilities is callable, verify the requested environment and authenticated readiness without requiring a separate inventory action. Otherwise inspect native plugin inventory and the bundled connection; if native inventory is unavailable, use the existing host's `codex plugin list --json` and `codex plugin marketplace list --json` when permitted. Preserve a correct installed plugin and authorization. Missing inventory access does not erase a confirmed installation or completed OAuth; reuse that evidence for catalog recovery. Missing marketplace snapshot: if inventory reports that a configured marketplace root does not contain a supported manifest, repair the catalog before the unknown-state handoff. This error does not prove plugin absence. Read only the reported marketplace entries and their source_type, source, and ref fields in the current host configuration; do not dump configuration or read credentials. For `payrail-skills`, require the Git source `https://github.com/payrail-one/agent.git` at ref `main`; for `payrail-skills-staging`, require that same source at ref `staging`. When the reported root directory is absent and its source matches, restore that snapshot once with `codex plugin marketplace add payrail-one/agent --ref main` or `codex plugin marketplace add payrail-one/agent --ref staging`, respectively. Restore only the verified missing snapshots named in the error. The staging snapshot can block production inventory too: the marketplace filter does not bypass other broken snapshots. Restoring its existing source is catalog repair, not a channel switch or plugin installation. Use same-source add for this absent-directory repair; marketplace upgrade can refresh installed plugin versions. Do not remove sources, clear caches, edit configuration, or repeat OAuth. If a root exists but is invalid, a source differs, or repair fails or is denied, report that specific blocker without trying another repair route. After successful repair, rerun both inventories once, preserve any installed plugin and completed sign-in, and install only if absence is then confirmed. Continue the requested channel setup and its same-chat initial sign-in rule; catalog repair alone is not setup completion. Installation integrity: installed means the selected bundle is present and loadable, not merely a configuration entry or an installed/enabled label. When tools are unavailable, check the exact plugin for host-reported load errors. If needed, inspect only its host-reported installed root, plugin manifest, declared skill path, and bundled MCP declaration; a marketplace source directory is not the installed bundle. Do not read credentials or scan unrelated caches. A current missing-cache or invalid-bundle error, or verified missing or corrupt bundle files, overrides an earlier installation-success report. After verifying the same selector, marketplace source, and channel, restore that missing or broken bundle once through an eligible native Install action or the same supported install command below. These install commands also apply to this verified repair case. Do not uninstall, disconnect, clear caches, or edit host configuration to repair it. Preserve completed sign-in; restoring plugin files does not require another OAuth flow. Recheck the reported installed root and load result, then continue catalog recovery. If repair is denied, fails, or leaves the bundle unloadable, report that blocker without another repair route. Unknown installation state, missing tools alone, or a newer available version does not justify repair. Only if neither inventory route is available and state has not otherwise been established, state is unknown: hand off **Plugins → Payrail Agent** to inspect details; Install only if absence is confirmed; do not invent a Connect button. Missing tools do not prove absence. Use an eligible native install action when exposed; supported command alternatives for the requested channel follow below. If neither installation route is available, hand off **Plugins → Payrail Agent → Install**. Use the same local host and configuration scope; do not change profiles or install/upgrade a CLI, hunt for app-bundled binaries, or launch a private App Server client. Codex's own plugin and OAuth commands are not the retired Payrail Agent CLI. OAuth remains host-managed; use the bounded Connect flow below. Do not automate Codex's own UI. A denied install or host approval is a stop, not a reason to change tools or permissions. When production installation is needed after promotion, prefer an eligible native Install action when exposed. Otherwise the agent may run the existing supported host plugin commands: register a missing source with `codex plugin marketplace add payrail-one/agent --ref main`. If already registered, verify `payrail-skills` is `payrail-one/agent` at ref `main` before refreshing only that source when needed with `codex plugin marketplace upgrade payrail-skills`. Install only the absent plugin with `codex plugin add payrailAgent@payrail-one-skills`. Public-directory listing is not required. Preserve a correct installed version even if a newer release exists; stop on a source/channel mismatch. Production setup does not authorize switching or duplicating an existing development installation; preserve it and report the channel mismatch. A missing or unsupported command is a host limitation, not a reason to install another executable. A successful command is not desktop activation, OAuth, or readiness.
- Claude Code: First discover current-task Payrail Agent tools, including deferred tools. When `get_payrail_agent_capabilities` is callable, verify the requested environment and authenticated readiness without requiring separate inventory. An auth challenge goes to Connect; a service failure is not proof of absence. Otherwise inspect `claude plugin list --json` and `claude plugin marketplace list --json` in the same host and configuration scope. Preserve an already-correct installation and authorization, including a supported older version. If inventory is unavailable, state is unknown: hand off `/plugin` to inspect details; Install only if absent, Authenticate only when needed. Report existing duplicates; do not remove them automatically or create another connection. Use existing supported host commands; if unavailable, hand off the native control instead of installing another CLI. A denied host action stops the attempt; do not switch routes to bypass it. When production installation is needed after promotion, verify any existing `payrail-skills` source is the stable `payrail-one/agent` marketplace; stop on a source/channel mismatch. Register only a missing source with `claude plugin marketplace add payrail-one/agent`, then install only the absent plugin with `claude plugin install payrailAgent@payrail-one-skills`. Check the in-session install summary: if active, continue; after a shell install or an activation-required summary, the user enters `/reload-plugins` in this same conversation before `/mcp` can authenticate the new server. If reload stops with a prompt-cache warning, explain the cost of re-reading the conversation; the user may accept it with `/reload-plugins --force`. Install success is not authentication or same-session readiness.
- OpenClaw: install the native plugin `payrailAgent` from the host's configured plugin marketplace.
- Grok Build: install the native plugin `payrailAgent` from the host's configured plugin marketplace.
- Grok Bot: Verify the actual MCP URL in the selected catalog entry, existing connector, or native Add request against this guide's endpoint before authentication. A matching name, logo, or tool count does not establish the channel; a production setup prompt does not turn an existing development connector into production. If the catalog URL is wrong or unavailable, do not install or authenticate that unverified channel. For a fresh setup with confirmed connector absence, use the host's supported native custom remote MCP Add action with the exact endpoint from the requested guide. The setup prompt already selects production or development: initiate that native Add/Connect flow without a separate how-to-connect choice. Keep the host's required confirmation, including a question widget when required, and secure OAuth steps; confirm the exact action rather than offering an unverified listing anyway. If custom remote Add is unavailable, report that specific host limitation instead of inventing an action or asking the user to choose an unknown channel. An ordinary setup prompt does not request switching or duplicating an existing connection; preserve it until the user explicitly requests a channel change. Preserve a correct installed connector and authorization. If inventory is unavailable, state is unknown: inspect or hand off **Settings → Plugins → Payrail Agent**; choose Connect if installed and sign-in is needed, or Add only if absent. Missing tools do not prove absence. When installation is needed, use the native Payrail Agent **Add** card for the requested channel; manual fallback: **Settings → Plugins → Payrail Agent → Add**. Use a custom remote entry only when supported by the host, with the exact endpoint below, and no correct installed connection exists. If the channel is unavailable, report it; do not add a duplicate connection or infer OAuth client identity from a generic account label. A connector adds tools only; Payrail Agent guidance is the skill, which a catalog listing bundles and a custom remote connection does not. After a custom remote Add, also install the skill: copy the `skills/payrailAgent` folder from https://github.com/payrail-one/agent at branch `main` into the workspace `skills/payrailAgent` directory (or `~/.cursor/plugins/local/payrailAgent/skills/`), then read its SKILL.md before the first Payrail Agent task. Without the installed skill, do not fill forms or checkouts from setup-guide memory.
- Hermes and other hosts: import the bundled skill and add the remote MCP through the host's native MCP settings with OAuth.
- The plugin bundles the skill and remote MCP declaration. Do not install or invoke a Payrail Agent CLI, package installer, or local Payrail Agent server.
- Any previously installed Payrail Agent CLI is an abandoned path. Ignore it for setup, login, verification, and recovery; do not execute or upgrade it. Its presence does not establish a connection.
- A successful plugin command proves its reported local installation only, not activation in this running app, OAuth completion, or readiness. Continue through native activation/Connect and actual tool calls below.

# Connect

Use the plugin's bundled `https://mcp.payrail.one/mcp` remote Streamable HTTP MCP server. Reuse its valid authorization, or complete one host-managed browser OAuth flow when needed.

Inspect the exact installed `payrailAgent` connection and activate a cold install when required by the host. Start Connect when sign-in is needed or explicitly requested; keep email, OTP, codes, and tokens in the secure browser flow. Follow the matching host actions:

A canceled or denied action stops this attempt; do not retry through another route. Report any cancellation, failure, or deadline at the phase it occurred, without automatically reopening sign-in or reinstalling.

- Codex: Requested sign-in: when the user explicitly asks to open the Payrail Agent login window, sign in again, or reconnect, start one host-managed OAuth attempt for the exact installed Payrail Agent connection in this same chat, even when inventory reports `o_auth`. This explicit request supplies the sign-in requirement for the native action or supported Codex command below; do not require a failed tool call first or send the user to Settings while that route is available. Reuse an already pending login; do not open a second flow. A repeated setup prompt alone is not an explicit sign-in request: preserve working authorization. A canceled or denied action stops the current attempt; never restart it automatically. Apply each host policy to its exact host and connection scope; an unrelated connector restriction does not prohibit Payrail Agent login. Initial sign-in: if tools are unavailable after discovery and you just installed the exact plugin during this authorized setup and have no evidence of a completed sign-in or a working authenticated connection, start one host-managed OAuth attempt in this installation chat using the eligible native action or supported Codex command below. Do not wait for missing tools to request authentication. The inventory value `unknown` means undetermined, not an authentication rejection; it does not block this first sign-in or require a Settings/new-chat handoff. A cached `o_auth` inventory label alone does not establish either and must not skip initial login after confirmed plugin absence. A plugin install does not itself complete OAuth. Check for a pending login first and wait for that same attempt; a canceled, denied, or failed login must not be restarted. Preserve completed authorization confirmed by the user or host and use authenticated tools or catalog recovery; unknown or missing tools alone never justify repeating OAuth. A reported network/service failure keeps its own recovery path. Keep the one login process attached until host-reported completion or failure, then discover tools and verify readiness here. Reuse existing authorization. When callable, call `get_payrail_agent_capabilities` once through the current task's Payrail Agent tool; its `mcp/www_authenticate` result lets the host show the native MCP connection prompt. A separate Connect tool is not required. Let the user approve and enter email and OTP in the secure window. If the prompt is pending, wait without starting another flow. Never reproduce that MCP call with curl, a shell client, or private RPC. When tools are unavailable, inspect supported host connection state: `failureReason=reauthenticationRequired` is an authentication failure, not a catalog activation failure. A current OAuth invalid_grant rejection for that exact connection also requires authentication recovery. The inventory label `o_auth` is saved OAuth metadata, not proof of accepted authentication or readiness. A tool-result prompt cannot recover a server that failed before initialization. For initial sign-in or when the exact installed connection requires sign-in, try one eligible native Connect action (Authenticate) if exposed for that existing server in the same host and configuration scope. Reuse a pending login and wait; do not open another prompt. If no eligible native action is exposed and host policy permits the command, for initial sign-in or when the exact installed connection requires sign-in, check `codex --version` and run `codex mcp login payrailAgent` once in the same host/configuration scope. Require Codex 0.147.0 or newer; older, unknown, or unsupported commands are a host limitation. Keep the command restrictions under Install: do not install/upgrade a CLI or hunt for another binary. This supported Codex command launches host-managed OAuth. The bans on the retired Payrail Agent CLI and raw shell MCP clients do not prohibit it. Missing native controls do not establish a policy denial. Apply current instructions and observed host decisions; historical notes do not establish a current restriction. If a policy blocks the fallback, identify the applicable source or observed denial without exposing private instructions; do not invent a session-policy prohibition. Denial or cancellation of the current login attempt stops that attempt; never switch routes to bypass it. A restriction limited to agent commands may still permit the documented manual native handoff. Missing tools alone do not establish that sign-in is required. Let Codex open its secure browser; if handoff is needed, use the exact host-issued URL. Capture command output without echoing it; report only sanitized completion or error status. Keep OAuth URLs out of transcript output; never reconstruct callbacks, relay parameters, or handle credentials. When either initial sign-in or an observed authentication requirement applies, and neither an eligible native action nor a permitted host command is available, report the observed limit and hand off **Settings → MCP servers → payrailAgent → Authenticate** for the existing connection. This is a user-operated native control, not an agent-callable action. Documented App Server methods are host integration interfaces, not callable model tools; do not use private RPC, a second server, or UI automation to bridge that gap. Wait for host completion without asking the user to confirm it in chat; an open sign-in screen is not completed authentication. Reauthentication is not payment approval: continue an interrupted payment only through its exact backend-owned operation and required approval. A network or auth-service failure keeps its own retryable error; do not reset credentials or use a new task to repair it. Pending startup: only when the exact host connection reports loading or initializing, or an omitted pending optional MCP server, and no authentication or service failure is present, give that existing startup one bounded opportunity to finish before rediscovering tools once. Use a supported host completion/status wait within its startup deadline, or the next sampling turn when that is the available refresh boundary; do not invent a wait API, add blind sleeps, or poll indefinitely. If the host supports explicit plugin selection, select the existing Payrail Agent plugin; when this needs user action, ask them to attach Payrail Agent with `@` in this chat. Selection can make the host wait for its startup, but is not installation or authentication. Do not change startup timeouts or required-server settings. If startup remains pending, report loading as pending; if it fails, handle that specific failure. Missing tools alone do not establish pending startup and never justify repeated OAuth. Catalog refresh: use current-task deferred tool discovery first; if capabilities is callable, finish readiness here and do not suggest a new chat. Only when an actual lookup cannot discover or call the required tools, inspect the installed/enabled state and host auth/service errors; missing tools alone do not identify the cause. If a supported reload action is actually callable, use it once and probe when applied; otherwise continue directly to recovery. When the correct plugin is loadable and enabled, OAuth completed, startup is no longer pending, and tools remain unavailable without a separate observed auth or service error, give one new-chat handoff: "Payrail Agent is installed and signed in, but its tools aren't available in this chat. Open a new Codex chat and send: Verify my Payrail Agent production connection. I already installed and signed in, then opened this new chat because the tools were missing. Keep the existing installation and sign-in; no setup steps need repeating." Use the requested environment in the product name. Keep the recovery cue; if the user is already in that new chat and tools remain unavailable, recheck the exact failure and apply Stale activation only when its evidence requirements are met. Unknown installation/auth state or pending, canceled, denied, or failed OAuth does not qualify for this handoff. Handle actual auth/service errors separately. The new chat reuses installation and authorization, then verifies capabilities, authenticated status, and balance. This is activation recovery, not automatic single-prompt completion. Include a retained non-sensitive user intent when useful, but never imply that conversation history, credentials, or payment approvals carry over. Do not invent an API or automate Codex's UI. Stale activation: a full app restart is a conditional last step, not a requirement for every install. Only after the exact bundle is loadable and enabled, sign-in completed, available native reload and one new-chat recovery have been attempted, and the host still reports an old missing-bundle error for verified repaired files or explicitly requests a restart, ask the user to quit and reopen Codex once. Preserve the installation and sign-in, carry the recovery cue that a restart was already attempted, and verify capabilities, authenticated status, and balance afterward. Never quit the app through automation or repeat this restart. An authentication rejection, service failure, startup still pending, or unexplained tool absence does not qualify. Without that stale-host evidence, report tool loading blocked without suggesting another chat, reinstall, restart, or sign-in.
- Claude Code: The connection is `plugin:payrailAgent:payrailAgent`. This host has no model-triggered sign-in: no tool, hook, or agent shell can open the Payrail Agent window, and `claude mcp login plugin:payrailAgent:payrailAgent` needs a real interactive terminal, so do not create a PTY workaround and do not send the user to a terminal. After any required install activation, reuse authorization. When sign-in is needed, give the user exactly one action and nothing else: run `/mcp`, select `payrailAgent`, choose Authenticate, and enter email and code only in the secure Payrail Agent window that opens from there; say you will verify readiness right after. Manual handoff: **/mcp → payrailAgent → Authenticate**. Catalog refresh: sign-in needs no reload, because the tools are available on the next request; after completed OAuth, discover `get_payrail_agent_capabilities` in this session first. Only if tools remain unavailable after host-reported authorization, the user runs `/reload-plugins` in this same conversation, following the cache-warning rule under Install, then retry discovery. This is a user command, not a shell or model reload API. Reconnect only for an observed connection failure. Do not launch a separate `claude -p` probe or treat its account login as the plugin OAuth result; report the remaining phase if recovery fails. A user reload is same-chat recovery, not automatic single-prompt completion.
- OpenClaw: `openclaw mcp login payrailAgent`. Manual handoff: run that command. Catalog refresh: `openclaw mcp reload`, then a Gateway configuration publish or process restart if tools still do not appear; verify with `openclaw mcp doctor --probe`.
- Hermes: `hermes mcp login payrailAgent` from a trusted local terminal; a gateway chat cannot complete it. Manual handoff: run that command. Catalog refresh: `/reload-mcp`.
- Grok Build: open `/mcps`, select `payrailAgent`, and authenticate; the host registers itself as `Grok` with a loopback redirect and stores tokens in `~/.grok/mcp_credentials.json`, which you never read. Manual handoff: **/mcps → payrailAgent → Authenticate**. Catalog refresh: reopen `/mcps`; if the tools still do not appear, the plugin was installed outside this running app, so ask the user to quit Grok Build completely and reopen it.
- Grok Bot: use native **Connect** only when authentication is needed; reuse the account-wide connection. Let the host complete browser OAuth and return to the original chat. Manual handoff: **Settings → Plugins → Payrail Agent → Connect**. If Connect shows `Retry`, reports `unreachable`, or returns a registration/authentication error before the window opens, inspect the connector details and report connection startup failed; do not describe a failed card as a pending email/OTP prompt; the label alone does not identify a host, service, or email/OTP defect. For a developer handoff, collect the app version, UTC attempt time, endpoint origin/path, and HTTP status or DNS/TLS/timeout error and request ID when available; omit credentials and callback query values. Reachability from another machine does not verify this connector route. Catalog refresh: discover `get_payrail_agent_capabilities` in that chat first. Only if connector attachment is needed, have the user type `@` and attach Payrail Agent here, then retry discovery; this is manual same-chat recovery, not automatic setup. For an observed connection failure, inspect the connector details and follow the required authentication action. Missing tools alone do not justify a new Bot task, app restart, or repeated OAuth. Do not reset the Bot computer for an unexplained connector failure. Do not infer a Bot OAuth identity or callback from generic Cursor metadata.

Do not tell the user that a fresh task or session will open OAuth. If neither the supported native action nor its permitted host command can initiate the connection, follow the host-specific blocked path above; give a manual handoff only when one is documented.

A successful authenticated Payrail Agent tool call is the only evidence of a usable connection. Installation and a host-reported OAuth completion are separate facts, not setup success. If sign-in completed but tools are unavailable, report exactly that; do not call the account disconnected or repeat login. A browser window opening or a command exiting zero is not readiness.

After OAuth completes, first probe the current task's callable catalog, including host-native deferred or lazy discovery, for `get_payrail_agent_capabilities`. A tool omitted from the initial visible list is not evidence that it is unavailable. If the call succeeds, continue readiness and the retained request in the same task. If discovery or the call fails, follow the host-specific recovery for the observed failure. Do not repeat OAuth without an authentication challenge, install a Payrail Agent CLI, start a local MCP server, or copy a token.

Call `get_payrail_agent_capabilities`. Require `kind === "capabilities"`, `setupState === "ready"`, `executionModes` to include `client_browser`, `sessionAuthority === "remote_database"`, and `browserPaymentRun.status === "ready"` with `executionMode === "agent_direct"`. Follow any blocked `setupState`, `nextAction`, and `instructions` instead of claiming readiness. Offer x402 and crypto only when their respective rail status is ready. The built-in browser is the only browser-payment execution path.

After capabilities report ready, call `get_payrail_agent_status`. Require `get_payrail_agent_status.outcome === "ready"`. Then silently call `get_payment_balance` without an asset selector; do not call `show_payment_balance` or a retired card-balance tool for this setup read.

For a funded balance, say: "**Payrail Agent is ready.** Your available balance is **{formatted balance}**. Your payment credentials stay protected and out of chat, and spending stays subject to your Payrail Agent approval rules." If all three rails are ready, continue: "Give it a try—send USDT or USDC, pay with x402, or ask me to buy something online." Otherwise offer only actions backed by ready rail-specific capabilities.

For an exact zero balance, keep the same heading, exact formatted balance, and credential/approval reassurance, then say: "Add funds to start using Payrail Agent, or ask me to top up your Payrail Agent Card." Do not create a top-up link or widget unless the user asks or the workflow returns `funding_required`.

If the balance is unavailable or malformed, say: "**Payrail Agent is ready.** I couldn’t read your available balance right now. Your payment credentials stay protected and out of chat, and spending stays subject to your Payrail Agent approval rules." Never infer zero or invent an amount or currency.

Continue the original request without asking the user to repeat it only when this same task retained it. In a fresh task, act only on the fresh task’s request and do not claim that prior task context carried over. Do not repeat onboarding in later already-connected tasks.