Skip to main content

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

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. 
search_offers -> get_checkout_requirements -> get_checkout_link
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.

​
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.
mcp-config.json
{
  "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. 
search_offers({
  "vertical": "sim",
  "min_data_gb": 10,
  "contract_months": 0
})
Example mock response: 
{
  "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. 
get_checkout_requirements({
  "offer_id": "offer_mock_sim_001"
})
Example mock response: 
{
  "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. Once the user has provided the required fields, the agent requests a hosted checkout link. 
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: 
{
  "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

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

Runnable examples

Start the mock AAP server and run the SDK examples with fake data.

Mock conversion artifact

Learn how a later fake conversion payload references the checkout context.
The source transcript is also available in the repository at examples/mcp-agent-flow.