# MCP tools

Endpoint: **`https://mcp.ozma.app/mcp`**

Install: `npx @ozma_app/cli connect` — [https://ozma.app/connect](https://ozma.app/connect)

## Connection

```http
POST /mcp
Authorization: Bearer ozma_live_…
Mcp-Session-Id: <uuid>
```

Production requires **OAuth 2.1** or **Bearer API key**. Unauthenticated requests return **401**.

OAuth metadata: `https://mcp.ozma.app/.well-known/oauth-protected-resource`

Echo **`Mcp-Session-Id`** on subsequent requests for session key persistence (30-day TTL in KV).

## Auth modes

| Mode | Best for |
|------|----------|
| **OAuth 2.1** | Interactive agents — email OTP proves ownership; mints full-scope key on approve |
| **Bearer `ozma_live_…`** | CI/scripts with pre-provisioned verified key |

Provider and billing tools need **`billing:write`** / **`provider:write`** — available after email verification or OAuth approve. Bare `ozma_register` keys return **403** until elevated.

## Consumer tools

| Tool | Params | Action |
|------|--------|--------|
| `ozma_register` | — | `POST /v1/register` → key + **0 credits** |
| `discover_tools` | `query`, `category?`, `max_results?` | Context-efficient catalog search |
| `search_apis` | `query`, `category?`, `sort?`, `max_price_cents?` | Full search |
| `get_categories` | — | Category list |
| `get_market_overview` | — | Market aggregates |
| `get_leaderboard` | `board`, `category?` | Merit board |
| `request_api` | `query`, `email?`, `notes?` | Catalog gap request |
| `get_api_details` | `slug` | Listing detail |
| `get_schema` | `slug` | Endpoints + schemas |
| `get_api_terms` | `slug` | Effective provider terms — CLI `ozma terms show` |
| `get_api_terms_status` | `slug` | Acceptance status — CLI `ozma terms status` |
| `accept_api_terms` | `slug`, `document_id?`, `content_hash?` | Accept terms — **human session required** (owner/admin + verified email) |
| `get_balance` | — | Billing balance |
| `create_checkout` | `pack?`, `amount_cents?` | Stripe Checkout (`billing:write`) |
| `billing_portal` | — | Portal URL (`billing:write`) |
| `billing_setup` | — | SetupIntent (`billing:write`) — **human must confirm card** |
| `get_usage` | `from?`, `to?` | Usage summary |
| `set_budget` | `key_id?`, `budget_cents?`, `per_call_max_cents?`, `daily_cap_cents?` | Patch key caps |
| `provision_access` | `slug?` | Ensure key exists |
| `call_api` | `slug`, `endpoint`, `method?`, `input?` | Gateway proxy — **428** if required terms missing |
| `run_probe` | `slug`, `endpoint`, `input?` | GET test call |

## Provider tools

Requires `provider:write`.

| Tool | Params | Action |
|------|--------|--------|
| `provider_list_apis` | — | List draft/live APIs |
| `provider_get_api` | `api_id` | Detail + pricing |
| `provider_create_api` | `openapi_url?`, `rapidapi_url?`, `body?` | Create/import |
| `provider_update_api` | `api_id`, metadata… | Patch listing |
| `provider_set_credentials` | `api_id`, `secret`, `injection?` | Store upstream secret |
| `provider_set_pricing` | `api_id`, `endpoints[]` | Price/discounts |
| `provider_verify` | `api_id` | Upstream smoke test |
| `provider_publish` | `api_id`, `skip_verify?`, `accept_terms?` | Go live — **`accept_terms: true` required** |
| `provider_list_documents` | `api_id?`, `kind?` | List legal documents |
| `provider_create_document` | kind, source, version, … | Create draft terms/privacy/… |
| `provider_activate_document` | `document_id`, … | Activate draft document |
| `provider_unpublish` | `api_id` | Live → draft |
| `provider_cancel_pending_pricing` | `api_id`, `endpoint_id` | Cancel scheduled increase |
| `provider_analytics` | — | GMV + payout stats |
| `provider_connect_onboard` | — | Stripe Connect URL — **human KYC** |

## Profile tools

| Tool | Params | Action |
|------|--------|--------|
| `list_providers` | `query?`, `limit?`, `offset?` | Public directory |
| `get_provider_profile` | `slug` | Trust badges + APIs |
| `get_my_profile` | — | Own profile (`provider:write`) |
| `update_my_profile` | profile fields… | Patch profile (`provider:write`) |

## Terms & documents

| Role | MCP | CLI |
|------|-----|-----|
| Consumer | `get_api_terms`, `get_api_terms_status`, `accept_api_terms` | `ozma terms show\|status\|accept <slug>` |
| Provider | `provider_list_documents`, `provider_create_document`, `provider_activate_document` | `ozma provider documents list\|create\|activate` |

`accept_api_terms` requires a **human session** (org owner/admin + verified email). Bearer API keys alone return **403** — use the web approval URL or `ozma login --email` then `ozma terms accept <slug> --yes`.

REST: `GET /v1/apis/:slug/terms`, `POST …/terms/accept`, `POST/GET /v1/provider/documents`.

## Human steps for billing / Connect

| Tool | Human action |
|------|--------------|
| `billing_setup` | Confirm card in [dashboard](https://ozma.app/dashboard/billing) or Stripe.js |
| `billing_portal` | Open returned URL in browser |
| `create_checkout` | Complete Stripe Checkout in browser |
| `provider_connect_onboard` | Complete Stripe Express KYC |
| `accept_api_terms` | Session login + verified email (or web approval URL) |

## Recommended flow

1. Connect OAuth or verified key
2. `discover_tools` / `search_apis` → `get_schema` → `call_api`
3. On **428** `terms_acceptance_required`: `get_api_terms` → human `accept_api_terms` / CLI / web → retry
4. For paid: human adds payment method; agent sets `set_budget`
5. Provide: `provider_connect_onboard` (human) → `provider_create_api` → credentials → verify → pricing → `provider_publish` with `accept_terms: true`

Agent onboarding: [https://ozma.app/onboarding.md](https://ozma.app/onboarding.md)

## Related

- [CLI reference](/docs/reference/cli)
- [Agent MCP loop example](/docs/examples/agent-mcp-loop)