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