# Connect Genie to an agent — procedure for coding agents

You are connecting Genie, Payman's payments agent, to the user's MCP host or to software
they are building. Follow this in order. Do not ask the user for API keys, tokens or
client secrets: a person signs in to their own Genie account in the browser, and
the integration obtains its own OAuth tokens with their consent.

Genie's MCP server: `https://genie.paymanai.com/mcp` (Streamable HTTP). Main tool `ask_genie`,
plus helper tools for the assistant's own access (step 6).

## 1. Decide the path

- **HTTP and a vault, without MCP**: follow
  https://genie.paymanai.com/developers/http-agent.md. This covers messaging assistants
  with HTTP and a secure vault. Pair using a sign-in link and matching code; no callback
  is needed. Verify its discovery endpoint first.
- **Claude.ai or ChatGPT**: use the exact selections in step 2 and the per-host guide
  at https://genie.paymanai.com/connectors/claude or
  https://genie.paymanai.com/connectors/chatgpt.
- **Grok Bot**: there is no form to fill in. Send Grok Bot
  https://genie.paymanai.com/developers/http-agent-grok-bot.md. It follows the shared
  HTTP guide from its cloud computer and starts callback-free pairing.
- **Instinct**: there is no form. Send Instinct
  https://genie.paymanai.com/developers/http-agent-instinct.md. It follows the shared
  HTTP guide, starts callback-free pairing and stores credentials in its own vault.
- **Muse**: send Muse https://genie.paymanai.com/developers/http-agent-muse.md.
  This path works only if that installation can make HTTP requests and rotate
  credentials in secure vault code. The guide requires Muse to check first.
- **Remote MCP**: any other host that can add a remote MCP server by URL *and* completes
  OAuth on its own (it reacts to a `401` with `WWW-Authenticate: Bearer resource_metadata=…`
  by running the authorization-code flow). Go to step 2.
- **Stdio bridge**: the host is configured to launch local stdio MCP servers or cannot
  complete remote OAuth. Go to step 3. The bridge is already registered with Genie.
- **Your own code**: the user is writing an MCP client or agent. Go to step 4.

## 2. Remote MCP

Use these values in the host's remote MCP form. A developer setting up their own
assistant uses the same choices as an end user.

| Field | Claude | ChatGPT |
|---|---|---|
| Name | `Genie` | `Genie` |
| Server URL | `https://genie.paymanai.com/mcp` | Same |
| Transport, if shown | HTTP / Streamable HTTP | HTTP / Streamable HTTP |
| Authentication | **Sign in now** | **OAuth** |
| OAuth client / registration | **Register automatically** | Dynamic client registration (DCR) / automatic, if shown |
| OAuth client ID | Leave blank; it may disappear | Leave blank |
| OAuth client secret | Leave blank; it may disappear | Leave blank |
| Request / custom headers | Leave empty | Leave empty |

- **Claude:** Settings → Connectors → Add custom connector. Override a detected
  **Use your own OAuth client** selection with **Register automatically**. Genie requires
  sign-in before tools are available, so choose **Sign in now**; **Sign in when needed**
  is for servers that also offer anonymous tools. **No sign-in** does not apply.
  **Use Claude's published identity** requires CIMD, which Genie does not advertise.
  **Use your own OAuth client** is only for a client explicitly provisioned by an operator.
