Agent connections

Start with the one-message AI guide. This reference is for the agent or administrator configuring a connection. For terminal operations use the CLI reference; for application HTTP requests use the API reference.

Choose a connection

Remote MCP can be used by a coding agent with local project access. Choosing a transport does not grant project-file access. Hosted chat environments may lack a local shell or editable project, and host support can vary by version, plan, and workspace permissions.

Remote MCP setup

The server URL is:

https://app.yolfi.com/mcp

Let the MCP host discover OAuth metadata, register its client, and perform Authorization Code + PKCE. The owner signs in and approves the connection in Yolfi. Do not fabricate OAuth tokens or copy a browser session into configuration.

Codex desktop, CLI, and IDE

Reuse Yolfi if it is already available. These local clients share MCP configuration on the same Codex host; choose the controls for the client you are using:

• Desktop: open Settings > MCP servers > Add server. Name it yolfi, choose Streamable HTTP, and enter https://app.yolfi.com/mcp. Save, select Restart, then Authenticate when the server requests OAuth sign-in.
• IDE extension: open the gear menu > MCP servers > Add server. Use the same name, transport, and URL. Save, select Restart extension, then Authenticate.
• CLI: inspect existing entries, add Yolfi only if it is absent, then sign in:

codex mcp list
codex mcp add yolfi --url https://app.yolfi.com/mcp
codex mcp login yolfi

After consent, use /mcp to inspect the active servers and call yolfi_auth_status in the agent session. See the official desktop, CLI, and IDE MCP setup.

ChatGPT web and local Work

ChatGPT web: open Plugins, select the plus button > Add custom MCP server, and enter Yolfi's name, a description, and https://app.yolfi.com/mcp. Choose OAuth, review the connection prompt, and select Create as a plugin. Install the resulting plugin, start a new conversation, and select it with @. Account and workspace policies may restrict custom connections. Follow the official ChatGPT connection steps.

Local Work in the desktop app: use Settings > MCP servers as described in the desktop instructions above. ChatGPT web does not read the local Codex configuration. A cloud task with local computer access also needs its connection checked in that task; local setup alone does not install a cloud plugin. See the official MCP guide.

Claude chat in the browser or Desktop

Open Add Yolfi to Claude. This opens the custom connector form with the name and URL filled in; it does not add or authorize anything until the owner confirms.

Alternatively, open Customize > Connectors > Add custom connector and enter the server URL. Complete OAuth sign-in in Yolfi, then enable Yolfi from the chat's + > Connectors menu. If Claude asks how to identify its OAuth client, use Register automatically. A Team or Enterprise owner may need to add the connector before members can connect their accounts. Browser chat does not require npx or a local configuration file.

See Claude's custom connector setup and supported install links.

Claude Code

Terminal or IDE: check /mcp first. A Yolfi connector already connected to the same claude.ai account may be available automatically. Otherwise, with the Claude Code CLI installed, add a remote server for your user:

claude mcp add --transport http yolfi --scope user https://app.yolfi.com/mcp
claude mcp login yolfi

Skip add for an existing entry. The login command opens browser OAuth; /mcp in an interactive session offers sign-in too. Complete consent before starting a headless run. User scope makes this entry available across your local projects. See Claude Code MCP setup and authentication.

Cloud sessions at claude.ai/code: add and authorize the Yolfi connector in claude.ai using the Claude connector flow above, and enable it for the cloud session. Local CLI configuration does not transfer to that cloud environment. A browser using Remote Control of a local session still uses the local host's connection. See how connectors reach Claude Code and cloud sessions.

Cursor IDE and Cloud Agents

IDE: use Add Yolfi to Cursor. The installed Cursor app asks you to confirm the server. Complete its OAuth sign-in. The link carries only the server URL, with no API key. See the official install-link format.

For manual setup, merge this entry into .cursor/mcp.json for one project or ~/.cursor/mcp.json for all projects, preserving other servers:

