DevelopersMCP · OAuth 2.1 · one money tool

Money your agent can use.

One MCP tool for money. Your agent says what the person wants, in their words; Genie picks the rail, checks the rules its owner set and reports what happened. Banks, cards, Coinbase and x402. No API keys.

claude mcp add --transport http genie https://genie.paymanai.com/mcp

Or paste https://genie.paymanai.com/mcp into any MCP host.

ask_genie genie-mcp

tools/call ask_genie

{
  "request": "Pay the $84 invoice from Acme",
  "context": "Invoice 1042, due Friday"
}

status done

{
  "status": "done",
  "message": "Paid $84.00 to Acme Supply from Everyday Checking. Record GN-20A7.",
  "conversation": "cnv_01j9k3"
}

Decision recordGN-20A7

instructionpay $84.00 → Acme Supplyfrom your agent · 10:41:02
policyper_payment 2,000 · daily 2,500 · monthly 5,000within limits · payee approved by the owner
budgetreserved 84.003,676.00 left this month
sentEveryday Checking ····4821bank confirmed · 10:41:03
recordwrittenAccount → Activity

Quickstart

Four steps to a first call

01
An account with money behind it
Create a Genie account, connect a rail under Accounts (Plaid, Link, Coinbase, a bank) and set limits under Policies. Genie only ever acts inside those.
02
Add the server to your host
claude mcp add --transport http genie https://genie.paymanai.com/mcp, or paste https://genie.paymanai.com/mcp wherever your host takes a remote MCP server. A host that only launches local servers uses the stdio bridge.
03
Sign in once
The first call answers 401 with OAuth resource metadata. A compliant client registers itself, opens Genie’s sign-in page and comes back with a token. Nothing to paste.
04
Call ask_genie with the person’s words
ask_genie({ request: "How much is in checking?" }). Read status; never fill in a payment form or pick an account yourself.

HTTP assistants

Give your assistant one instruction.

For assistants with HTTP access, browser sign-in and a secure vault. Copy this instruction into your assistant, then sign in to Genie and choose what it can access. The guide checks compatibility first.

Read the HTTP integration guide · Muse · Instinct · Grok Bot

The contract

One money tool, five outcomes

status	Genie	Your agent
`done`	Answered or acted. The message says what happened.	Relay it. It does not prove payment settlement or order completion.
`needs_input`	Genie needs something from the person.	Put the message to them; call again with their answer and the same conversation.
`needs_approval`	The owner approves in their Genie account.	Stop and say so. The approval never happens in your chat.
`refused`	Outside the rules the owner set.	Relay the reason. Do not rephrase to get around it.
`error`	The turn failed.	Read outcome: retry after NOTHING_RAN or BUSY, never after OUTCOME_UNKNOWN.

Endpoint: https://genie.paymanai.com/mcp, MCP Streamable HTTP. Server name genie-mcp.
Tools: One tool for money: ask_genie. Input request (what the person wants, in their words), optional context and conversation. Output status and message. Helper tools for the assistant’s own access, with scope genie:self: get_genie_agent, rename_genie_agent, grant_genie_read_access and request_genie_access. After a Link purchase, attach_purchase_confirmation uploads the merchant’s confirmation.
Sign-in: OAuth 2.1, authorization code with PKCE (S256), public client. Scopes genie:ask and genie:self. Discovery: https://genie.paymanai.com/.well-known/oauth-protected-resource names the authorization server; its metadata names the authorize, token, revocation and registration endpoints. Register automatically with your exact redirect URIs and token_endpoint_auth_method: none; no client secret is needed. Access tokens last an hour.
Stay signed in: Include authorization_code and refresh_token in your registration’s grant_types to receive a refresh token. Use the newest token after each refresh; tokens rotate, expire after 90 days without use, and can be revoked.
Native clients: A preregistered native client such as the stdio bridge may redirect to http://127.0.0.1 on any port and receives a refresh token. Dynamically registered clients use their exact registered redirect URIs. Replaying a rotated-out refresh token revokes its refresh family. An already issued access token may remain valid until its one-hour expiry.
Rails: Whatever the person has connected: banks through Plaid, cards through their Link wallet, Coinbase for crypto and stablecoins, and x402 for machine payments. Genie picks the account and rail from the request and the person’s rules; your agent never does.
Unauthenticated calls: Return 401 with WWW-Authenticate: Bearer resource_metadata="…", scope="genie:ask genie:self", so a compliant MCP client starts sign-in on its own.

Hosts

Where people already talk to Genie

Each of these connects with the same URL and sign-in, no code. The guide for each has the exact form values, or the one message to send.

Stdio hosts

A host that only runs local MCP servers

For a host configured to launch local stdio MCP servers, @paymanai/genie-mcp-stdio is a small local bridge: stdio to the host, Streamable HTTP to Genie. One server entry, no secrets in the host’s config.

{
  "mcpServers": {
    "genie": {
      "command": "npx",
      "args": ["-y", "@paymanai/genie-mcp-stdio"]
    }
  }
}

On the first call the bridge opens the person’s browser to sign in to Genie. It is a registered native client, so it keeps a refresh token in a private file on their machine and stays signed in; npx -y @paymanai/genie-mcp-stdio logout revokes it at Genie. Or skip the reading and hand this to a coding agent:

Integrate Genie (Payman's payments agent) into my MCP host by following the
"For agents" section of https://raw.githubusercontent.com/PaymanAI/genie-mcp-stdio/main/README.md
exactly. Detect which host I use, add the server, run the sign-in, and verify.

Source, per-host instructions and the exact procedure the agent follows are in the repository README.

Connectors

Where the money is

The accounts Genie can act on, each with a guide to how the connection is made and, where one is needed, how the owner obtains the token. Your agent never sees any of these credentials. All connectors.

Money your agent can use.

Four steps to a first call

An account with money behind it

Add the server to your host

Sign in once

Call ask_genie with the person’s words

Give your assistant one instruction.

One money tool, five outcomes

Where people already talk to Genie

A host that only runs local MCP servers

Where the money is

Using an assistant instead?