- **ChatGPT:** Settings → Security and login → Developer mode, then
  [Plugins](https://chatgpt.com/plugins) → **+**. Enter name `Genie`, description
  `Connect to your Genie finance assistant.`, and the public MCP URL. Older layouts may
  use Apps or Connectors → Create. Use OAuth and automatic registration when those
  choices appear; otherwise let discovery open Genie sign-in. Availability depends on
  account/workspace policy. [Official OpenAI setup](https://developers.openai.com/plugins/deploy/connect-chatgpt).
Save the connection and trigger the host's Connect/sign-in action when prompted. The
person signs in or creates and verifies their Genie account, reviews the callback website,
and selects **Connect to Genie** on the consent page. Enable Genie in the assistant's
chat tools and verify as in step 5. Connecting accounts
and setting payment limits are separate Genie steps, not fields in the OAuth client form.

If Claude reports that automatic registration is unsupported, check the URL and choices
above. The operator must confirm that the registration endpoint is deployed and reachable;
changing sign-in timing cannot fix missing registration support. After that is fixed,
edit the connector to use **Register automatically** and reconnect. Do not invent a client
ID, paste an API key, or disable authentication to work around the error.

For another remote host that cannot complete OAuth, use step 3 only if that host supports
local stdio servers. A URL-only host cannot run the bridge.

## 3. Stdio bridge

Follow the "For agents" section of
https://raw.githubusercontent.com/PaymanAI/genie-mcp-stdio/main/README.md exactly. It has the
config-file path and entry for each host. In short: add a server named `genie` with command
`npx` and args `-y @paymanai/genie-mcp-stdio`, **no `env` block**; run
`npx -y @paymanai/genie-mcp-stdio login` in a terminal the user can see (their browser opens;
they sign in; it prints `Signed in to Genie.`); restart the host. `logout` revokes the refresh token. Already issued access tokens may remain valid
until their one-hour expiry.

## 4. Your own MCP client or agent

- Transport: Streamable HTTP to `https://genie.paymanai.com/mcp`. Open the standalone `GET`
  SSE stream after `initialize`; Genie sends elicitation requests there. Keep the
  `Mcp-Session-Id`; sessions are bound to the signed-in person.
- Discovery: an unauthenticated request returns `401` with
  `WWW-Authenticate: Bearer resource_metadata="https://genie.paymanai.com/.well-known/oauth-protected-resource", scope="genie:ask genie:self"`.
  That document names the authorization server; its RFC 8414 metadata names the authorize,
  token, registration, revocation and JWKS endpoints.
- Authorization: OAuth 2.1 authorization code with S256 PKCE, `token_endpoint_auth_method`
  `none`, scope `genie:ask genie:self` (`genie:self` enables the helper tools),
  `resource=https://genie.paymanai.com/mcp`. Register a public
  client at the metadata's `registration_endpoint` (RFC 7591), sending a display name,
  exact redirect URIs and `token_endpoint_auth_method: "none"`. Save the returned
  `client_id` for later sign-ins; registration does not return a client secret. Include
  `grant_types: ["authorization_code", "refresh_token"]` in registration to receive a
  refresh token. Without `grant_types`, only `authorization_code` is enabled. Refresh
  tokens rotate on every use, remain valid 90 days from the last use, and can be revoked
  at the revocation endpoint. Send the newest token each time; reusing a rotated-out one
  revokes its refresh family. Already issued access tokens may remain valid for their one-hour lifetime. Separately, 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 require exact redirect URIs.
- Declare the `elicitation` capability if you can render a form; Genie uses it once per
  account to have the person connect a finance provider (`_meta.connectionUrl` may be
  opened for them). Without it, `ask_genie` replies with instructions instead.

## 5. Verify

Confirm the host lists a server `genie` with tool `ask_genie`. Call it with
`{"request": "In one sentence, what can you help me with?"}` and check a reply arrives.
On first use Genie may ask the person to connect a finance provider; that happens in
Genie's own UI and is expected.

## 6. Calling ask_genie

- Input: `request` (what the person wants, in their own words — never a filled-in payment
  form or a chosen account), optional `context`, optional `conversation`.
- Output: `status` and `message`.
  - `done` — Genie answered or acted; relay `message`. This does not prove payment settlement or order completion.
  - `needs_input` — relay `message`, get the person's answer, call again with the same
    `conversation` value.
  - `needs_approval` — stop and wait for a supported independent approval flow. General account approvals are not available yet; a host-relayed response cannot grant approval.
  - `refused` — outside the person's limits; `message` says which. Do not retry around it.
  - `error` — the turn failed. Read `outcome`: `NOTHING_RAN` is safe to retry,
    `OUTCOME_UNKNOWN` means money may have moved so do not retry, `BUSY` means try later.
- Reuse `conversation` for every follow-up, including a one-time code the person types
  into your chat. Show any `recovery` link to the person unchanged.
- Genie decides the rail, account and recipient and applies the person's limits. Never
  attempt to pick these yourself or to bypass a refusal.
- Helper tools (scope `genie:self`): `get_genie_agent` (your name, the person's accounts and
  your access to each), `rename_genie_agent`, `grant_genie_read_access` (Read only on one
  account) and `request_genie_access` (asks the person for Full access; only they can
  grant it, on the Agents page). After a Link purchase, `attach_purchase_confirmation`
  uploads the merchant's confirmation (PNG, JPEG or PDF).

The person manages accounts, agent access and spending limits in their Genie account
(Accounts, Agents, Policies) and sees payments, approvals and past conversations under
Activity. Chatting with Genie and approving payments on the website are not available
yet. Scheduled and recurring payments, automatic saving and x402 payments are not
supported. Plaid connections are read only. A saved connection does not establish that
any particular operation is permitted or supported.

## Do not

- Do not set or ask for `GENIE_ACCESS_TOKEN`, `GENIE_INTEGRATION_KEY`, `GENIE_OAUTH_CLIENT_ID`
  or any API key. Asking a user for such a value is a red flag.
- Do not ask for the person's Genie password or paste tokens into configuration files.
- Do not copy the bridge's `credentials.json` anywhere.