> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rako.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Agent Flow Tutorial

> Walk through the canonical MCP checkout-link flow with fake data and placeholder keys.

# MCP Agent Flow Tutorial

This tutorial shows the canonical Rako MCP flow for an agent that helps a user compare eligible offers, collect checkout requirements, and generate a hosted checkout link.

```text theme={null}
search_offers -> get_checkout_requirements -> get_checkout_link
```

<Info>
  This tutorial uses placeholder credentials and fake IDs only. It does not process payment, collect payment details, confirm an order, prove a conversion, or mutate production/live data.
</Info>

## What you will learn

By the end, you should understand how an agent can:

1. Search for offers that match a user's request.
2. Ask what information is needed before checkout.
3. Collect only the required fields from the user in plain language.
4. Request a checkout link for the selected offer.
5. Hand the user off to hosted checkout outside the agent.

## Placeholder MCP config

Use placeholder credentials when running against the local mock server from the runnable examples.

```json mcp-config.json theme={null}
{
  "mcpServers": {
    "rako": {
      "command": "bunx",
      "args": ["@rakohq/mcp"],
      "env": {
        "AAP_API_KEY": "aap_demo_key",
        "AAP_API_URL": "http://localhost:3456"
      }
    }
  }
}
```

The example assumes deterministic fake data such as `sess_mock_001`, `offer_mock_sim_001`, and `https://checkout.example.invalid/mock`.

## 1. Search offers

The agent starts with the user's shopping intent.

```json theme={null}
search_offers({
  "vertical": "sim",
  "min_data_gb": 10,
  "contract_months": 0
})
```

Example mock response:

```json theme={null}
{
  "session_id": "sess_mock_001",
  "offers": [
    {
      "offer_id": "offer_mock_sim_001",
      "merchant_id": "merchant_mock_telco",
      "title": "Mock 20GB rolling SIM",
      "price": {
        "amount": 8,
        "currency": "GBP",
        "interval": "month"
      },
      "aap_code": "aap://rako.sh/v1/offer/merchant_mock_telco/offer_mock_sim_001"
    }
  ]
}
```

The agent should summarize the relevant option, keep the `session_id` and selected `offer_id`, and avoid saying the user has bought anything.

## 2. Get checkout requirements

Before asking for user details, the agent asks what fields are required.

```json theme={null}
get_checkout_requirements({
  "offer_id": "offer_mock_sim_001"
})
```

Example mock response:

```json theme={null}
{
  "offer_id": "offer_mock_sim_001",
  "required_fields": [
    {
      "name": "email",
      "label": "Email address",
      "type": "email",
      "required": true
    },
    {
      "name": "postcode",
      "label": "Postcode",
      "type": "text",
      "required": true
    }
  ],
  "notes": "Mock checkout requires contact and eligibility fields before a checkout link can be generated."
}
```

The agent should ask for those fields in normal language and explain that payment credentials are handled outside the agent conversation.

## 3. Generate a checkout link

Once the user has provided the required fields, the agent requests a hosted checkout link.

```json theme={null}
get_checkout_link({
  "session_id": "sess_mock_001",
  "offer_id": "offer_mock_sim_001",
  "user_details": {
    "email": "alex@example.invalid",
    "postcode": "SW1A 1AA"
  },
  "context": "Best mock value for 10GB+ no-contract SIM"
})
```

Example mock response:

```json theme={null}
{
  "checkout_id": "checkout_mock_001",
  "status": "checkout_link_created",
  "checkout_url": "https://checkout.example.invalid/mock",
  "message": "Mock checkout link created. The user completes checkout outside the agent."
}
```

The agent can now give the user the URL and clearly state that checkout happens on the hosted checkout page.

## Mock transcript

```text theme={null}
User: Find me a no-contract SIM with at least 10GB of data.

Agent: I found a mock offer: Mock 20GB rolling SIM for £8/month. I need to check what details are required before generating a checkout link.

[Tool call] search_offers({ vertical: "sim", min_data_gb: 10, contract_months: 0 })
[Tool call] get_checkout_requirements({ offer_id: "offer_mock_sim_001" })

Agent: This mock checkout needs an email address and postcode so the hosted checkout can be created. I will not ask for payment details in chat. What email and postcode should I use for the mock checkout handoff?

User: alex@example.invalid, SW1A 1AA.

[Tool call] get_checkout_link({ session_id: "sess_mock_001", offer_id: "offer_mock_sim_001", user_details: { email: "alex@example.invalid", postcode: "SW1A 1AA" }, context: "Best mock value for 10GB+ no-contract SIM" })

Agent: Here is the mock checkout link: https://checkout.example.invalid/mock

Opening this link would hand you off to hosted checkout. Creating this link does not process payment or confirm a conversion.
```

## Run it locally

<CardGroup cols={2}>
  <Card title="Runnable examples" href="/examples/overview">
    Start the mock AAP server and run the SDK examples with fake data.
  </Card>

  <Card title="Mock conversion artifact" href="/guides/mock-conversion">
    Learn how a later fake conversion payload references the checkout context.
  </Card>
</CardGroup>

The source transcript is also available in the repository at [`examples/mcp-agent-flow`](https://github.com/rakohq/developer-docs/tree/main/examples/mcp-agent-flow).