Agent MCP loop
Discover, inspect schema, and call an API with a human billing boundary.
View as Markdown →This example shows the recommended discover → schema → call loop for agents connected to Ozma MCP at https://mcp.ozma.app/mcp.
1. Connect
npx @ozma_app/cli connect
Complete OAuth 2.1 in the browser or configure a Bearer ozma_live_… key. See Quickstart (agent).
Install hub: 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:
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, 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:
- Human session login (
ozma login --email) - Human accepts:
ozma terms accept <slug> --yes - 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