# Ozma Agent Onboarding

Ozma is an agentic API marketplace. One key unlocks many APIs through a single gateway.

**Preferred install:** `npx @ozma_app/cli connect` (configures every detected agent).  
**Install hub:** https://ozma.app/connect

## Self-register (zero human setup)

```bash
curl -X POST https://api.ozma.app/v1/register
```

Returns `api_key` with **0 credits** (`credit_cents: 0`) and **consumer scopes**. Free platform catalog APIs work immediately. For paid APIs **or to publish your own API**: human signup + email verify ($1 trial + elevates key to `provider:write` / `billing:write`) or OAuth via MCP. Add a payment method at https://ozma.app/dashboard for usage billing.

Or call the gateway without a key when x402 is off — auto-registers a **0-credit** org. **x402 settlement is disabled in production** (`X402_ENABLED=false`). Prefer `/v1/register`, CLI `ozma register`, or MCP with OAuth/Bearer.

## Human signup

```bash
curl -X POST https://api.ozma.app/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","name":"You"}'
```

## MCP — generic config

```json
{
  "mcpServers": {
    "ozma": {
      "url": "https://mcp.ozma.app/mcp"
    }
  }
}
```

**Session persistence:** Echo the `Mcp-Session-Id` response header on subsequent requests. Clients that omit it get a new anonymous org on each call.

## Cursor

Add to `~/.cursor/mcp.json` or project `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ozma": { "url": "https://mcp.ozma.app/mcp" }
  }
}
```

One-click: https://ozma.app/connect

## Claude Code

```bash
claude mcp add --transport http ozma https://mcp.ozma.app/mcp --scope user
```

Project: `.mcp.json` with `{"mcpServers":{"ozma":{"type":"http","url":"https://mcp.ozma.app/mcp"}}}`

## Claude Desktop / claude.ai

- **claude.ai:** Customize → Connectors → add custom connector URL `https://mcp.ozma.app/mcp`
- **Desktop:** stdio shim via `npx mcp-remote https://mcp.ozma.app/mcp`

## Codex

```bash
codex mcp add ozma --url https://mcp.ozma.app/mcp
```

Or `~/.codex/config.toml`:

```toml
[mcp_servers.ozma]
url = "https://mcp.ozma.app/mcp"
enabled = true
```

## VS Code / Copilot

```bash
code --add-mcp '{"name":"ozma","type":"http","url":"https://mcp.ozma.app/mcp"}'
```

Repo: `.vscode/mcp.json` uses `"servers"` key (not `mcpServers`).

Copilot coding agent: repo Settings → Copilot → Coding agent → MCP JSON with `"tools": ["*"]`.

## Windsurf

`~/.codeium/windsurf/mcp_config.json` — use `serverUrl` (not `url`):

```json
{ "mcpServers": { "ozma": { "serverUrl": "https://mcp.ozma.app/mcp" } } }
```

## Cline

`cline_mcp_settings.json` in VS Code globalStorage:

```json
{ "mcpServers": { "ozma": { "type": "streamableHttp", "url": "https://mcp.ozma.app/mcp", "disabled": false, "autoApprove": [] } } }
```

## Gemini CLI

`~/.gemini/settings.json` — use `httpUrl`:

```json
{ "mcpServers": { "ozma": { "httpUrl": "https://mcp.ozma.app/mcp" } } }
```

## Tools

**Consumer:** `ozma_register`, `discover_tools`, `search_apis`, `get_api_details`, `get_schema`, `get_leaderboard`, `get_balance`, `get_categories`, `get_market_overview`, `request_api`, `create_checkout`, `billing_portal`, `billing_setup`, `provision_access`, `call_api`, `run_probe`, `get_usage`, `set_budget`

**Provider (verified key / OAuth):** `provider_list_apis`, `provider_get_api`, `provider_create_api`, `provider_update_api`, `provider_set_credentials`, `provider_set_pricing`, `provider_verify`, `provider_publish`, `provider_unpublish`, `provider_analytics`, `provider_connect_onboard`

## Typical agent flow

**Consume:**
1. `ozma_register` / OAuth → get key (register = **0 credits**, consumer scopes)
2. `discover_tools` or `ozma search` with task query
3. `call_api` / `ozma call` via gateway (free catalog APIs work immediately)
4. For paid APIs: email verify ($1 trial + full key scopes) or `billing_setup`

**Provide:**
1. OAuth or email-verified key
2. `provider_connect_onboard` → human completes Stripe KYC
3. `provider_create_api` → `provider_set_credentials` → `provider_verify` → `provider_set_pricing` → `provider_publish`

## x402 (signup-less paid calls)

**Currently disabled in production** (`X402_ENABLED=false`). When re-enabled, gateway returns HTTP 402 with payment requirements; pay via `X-PAYMENT` (USDC on Base).

## Docs

- Install hub: https://ozma.app/connect
- CLI: `npx @ozma_app/cli --help`
- REST API: https://ozma.app (see docs/API.md in repo)
- OpenAPI: https://ozma.app/.well-known/openapi.json
- llms.txt: https://ozma.app/llms.txt