Vetto Researchers — MCP server

A small MCP server that lets a coding agent (Claude Code, etc.) send and receive Sample data per intent on the Vetto Researchers platform, without memorising the HTTP API. It is a thin wrapper over the Agent API (/api/agent/*, see docs/adr/0006-agent-api-for-samples.md): every call carries your bearer Agent Token, and the platform enforces access — reads are scoped to your grants; writes are admin-only.

What you can do

| Tool | Access | Does | | -------------------- | ------ | ----------------------------------------------------- | | list_intents | any | List intents you can see | | list_samples | any | List Samples in an intent (intent = key) | | get_sample | any | One Sample with its files (file urls are downloads) | | create_sample | admin | Create a Sample in an intent | | update_sample | admin | Change label / visibility / models | | attach_sample_file | admin | Attach a local file (filePath) or link (url) | | delete_sample_file | admin | Remove a file from a Sample |

Editing the actual datapoints/rubrics is not exposed yet — that arrives with the phase-2 content migration.

Get a token

Ask a Vetto admin to mint you an Agent Token in the backoffice (Access → Tokens). It is shown once and starts with vetto_.

Install (no checkout needed)

Register the server with your agent — npx fetches the published package on demand, so you don't clone this repo. For Claude Code, on one line:

claude mcp add vetto --env VETTO_API_TOKEN=vetto_your_token_here --env VETTO_BASE_URL=https://researchers.vetto.ai -- npx -y @vettoai/[email protected]

On Windows PowerShell, same command with backtick (`) line breaks or just keep it on one line.

• VETTO_BASE_URL is the deployment origin (no trailing slash). Use http://localhost:3000 to point at a local dev server.
• The version is pinned (@0.1.0) on purpose — an MCP server runs with your token in its environment, so you don't want npx silently pulling a new release. Bump it deliberately when a new version ships.
• The local alias vetto and the tool names (mcp__vetto__…) are yours to choose at claude mcp add time; they don't depend on the package name.
• Verify with claude mcp list, then ask your agent to "list the Vetto intents" to confirm the connection.

From source (contributors)

Hacking on the server itself? Run it from a checkout instead of npm:

cd mcp && npm install
claude mcp add vetto --env VETTO_API_TOKEN=… --env VETTO_BASE_URL=… -- node /absolute/path/to/vetto-researchers/mcp/server.mjs

Notes

• Logs go to stderr; stdout carries the JSON-RPC stream — don't pipe stdout.
• A 403 on a write means your token is read-only (not an admin). A 401 means the token is missing or revoked — ask an admin to re-mint.
• The same Agent Token also works with plain curl against /api/agent/* (see docs/skills/vetto-samples/SKILL.md); the MCP server just makes it turnkey for an agent.

Publishing (maintainers)

The package is published publicly to npm under the @vettoai org (the code carries no secrets — token and base URL are runtime env). To cut a release:

cd mcp
npm version patch        # or minor / major — bumps version + git tag
npm publish              # publishConfig.access=public, so no extra flag

• Requires npm login as a member of the @vettoai org, with 2FA.
• After bumping, update the pinned version in the install command above (and tell the team to re-run claude mcp add to pick it up).
• files in package.json limits the tarball to server.mjs + this README; run npm publish --dry-run first to confirm the contents.