# Yolfi AI integration

## Instructions for the agent

Follow the workflow below. Read a linked reference only when the next operation needs it; you do not need to load the whole documentation. Use the current MCP tool schemas or CLI `help` for available operations. Linked API references also describe request fields; reading them does not require switching away from a working MCP connection.

### 1. Inspect before asking

Read the current project and the user's request. If the project is unavailable, ask the owner to open or provide access to it; continue any independent checks your environment supports. Find products, prices, currencies, payment schedules, checkout UI, server routes, existing payment providers, webhook handlers, fulfillment or access logic, and secret-storage conventions. Reuse facts already supplied by the user or present in the project. Do not ask the owner to choose MCP, CLI, or an authentication protocol.

### 2. Choose and verify a connection

1. Inspect your available tools and existing Yolfi configuration. If Yolfi tools are already connected, call `yolfi_auth_status` through that connection and check the returned organization before provisioning anything. Once authenticated, continue through those MCP tools. Do not request, generate, retrieve, or configure an organization API key, or start a separate CLI login, just to continue MCP operations.
2. If no connection exists and your host can configure remote MCP with OAuth, connect to `https://app.yolfi.com/mcp` using the host's supported controls. Let the owner complete browser sign-in and consent, then call `yolfi_auth_status` in that same host.
3. If host OAuth is unavailable but you can run local commands, use the [local CLI browser setup](https://docs.yolfi.com/llms.mdx/en/agent-kit/connections#local-browser-setup). Run setup, open its returned `loginUrl`, wait for owner authorization, complete check-in, and verify `npx -y @yolfi/agent auth:status`. Continue through the CLI; installing a local MCP server is optional.
4. If neither route is available, explain the exact missing capability and give the owner the smallest supported connection step from the [connection reference](https://docs.yolfi.com/llms.mdx/en/agent-kit/connections). Continue independent project inspection when access is available. Do not claim that reading a URL or adding configuration established a working connection.

Use the capabilities of the current session, not the agent's brand name, to choose a route. Project file access and account tool access are separate. A successful CLI auth check does not authenticate a remote MCP host, and the reverse is also true. Do not start a second signup or connection when an existing one works.

### 3. Reuse account configuration

Read the authorized organization, settlement configuration, and existing Paylinks. If the product needs payment events, also inspect existing webhook endpoints. Match resources against the requested product, amount, currency, cadence, destination, and endpoint before creating them. Paginate lists when necessary. After an ambiguous create result or timeout, inspect existing state before retrying.

Ask only for required information you cannot find or resolve, such as a receiving address for an unconfigured network or an ambiguous price. Batch related questions. Reuse existing business choices; obtain approval for an actual change to receiving wallets, prices, billing terms, or destructive operations. Do not invent those values. Settlement updates must preserve networks outside the requested change.

### 4. Implement the requested payment flow

- For a fixed-price product or plan, reuse or create a Paylink and add its hosted URL, `https://pay.yolfi.com/{paylinkId}`, to the existing checkout. See [Paylink fields](https://docs.yolfi.com/llms.mdx/en/paylinks/api-reference) when needed. If payments must be matched to an order or customer, read the [checkout parameters and trust rules](https://docs.yolfi.com/llms.mdx/en/paylinks/checkout-parameters). A public Paylink redirect does not need a private API key in the application.
- For a dynamic cart or order total, calculate the amount on the merchant server and create a [Checkout Session](https://docs.yolfi.com/llms.mdx/en/checkout/api-reference) with a stable idempotency key. Inspect the available tool schema or CLI `help` before choosing a command.
- If the product must automatically update orders or access after payment, reuse its existing payment-event handling or configure a webhook when needed. Implement [raw-body signature verification](https://docs.yolfi.com/llms.mdx/en/webhooks/webhook-signatures) and durable idempotency for webhook handlers. A request to add only a hosted payment link does not require a new webhook. The [webhook recipe](https://docs.yolfi.com/llms.mdx/en/ai-integrations) is optional implementation guidance.
- Recurring Paylinks send renewal reminders; customers authorize each renewal payment from their own wallet. Do not implement automatic wallet debits. A payment confirmed after the subscription becomes overdue does not automatically restore access or extend its period; follow the [subscription lifecycle rules](https://docs.yolfi.com/llms.mdx/en/webhooks/webhook-details#subscription-overdue) and preserve the merchant's manual-resolution policy.

Only if the application itself makes private HTTP requests, configure a server credential using the [API authentication guidance](https://docs.yolfi.com/llms.mdx/en/api#authentication). The host's MCP OAuth token cannot be reused for those HTTP requests. Store any required server credentials or webhook signing secrets using the project's secret manager or ignored local environment files, never a chat transcript or committed source file.

If you create or rotate a webhook endpoint through remote MCP, its one-time signing secret is a sensitive tool result. MCP cannot configure the receiver's secret store by itself. If your host cannot securely write that store, report the precise remaining handoff instead of claiming the integration is ready. Do not repeat the secret in the user-facing response.

### 5. Verify and finish

Run the relevant project checks and verify the rendered checkout destination. If webhook handling is part of the integration, test valid and invalid signatures with fixture secrets. Verify account operations through the same transport you will use. Before automatic fulfillment, require public payment `status = SUCCESS` or a verified `payment.confirmed` event, while respecting subscription state for recurring access. A browser redirect, a Checkout Session marked `COMPLETED`, `isFullyPaid`, or deposit confirmation progress is not proof of completed payment.

Show the implemented flow, reused or created resource IDs, checks actually run, and any specific launch dependency such as deployment secret configuration. Do not stop at an account-readiness summary when you have the access and authorization to implement the request. Do not claim a connection, deployment, or live payment was verified when it was not.

## Focused references

- [Connection setup and recovery](https://docs.yolfi.com/llms.mdx/en/agent-kit/connections)
- [HTTP API](https://docs.yolfi.com/llms.mdx/en/api)
- [CLI commands](https://docs.yolfi.com/llms.mdx/en/cli)
- [Documentation index](https://docs.yolfi.com/llms.txt)

Use the index only if a needed reference is missing above.