{
  "mcpServers": {
    "yolfi": {
      "url": "https://app.yolfi.com/mcp"
    }
  }
}

Enable Yolfi in Cursor's Customize controls and complete OAuth when prompted. See Cursor MCP configuration.

Cloud Agents: open the MCP dropdown at cursor.com/agents, add an HTTP server with Yolfi's URL, enable it, and complete OAuth. Cloud sign-ins are separate from IDE sign-ins; a local config file does not connect a cloud agent. Team admins can distribute shared servers through Dashboard > Plugins & MCPs, but each user still authorizes OAuth. See Cloud Agent MCP setup.

OpenClaw Control UI

An administrator opens the Control UI for the Gateway that runs the agent, then Settings > MCP > Add server. Name it yolfi, select Streamable HTTP, and enter https://app.yolfi.com/mcp. In the scoped MCP config editor, set the entry's auth to oauth and keep it enabled. Select Save & Publish to apply the configuration, then Sign in for Yolfi and approve access. Verify the connection from the agent using yolfi_auth_status.

Browser sign-in requires the Gateway's own HTTPS, loopback, or published Tailscale address. A separately hosted UI cannot receive its OAuth callback. Use the official Control UI guide and connection troubleshooting. Offline CLI registration and login have different requirements, including stopping the Gateway; they are not commands to run against an active Gateway. See the CLI registry reference.

Hermes Desktop and terminal

Desktop: use Add Yolfi to Hermes. Review the server URL and OAuth configuration in the confirmation dialog, then approve the addition and sign in. This link requires Hermes Desktop. See the official Add to Hermes format.

Terminal: with Hermes installed, check existing servers before adding Yolfi:

hermes mcp list
hermes mcp add yolfi --url https://app.yolfi.com/mcp --auth oauth --connect-timeout 300

Skip add for an existing entry. If authorization remains pending, run hermes mcp login yolfi in a fresh terminal and complete the browser flow. Use /reload-mcp in the active session or start a new session, then verify yolfi_auth_status. See Hermes MCP commands and MCP configuration.

For an SSH or hosted Hermes installation, follow its remote OAuth guide. Depending on the surface, authorization uses the Desktop callback relay, an interactive callback URL prompt, or SSH forwarding. Do not assume a browser on another machine can reach the remote loopback callback, or that Yolfi provides a device-code grant.

Other MCP hosts

Use the installed host's documented remote connector or MCP interface with the server URL above. Confirm that the current environment supports Streamable HTTP and OAuth; the product name alone does not prove local shell or project-file access.

Only hosts documenting this mcpServers format should use:

{
  "mcpServers": {
    "yolfi": {
      "url": "https://app.yolfi.com/mcp"
    }
  }
}

Use the configuration format documented by the installed host. Do not ask a browser-only chat to run npx or assume it reads another application's local MCP configuration.

Local browser setup

Run these in the environment that will make Yolfi CLI or local MCP calls:

npx -y @yolfi/agent setup --agent local-agent

Open the returned loginUrl using an available browser tool, or present that link if the environment cannot open it. The owner completes sign-in and approval. Then run:

npx -y @yolfi/agent checkin --agent local-agent
npx -y @yolfi/agent auth:status

The package stores the resulting dedicated credential in ~/.yolfi/config.json with owner-only permissions. If check-in is pending, wait for owner approval and retry check-in. An expired or redeemed request that did not leave a usable local credential requires a new setup request. Do not print credentials or check-in tokens.

The CLI can now perform the integration directly. Only add local MCP if the host needs it:

{
  "mcpServers": {
    "yolfi": {
      "command": "npx",
      "args": ["-y", "@yolfi/agent", "mcp"]
    }
  }
}

The MCP process must use the same machine, user home, and optional YOLFI_CONFIG_HOME profile as browser setup. Verify yolfi_auth_status from the MCP session after loading it. A CLI auth check alone does not prove the MCP process can read that credential.

