# Agent MCP loop

This example shows the recommended **discover → schema → call** loop for agents connected to Ozma MCP at `https://mcp.ozma.app/mcp`.

## 1. Connect

```bash
npx @ozma_app/cli connect
```

Complete **OAuth 2.1** in the browser or configure a Bearer `ozma_live_…` key. See [Quickstart (agent)](/docs/getting-started/quickstart-agent).

Install hub: [https://ozma.app/connect](https://ozma.app/connect)

## 2. Discover

Tool: **`discover_tools`** or **`search_apis`**

```
query: "latest exchange rates USD EUR"
sort: relevance
max_results: 5
```

Expected: `frankfurter` (Frankfurter Exchange Rates) among top results — free, finance category.

Optional trust check: **`get_provider_profile`** with the provider slug from listing metadata.

## 3. Schema

Tool: **`get_schema`**

```
slug: frankfurter
```

Returns proxy paths, methods, and parameter schemas. Note `GET /latest` accepts `from` and `to` query params.

## 4. Call (free API)

Tool: **`call_api`**

```
slug: frankfurter
endpoint: /latest
method: GET
input: { "from": "USD", "to": "EUR" }
```

Response envelope includes `meta.cost_cents: 0` for this free endpoint.

CLI equivalent:

```bash
npx @ozma_app/cli call frankfurter /latest --query from=USD --query to=EUR --json
```

## 5. Human billing boundary (paid APIs)

Agents can autonomously call **free** catalog APIs with a register key (`ozma_register` → 0 credits).

For **paid** APIs or after trial credits exhaust:

| Step | Who | Tool / surface |
|------|-----|----------------|
| Email verify | Human (once) | Web signup or `ozma login --email` — unlocks `billing:write` |
| Add payment method | **Human required** | Dashboard [Billing](https://ozma.app/dashboard/billing), MCP `billing_setup` + Stripe.js, or `billing_portal` |
| Set key budgets | Agent or human | MCP `set_budget` or `ozma budget set` |
| Checkout prepaid pack | Human (optional) | MCP `create_checkout` or `ozma billing checkout` |

`billing_setup` returns a SetupIntent `client_secret` only — card capture cannot complete inside the agent loop without a browser.

## 6. Required terms gate

If `call_api` returns **428** `terms_acceptance_required`:

1. Agent: `get_api_terms` / `get_api_terms_status` (surface `document_id`, `content_hash`, `approval_url`)
2. Human session login (`ozma login --email`) or open the web `approval_url`
3. Human accepts: MCP `accept_api_terms` (session), or `ozma terms accept <slug> --yes`
4. Agent retries `call_api`

## 7. Usage audit

Tool: **`get_usage`** — review spend for the org.

```
from: 2026-07-01
to: 2026-07-22
```

## Full onboarding doc

Machine-readable agent onboarding: [https://ozma.app/onboarding.md](https://ozma.app/onboarding.md)

## Related

- [MCP reference](/docs/reference/mcp)
- [Authentication](/docs/getting-started/authentication)
- [First API call](/docs/examples/first-call)