Verlon AI MCP

@verlon-ai/mcp

[npm version] [license] [CI]

Model Context Protocol server for 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.

Status: 0.4.0 — listed in the MCP Registry as ai.verlon/mcp. Ships 6 read-only tools (list_gates, get_gate, list_logs, get_recommendations, list_experiments, list_models) plus one write tool, switch_model, registered only with --enable-writes. The broader write surface (create_gate, update_gate, run_chat, start_experiment) lands in a future release behind the same flag.

Install

You 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.

Claude Code

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

Then restart Claude Code. The verlon server should appear in the tools list, and Claude can call verlon:list_gates against your account.

Cursor

Add to your Cursor MCP config (Settings → Features → MCP Servers):

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

Any other MCP-compatible client

The server speaks MCP over stdio. Spawn npx -y @verlon-ai/mcp with VERLON_API_KEY in the subprocess environment.

Tools

The default tool set is read-only — see Security note for the rationale. Write tools register only when the server starts with --enable-writes.

Write tools (--enable-writes only)

Configuration

CLI flags

Security note

Read-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) only after you understand the implications. The only write tool today is switch_model, deliberately the narrowest possible first write: one reversible field on one gate. Creating, updating, or deleting resources is not yet exposed.

Development

npm installnpm test          # vitestnpm run build     # tsc → dist/

Publishing (maintainers)

The 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.

Per-release flow

Bump versions in lockstep across three files — CI fails on drift:

Then:

# 1. Merge the bump to main (CI enforces the lockstep), then tag:git tag v0.4.1 && git push origin v0.4.1# The publish workflow runs `npm publish --provenance` automatically.
# Wait ~30s for npm CDN; verify:npm view @verlon-ai/mcp version   # should print the new version
# 2. MCP Registry publish (manual — needs mcp-publisher + DNS-verified ai.verlon namespace)npm run publish:mcp

One-time setup (registry publishing)

# Install the MCP Registry publisher (NOT npm — it's a prebuilt binary)brew install mcp-publisher
# DNS-verify the verlon.ai domain (required to publish under the ai.verlon namespace)mcp-publisher login --help   # follow the DNS verification flow it prints# Add the TXT record on verlon.ai; verify with `dig TXT verlon.ai +short`

Verification

# All three versions match?npm view @verlon-ai/mcp versionjq -r .packages[0].version server.jsongrep VERLON_MCP_VERSION src/server.ts
# Registry listing live?curl 'https://registry.modelcontextprotocol.io/v0/servers?search=verlon' | jq
# End-to-end smoke against the published artifactVERLON_API_KEY=sk-vrln-... npx @modelcontextprotocol/inspector npx -y @verlon-ai/mcp

License

MIT — see LICENSE.