New account signup

Browser sign-in is the normal connection path. Local CLI and local MCP also provide signup for an owner who explicitly needs a new account. Reuse an existing account first. Only ask for an email or project name if the owner has not already supplied and confirmed it.

npx -y @yolfi/agent auth:agent-register \
  --email "owner@example.com" \
  --project-name "Space Shop" \
  --agent-name "local-agent" \
  --integration-intent accept_payments

The first call sends an email confirmation and stores temporary check-in state locally. After the owner opens the email link, repeat the same command with the same arguments to finish check-in. Local MCP exposes the equivalent yolfi_agent_register tool. Existing email addresses must use browser setup or host OAuth. If signup expires after account creation, use browser setup instead of repeating registration.

Provisioning and runtime credentials

A working MCP connection is sufficient for the agent to use its authorized MCP tools, including payment links, webhooks and Checkout Sessions. No additional organization API key is needed. Continue through that connection; do not add a CLI login or fetch an API key as a routine next step. This also applies to local MCP after browser setup: its stored agent credential is used automatically.

Adding a public Paylink URL does not require an application API key. A deployed server that creates dynamic Checkout Sessions needs a configured server credential. Use the existing secret manager and a secure handoff available in your environment; report a missing deployment-secret step without asking the owner to paste secrets into chat.

Remote MCP endpoint creation and rotation return the one-time signing secret in the tool result. That result is sensitive: do not repeat it in the user-facing response or logs. Remote MCP does not save it into a local profile or configure deployment secrets. If the host cannot securely write the receiver's secret storage, report that missing capability and use a supported handoff or local tooling. Local CLI/MCP creation and rotation save secrets in their protected profile and redact them from normal output. Reading an organization API key through a sensitive key-retrieval operation also requires careful handling; do not call it merely to check authentication.

Verification and recovery

• Run yolfi_auth_status inside the actual MCP session, or auth:status for a CLI workflow. Check the organization returned by that transport before changing it.
• A reachable server URL, dashboard login, installed config, or completed browser consent alone is not verification that the active agent can call authenticated tools.
• If remote authentication fails, reconnect or repeat the host's OAuth flow. If local auth fails, check the selected local profile and redo browser setup when needed.
• A missing tool can indicate a stale host tool list or an older package version. Inspect tools/list or CLI help, then use an available supported operation. Do not silently switch accounts or claim an unavailable command ran.
• After a timeout during a mutation, read the resulting state before retrying. Use stable idempotency keys for Checkout Session retries.
• If an owner denies consent, do not keep retrying authorization. Continue only independent work and describe what remains unavailable.

MCP resources and prompts

Connected servers expose knowledge resources and guided prompts for payment integration, Paylinks, webhooks, and verification. Read their current schemas and capabilities from the connected server. Resources provide instructions, not account authorization or payment evidence. The canonical workflow remains Connect with AI.

Core payment tools include yolfi_auth_status, yolfi_organization_get, yolfi_paylinks_list, yolfi_paylinks_get, yolfi_paylinks_create, yolfi_webhooks_list, and yolfi_webhooks_configure. Targeted settlement changes use yolfi_settlement_configure. Dynamic checkout uses yolfi_checkout_sessions_create and yolfi_checkout_sessions_get; the creation tool accepts the HTTP request fields plus idempotencyKey. Inspect tools/list for the actual connected server before calling these tools.

Local MCP additionally offers browser setup/check-in, signup, and yolfi_webhooks_verify({ endpointId, payload, signature }) using protected local signing-secret storage. Do not assume those local helpers exist on the remote server.

Connection compatibility

Remote connections require a host that supports Streamable HTTP MCP and OAuth at https://app.yolfi.com/mcp. The host discovers authorization settings and handles sign-in and token refresh. For local connections, use the official package's browser setup. You do not need to implement an authentication flow yourself.