kervo-mcp

MCP server for the Kervo public API. It runs locally over stdio, so any MCP client (Claude Desktop, Cursor, VS Code…) can read and change your Kervo organization with the permissions of a service account API key.

At startup it downloads the OpenAPI schema from your Kervo instance and creates one tool per operation, so new API endpoints show up without upgrading this package. Only the tools allowed by the key's scopes are listed.

Requirements

• uv (for uvx) or Python 3.10+.
• A Kervo organization whose plan includes the public API.
• A service account API key (kvo_…), created in Organization › Integrations.

Configuration

Replace <paste your kvo_ key here> with your key in the examples below.

Claude Desktop

Settings › Developer › Edit Config opens claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows). Restart Claude Desktop after saving.

{
  "mcpServers": {
    "kervo": {
      "command": "uvx",
      "args": ["kervo-mcp"],
      "env": {
        "KERVO_API_URL": "https://api.kervo.app/public/v1",
        "KERVO_API_KEY": "<paste your kvo_ key here>"
      }
    }
  }
}

The same mcpServers block works in:

• Antigravity — ~/.gemini/config/mcp_config.json (agent panel › MCP Servers › View raw config) or .agents/mcp_config.json in the workspace.
• Gemini CLI — ~/.gemini/settings.json or .gemini/settings.json in the project.
• Windsurf / Devin Desktop — ~/.config/devin/mcp_config.json (%APPDATA%\devin\ on Windows).
• Cursor — ~/.cursor/mcp.json or .cursor/mcp.json in the project; add "type": "stdio" to the kervo entry.

Claude Code

claude mcp add --env "KERVO_API_URL=https://api.kervo.app/public/v1" --env "KERVO_API_KEY=<paste your kvo_ key here>" --transport stdio --scope user kervo -- uvx kervo-mcp

VS Code

.vscode/mcp.json. VS Code asks for the key when the server starts and stores it encrypted, so it never goes into the file:

{
  "inputs": [
    { "type": "promptString", "id": "kervo-api-key", "description": "Kervo API key (kvo_…)", "password": true }
  ],
  "servers": {
    "kervo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["kervo-mcp"],
      "env": {
        "KERVO_API_URL": "https://api.kervo.app/public/v1",
        "KERVO_API_KEY": "${input:kervo-api-key}"
      }
    }
  }
}

Codex

~/.codex/config.toml (or codex mcp add kervo --env KERVO_API_KEY=… -- uvx kervo-mcp):

[mcp_servers.kervo]
command = "uvx"
args = ["kervo-mcp"]

[mcp_servers.kervo.env]
KERVO_API_URL = "https://api.kervo.app/public/v1"
KERVO_API_KEY = "<paste your kvo_ key here>"

Zed

Run zed: open settings file and add under context_servers:

{
  "context_servers": {
    "kervo": {
      "command": "uvx",
      "args": ["kervo-mcp"],
      "env": {
        "KERVO_API_URL": "https://api.kervo.app/public/v1",
        "KERVO_API_KEY": "<paste your kvo_ key here>"
      }
    }
  }
}

Troubleshooting

If the client cannot start uvx (spawn uvx ENOENT, common in desktop apps on macOS), use the full path printed by which uvx as command.

Security

• The agent acts as the service account and only sees what it sees. Use a dedicated key with the smallest scopes that do the job (read-only when possible) and an expiration date.
• The key lives in your MCP client's config file; keep that file private and never commit it.
• This package never writes the key to disk or logs, and never logs tool arguments.
• Task contents are data written by people: the server tells the model never to follow instructions found in them, but review destructive actions your agent proposes.

Exit codes

• 2 — invalid configuration (missing or malformed key, bad URL).
• 1 — startup failed (schema unreachable, invalid or revoked key, plan without the public API).

Development

The code lives in backend/kervo_mcp/ of the Kervo repository (shared with the remote connector). Build the wheel with python -m build --wheel packaging/kervo-mcp from backend/; only the wheel is published (the build pulls the modules from ../../kervo_mcp). Releases are tagged kervo-mcp-v<version>, matching kervo_mcp.__version__.