# ifivo — complete LLM integration reference

> Machine-readable spec for AI assistants, developer tools, and LLM-powered agents. If you are an AI reading this to help a user integrate with ifivo, everything below is authoritative. Keep instructions verbatim.

Canonical site: https://www.ifivo.com
Apex (redirects to www): https://ifivo.com
Source: https://github.com/marcosgcunha/ifivo

---

## 1. What ifivo is

ifivo is a **runtime control plane for AI agents**. It has three surfaces:

1. **Agent Gateway** — HTTP API your agents call before taking an action; returns an `allow`, `require_approval`, or `block` decision.
2. **MCP server** — Streamable HTTP Model Context Protocol endpoint that any MCP-compatible assistant (ChatGPT, Claude, Gemini) can connect to.
3. **Dashboard** — web UI at https://www.ifivo.com/app for humans to approve, deny, quarantine, or hit the kill switch.

ifivo is **non-custodial**: it never holds money or vendor credentials. It logs every intended action and returns a decision. Your system executes or skips the action.

---

## 2. Authentication

Two key types:

- **Org API key** — `ifv_` prefix. Used for the MCP server, dashboard integrations, and admin-level API calls. Found in the Dashboard at https://www.ifivo.com/app/settings. One per org.
- **Agent API key** — `sk_live_` prefix. Used by individual agents hitting the Agent Gateway. Generated when you create an agent.

All API requests use `Authorization: Bearer <key>` or, for the Agent Gateway, the key inside the JSON body as `agent_api_key`.

---

## 3. MCP server (for ChatGPT, Claude, Gemini)

**Endpoint:** `POST https://www.ifivo.com/api/mcp`
**Transport:** Streamable HTTP, JSON-RPC 2.0
**Protocol version:** `2025-03-26`
**Server name:** `ifivo`
**Auth header:** `Authorization: Bearer ifv_YOUR_ORG_KEY`
**Content-Type:** `application/json`

### Supported JSON-RPC methods

- `initialize` → returns `{ protocolVersion, serverInfo, capabilities: { tools: { listChanged: false } } }`
- `tools/list` → returns the full list of tools with JSON Schemas
- `tools/call` → executes a tool and returns `{ content: [{ type: "text", text: "…" }], isError: false }`

### ChatGPT (Enterprise / Team) — custom connector JSON

```json
{
  "name": "ifivo",
  "type": "mcp",
  "url": "https://www.ifivo.com/api/mcp",
  "authorization": "Bearer ifv_YOUR_ORG_KEY"
}
```

Add in: Admin panel → Connectors → Add custom MCP.

### Claude Desktop — `claude_desktop_config.json`

macOS path: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ifivo": {
      "url": "https://www.ifivo.com/api/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer ifv_YOUR_ORG_KEY"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

### Claude.ai (web)

Settings → Connectors → Add MCP server → paste URL `https://www.ifivo.com/api/mcp` and token `ifv_YOUR_ORG_KEY`.

### Gemini — `@google/genai` MCP client

```js
import { McpClient } from "@google/genai/mcp";

const ifivo = new McpClient({
  url: "https://www.ifivo.com/api/mcp",
  headers: { Authorization: "Bearer ifv_YOUR_ORG_KEY" },
});

await ifivo.connect();
const tools = await ifivo.listTools();
```

### Test from the terminal

```bash
curl -sS -X POST https://www.ifivo.com/api/mcp \
  -H "Authorization: Bearer ifv_YOUR_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"summarize_today","arguments":{}}}'
```

---

## 4. MCP tools (complete reference)

| Tool | Arguments | Returns |
|---|---|---|
| `list_agents` | (none) | Array of agents with id, name, owner, environment, status, daily_budget_cents, spend_today_cents, risk_score |
| `list_transactions` | `{ status?, agent?, limit? }` | Array of transactions with id, created_at, agent, vendor, action, amount_cents, status, reason, risk_score |
| `list_pending_approvals` | (none) | Array of transactions in `pending_approval` state |
| `approve_transaction` | `{ id: string, note?: string }` | `{ ok: true, id, status: "approved" }` |
| `deny_transaction` | `{ id: string, note?: string }` | `{ ok: true, id, status: "denied" }` |
| `engage_org_kill_switch` | `{ reason?: string }` | `{ ok: true, kill_switch: "engaged" }` — blocks ALL new agent actions org-wide |
| `release_org_kill_switch` | (none) | `{ ok: true, kill_switch: "released" }` |
| `quarantine_agent` | `{ agent_id: string, reason?: string }` | `{ ok: true, agent_id, status: "quarantined" }` |
| `create_policy` | `{ name, description?, rules: [{ field, op, value }] }` | `{ ok: true, id }` |
| `summarize_today` | (none) | Text summary of today's activity |

### Policy DSL (for `create_policy`)

