{
  "markdown": "# @verlon-ai/mcp\n\n[![npm version](https://img.shields.io/npm/v/%40verlon-ai%2Fmcp)](https://www.npmjs.com/package/@verlon-ai/mcp)\n[![license](https://img.shields.io/npm/l/%40verlon-ai%2Fmcp)](./LICENSE)\n[![CI](https://github.com/verlon-ai/mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/verlon-ai/mcp/actions/workflows/ci.yml)\n\nModel Context Protocol server for [Verlon AI](https://verlon.ai). Exposes your Verlon resources (gates, logs, recommendations, experiments) as MCP tools so coding agents — Claude Code, Cursor, Cline, any MCP-compatible client — can inspect and manage your AI infrastructure natively.\n\n**Status:** 0.3.2 — listed in the [MCP Registry](https://registry.modelcontextprotocol.io/) as `ai.verlon/mcp`. Ships 5 read-only tools (`list_gates`, `get_gate`, `list_logs`, `get_recommendations`, `list_experiments`). Write tools (`create_gate`, `update_gate`, `run_chat`, `start_experiment`) gated behind `--enable-writes` land in a future release.\n\n## Install\n\nYou don't install it directly. Your MCP client (Claude Code, Cursor, etc.) spawns it as a subprocess via `npx`. Add the snippet below to your client's MCP config.\n\n### Claude Code\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on your OS:\n\n```json\n{\n  \"mcpServers\": {\n    \"verlon\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@verlon-ai/mcp\"],\n      \"env\": {\n        \"VERLON_API_KEY\": \"sk-vrln-...\"\n      }\n    }\n  }\n}\n```\n\nThen restart Claude Code. The `verlon` server should appear in the tools list, and Claude can call `verlon:list_gates` against your account.\n\n### Cursor\n\nAdd to your Cursor MCP config (Settings → Features → MCP Servers):\n\n```json\n{\n  \"mcpServers\": {\n    \"verlon\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@verlon-ai/mcp\"],\n      \"env\": {\n        \"VERLON_API_KEY\": \"sk-vrln-...\"\n      }\n    }\n  }\n}\n```\n\n### Any other MCP-compatible client\n\nThe server speaks MCP over stdio. Spawn `npx -y @verlon-ai/mcp` with `VERLON_API_KEY` in the subprocess environment.\n\n## Tools\n\nAll v0.3.x tools are **read-only** — see [Security note](#security-note) for the rationale and the planned write-tool opt-in.\n\n| Tool | Inputs | What it returns |\n|---|---|---|\n| `list_gates` | _none_ | Every gate in the account — id, name, description, model, taskType, taskSubtype, createdAt |\n| `get_gate` | `gateId` (UUID) | Full gate config — model, fallback chain, task type, spending limits, sub-gates, orchestration |\n| `list_logs` | `gate?`, `since?` (ISO 8601), `success?`, `limit?` (1-100, default 20) | Recent request logs — timestamp, gate, model, cost, latency, success/failure |\n| `get_recommendations` | `gateId` (UUID) | Cortex intelligence report — themes, drift detection, optimization recommendations. `{ report: null }` when no run has been produced yet |\n| `list_experiments` | `gateId?`, `status?`, `projectId?` | Experiments (shadow + split) — id, name, status, test type, variants, goal metric, configuration |\n\n## Configuration\n\n| Env var | Required | Default | Notes |\n|---|---|---|---|\n| `VERLON_API_KEY` | Yes | — | Your Verlon API key (`sk-vrln-...`). |\n| `VERLON_BASE_URL` | No | `https://api.verlon.ai` | Override for self-hosted Verlon. |\n\n## CLI flags\n\n| Flag | Purpose |\n|---|---|\n| `--enable-writes` | Register write-capable tools. **Phase 3+ feature.** In 0.1.x this flag is accepted but no write tools exist yet. Default is read-only — a misaligned agent can't accidentally destroy resources. |\n| `--help`, `-h` | Print usage. |\n\n## Security note\n\nRead-only by default is a deliberate choice. The MCP client (Claude Code, Cursor, etc.) sees this server's tools and may invoke them autonomously when a user's request makes them seem relevant. A read-only default means even a misaligned agent can only inspect your account, not modify it. Opt in to write tools (`--enable-writes`, Phase 3+) only after you understand the implications.\n\n## Development\n\n```bash\nnpm install\nnpm test          # vitest\nnpm run build     # tsc → dist/\n```\n\n## Publishing (maintainers)\n\nThe package is dual-published: to npm as `@verlon-ai/mcp` (automated, with provenance), and to the MCP Registry as `ai.verlon/mcp` (manual). The registry validates that the npm version exists before accepting a publish, so **npm always goes first**.\n\n### Per-release flow\n\nBump versions in **lockstep** across three files — CI fails on drift:\n\n| File | Field |\n|---|---|\n| `package.json` | `version` |\n| `server.json` | `version` AND `packages[0].version` |\n| `src/server.ts` | `VERLON_MCP_VERSION` constant |\n\nThen:\n\n```bash\n# 1. Merge the bump to main (CI enforces the lockstep), then tag:\ngit tag v0.3.1 && git push origin v0.3.1\n# The publish workflow runs `npm publish --provenance` automatically.\n\n# Wait ~30s for npm CDN; verify:\nnpm view @verlon-ai/mcp version   # should print the new version\n\n# 2. MCP Registry publish (manual — needs mcp-publisher + DNS-verified ai.verlon namespace)\nnpm run publish:mcp\n```\n\n### One-time setup (registry publishing)\n\n```bash\n# Install the MCP Registry publisher (NOT npm — it's a prebuilt binary)\nbrew install mcp-publisher\n\n# DNS-verify the verlon.ai domain (required to publish under the ai.verlon namespace)\nmcp-publisher login --help   # follow the DNS verification flow it prints\n# Add the TXT record on verlon.ai; verify with `dig TXT verlon.ai +short`\n```\n\n### Verification\n\n```bash\n# All three versions match?\nnpm view @verlon-ai/mcp version\njq -r .packages[0].version server.json\ngrep VERLON_MCP_VERSION src/server.ts\n\n# Registry listing live?\ncurl 'https://registry.modelcontextprotocol.io/v0/servers?search=verlon' | jq\n\n# End-to-end smoke against the published artifact\nVERLON_API_KEY=sk-vrln-... npx @modelcontextprotocol/inspector npx -y @verlon-ai/mcp\n```\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 5809,
  "sha": "de83ab8ef08ab23224554a4e6d4af65dc73db20063f4e457a10c0b3766043ee9",
  "repo_slug": "verlon-ai/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_verlon_mcp_7738a95c/readme"
}