MCP (Model Context Protocol)

Overview

MCP (Model Context Protocol) is the open standard for how coding agents and LLM clients connect to external tools and data. The @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, and every npm release carries a provenance attestation 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. It looks like sk-vrln-....

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.

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:

{
  "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.

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.

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. Manage gates the MCP server will inspect at verlon.ai/dashboard/gates.

​Overview

​Use Cases

​Why the Verlon MCP server?

​Quick Start

​Step 1: Get a Verlon API key

​Step 2: Wire the server into your MCP client

​Step 3: Restart the client and try it

​Tools

​Configuration

​Dashboard

Overview

Use Cases

Why the Verlon MCP server?

Quick Start

Step 1: Get a Verlon API key

Step 2: Wire the server into your MCP client

Step 3: Restart the client and try it

Tools

Configuration

Dashboard