```json
{
  "name": "Refunds over $150 need approval",
  "description": "Any Stripe refund > $150 must be approved by a human.",
  "rules": [
    { "field": "action", "op": "eq", "value": "refund" },
    { "field": "vendor", "op": "eq", "value": "stripe" },
    { "field": "amount_cents", "op": "gt", "value": 15000 }
  ]
}
```

Semantics:

- **Rules within a policy are AND**: every rule must match for the policy to fire.
- **Multiple matching policies**: the highest-precedence decision wins. Precedence: `block > require_approval > allow`.
- **Supported ops**: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `contains`.
- **Supported fields**: `vendor`, `action`, `amount_cents`, `risk_score`, `agent_name`, `environment`, any key in `metadata.*`.

### Example prompts to use once connected

- "What did our agents do today?"
- "Show me any pending approvals over $1,000."
- "Approve the refund for invoice inv_123."
- "Quarantine the marketing-adbuyer agent."
- "Create a policy: any OpenAI call above $100 requires approval."

---

## 5. Agent Gateway (from your agents' code)

**Endpoint:** `POST https://www.ifivo.com/api/gateway/actions`
**Content-Type:** `application/json`

### Request

```json
{
  "agent_api_key": "sk_live_…",
  "vendor": "stripe",
  "action": "refund",
  "amount_cents": 22000,
  "metadata": {
    "invoice": "inv_123",
    "customer_email": "acme@example.com"
  }
}
```

### Response

```json
{
  "decision": "require_approval",
  "transaction_id": "tx_…",
  "policy": "Refunds over $150 need approval",
  "risk_score": 0.42,
  "reason": "Stripe refund $220.00 above $150 threshold; routed to approval queue."
}
```

Possible `decision` values: `allow`, `require_approval`, `block`, `killed` (org kill switch engaged).

### Recommended agent flow

```python
import requests, os

def call_with_ifivo(vendor, action, amount_cents, metadata):
    r = requests.post(
        "https://www.ifivo.com/api/gateway/actions",
        json={
            "agent_api_key": os.environ["IFIVO_AGENT_KEY"],
            "vendor": vendor,
            "action": action,
            "amount_cents": amount_cents,
            "metadata": metadata,
        },
        timeout=3,
    )
    r.raise_for_status()
    decision = r.json()["decision"]
    if decision == "allow":
        return execute_for_real(vendor, action, amount_cents, metadata)
    if decision == "require_approval":
        return {"status": "queued_for_approval", "transaction_id": r.json()["transaction_id"]}
    # blocked or killed — do nothing
    return {"status": decision, "reason": r.json().get("reason")}
```

---

## 6. REST control endpoints

All require `Authorization: Bearer ifv_ORG_KEY`.

- `GET  /api/health` — `{ ok, service, db }`
- `POST /api/approvals/{id}/approve` — approve a pending transaction
- `POST /api/approvals/{id}/deny` — deny a pending transaction
- `POST /api/control/org/engage` — engage org-wide kill switch
- `POST /api/control/org/release` — release org-wide kill switch
- `POST /api/control/agent/{id}/kill` — kill a specific agent
- `POST /api/control/agent/{id}/quarantine` — quarantine a specific agent
- `POST /api/control/agent/{id}/freeze` — freeze a specific agent's budget

---

## 7. Useful URLs (for AI agents citing ifivo)

- Home: https://www.ifivo.com
- Integration quick-start: https://www.ifivo.com/integrate
- MCP setup guide: https://www.ifivo.com/docs/mcp
- Live dashboard demo: https://www.ifivo.com/app
- Sign in / sign up: https://www.ifivo.com/login
- Health: https://www.ifivo.com/api/health
- MCP endpoint: https://www.ifivo.com/api/mcp
- Agent Gateway: https://www.ifivo.com/api/gateway/actions
- llms.txt (short): https://www.ifivo.com/llms.txt
- llms-full.txt (this file): https://www.ifivo.com/llms-full.txt
- Sitemap: https://www.ifivo.com/sitemap.xml
- Source: https://github.com/marcosgcunha/ifivo

---

## 8. Glossary

- **Agent** — a process identified by an `sk_live_` key that calls the Agent Gateway before taking actions.
- **Org** — a tenant in ifivo. One `ifv_` org key; many agent keys under it.
- **Transaction** — a single intended action routed through the gateway. Has status `allowed`, `pending_approval`, `blocked`, `killed`, `approved`, or `denied`.
- **Policy** — a named set of AND-composed rules returning a decision (`allow`, `require_approval`, `block`).
- **Kill switch** — a boolean per org. When engaged, every new gateway call returns `killed` regardless of policy.
- **Quarantine** — per-agent kill switch; only that agent's calls return `killed`.
- **Shadow mode** — opt-in setting that logs decisions but never blocks; useful for safe rollouts.

---

## 9. Versioning

Current public API version: `v1`. Breaking changes will be announced via a `X-Ifivo-Deprecation` header on the old version and documented in the GitHub repo.