> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verlon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP (Model Context Protocol)

> Inspect and manage your Verlon AI account from any MCP-compatible client — Claude Desktop, Claude Code, Cursor, Cline, Windsurf.

## Overview

[MCP (Model Context Protocol)](https://modelcontextprotocol.io) is the open standard for how coding agents and LLM clients connect to external tools and data. The [`@verlon-ai/mcp`](https://www.npmjs.com/package/@verlon-ai/mcp) server exposes your Verlon gates, logs, recommendations, and experiments as MCP tools so any compatible host (Claude Desktop, Claude Code, Cursor, Cline, Windsurf, etc.) can inspect and reason about your AI infrastructure natively — without you copy-pasting curl commands into a chat. The server is open source (MIT) at [github.com/verlon-ai/mcp](https://github.com/verlon-ai/mcp), and every npm release carries a [provenance attestation](https://www.npmjs.com/package/@verlon-ai/mcp#provenance) tying the published package to that repo.

The server is **read-only by default**. The current 0.3.x releases ship five read tools — `list_gates`, `get_gate`, `list_logs`, `get_recommendations`, `list_experiments`. Write tools (`create_gate`, `update_gate`, etc., behind an explicit `--enable-writes` opt-in) follow in a future release.

### Use Cases

* **Agent introspection** — Ask Claude "what gates do I have?" and have it call `list_gates` rather than you opening the dashboard
* **Gate auditing during refactors** — Use Claude Code to inventory your AI infrastructure while editing the surrounding application code
* **Log inspection** — Tail recent requests inline with `list_logs` while debugging an integration

### Why the Verlon MCP server?

* **Read-only by default** — A misaligned agent host can only inspect, never destroy. Write tools require the explicit `--enable-writes` flag
* **Structured JSON tool outputs** — Every tool returns parseable JSON, not free-form text — so the calling model can reason about the result without re-prompting
* **One install line** — `npx -y @verlon-ai/mcp` works in any MCP client; no compile step, no Docker
* **Targeted error recovery** — Auth and API errors surface as `isError: true` content with explicit recovery hints, so the model can self-correct mid-conversation

## Quick Start

### Step 1: Get a Verlon API key

Generate one at [verlon.ai/dashboard/settings/keys](https://verlon.ai/dashboard/settings/keys). It looks like `sk-vrln-...`.

<Warning>
  The API key gives the MCP server full read access to your account. Treat it
  like any other secret — don't commit it to git, don't paste it into shared
  chats. Per-client config files are the right place.
</Warning>

### Step 2: Wire the server into your MCP client

**Claude Code / Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on your OS:

```json theme={null}
{
  "mcpServers": {
    "verlon": {
      "command": "npx",
      "args": ["-y", "@verlon-ai/mcp"],
      "env": {
        "VERLON_API_KEY": "sk-vrln-..."
      }
    }
  }
}
```

**Cursor** — add the same snippet under Settings → Features → MCP Servers.

**Any other MCP-compatible client** — spawn `npx -y @verlon-ai/mcp` over stdio with `VERLON_API_KEY` in the subprocess environment.

### Step 3: Restart the client and try it

Restart Claude Code (or your chosen host). Ask:

> List the gates in my Verlon account.

The host discovers the `list_gates` tool, invokes it, and shows the gates as a JSON response inline.

<Info>
  The default is **read-only**. If you opt into write tools via
  `--enable-writes`, do it deliberately and after you understand which
  tools mutate account state. Per-tool destructive hints are surfaced to the
  host so it can prompt before invoking risky operations.
</Info>

## Tools

All current tools are **read-only**. Write tools (`create_gate`, `update_gate`, `run_chat`, `start_experiment`) ship behind an explicit `--enable-writes` opt-in in a future release.

| Tool                  | Inputs                                                                 | What it returns                                                                                                                      |
| --------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `list_gates`          | *none*                                                                 | Every gate in the account — id, name, description, model, task type, creation date                                                   |
| `get_gate`            | `gateId` (UUID)                                                        | Full gate config — model, fallback chain, task type, spending limits                                                                 |
| `list_logs`           | `gate?`, `since?` (ISO 8601), `success?`, `limit?` (1–100, default 20) | Recent request logs — timestamp, gate, model, cost, latency, success/failure                                                         |
| `get_recommendations` | `gateId` (UUID)                                                        | Cortex intelligence report — themes, drift detection, optimization recommendations. `{ report: null }` when no Cortex run exists yet |
| `list_experiments`    | `gateId?`, `status?`, `projectId?`                                     | Experiments (shadow + split) — id, name, status, test type, variants, goal metric, configuration                                     |

The npm package always reflects the current toolset; check `verlon-mcp --help` after install.

## Configuration

| Env var           | Default                 | Notes                                             |
| ----------------- | ----------------------- | ------------------------------------------------- |
| `VERLON_API_KEY`  | —                       | **Required.** Your Verlon API key (`sk-vrln-...`) |
| `VERLON_BASE_URL` | `https://api.verlon.ai` | Optional override for self-hosted Verlon          |

## Dashboard

Generate API keys for the MCP server at [verlon.ai/dashboard/settings/keys](https://verlon.ai/dashboard/settings/keys). Manage gates the MCP server will inspect at [verlon.ai/dashboard/gates](https://verlon.ai/dashboard/gates).