Verlon AI MCP

@verlon-ai/mcp

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 install

npm test # vitest npm 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 version jq -r .packages[0].version server.json grep 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 artifact

VERLON_API_KEY=sk-vrln-... npx @modelcontextprotocol/inspector npx -y @verlon-ai/mcp

License

MIT — see LICENSE.