The MCP server: kadmo mcp

The Kadmo runtime is an MCP server. Register it with Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf (Devin Desktop), Gemini CLI or any other MCP client, and the client can run your workflows, read your skill packs and drive your Chrome.

A client on your computer registers it over stdio: the client starts kadmo mcp itself and talks to it over stdin and stdout. You do not start anything by hand, and no token is needed. Install the runtime first: Install the runtime.

This is the runtime's local MCP server, which works with the skill packs and the browser on your computer. The Kadmo app hosts a separate MCP server for your account at https://app.kadmo.ai/mcp (agents, tasks, playbooks, packs): see MCP server.

Register the local server as kadmo-agent. The name kadmo belongs to the app's server, so one client holds both side by side: kadmo for your Kadmo account, kadmo-agent for the runtime on your computer.

What the server offers

Kind	What	Details
Tools	29 tools: workflows and run logs, an artifact upload for agents, and the browser tools; plus the tools of installed plugins	MCP tools
Resources	workflow://<id> for each workflow (YAML) and skill://<domain>/... for each enabled _skill.md and role guide of an installed skill pack (Markdown)	Skill packs
Prompts	none

The browser tools need the Kadmo extension. The server's name in the MCP registry is ai.kadmo/kadmo-agent.

Register it with your client

Every recipe below runs kadmo mcp from the global install. Without a global install, use npx as the command and ["-y", "@kadmo/cli", "mcp"] as the arguments; npx fetches the package on first use.

Claude Code

claude mcp add kadmo-agent -- kadmo mcp

Add --scope user to make it available in every project. claude mcp list shows kadmo-agent as connected, and its tools as mcp__kadmo-agent__<tool>.

Claude Desktop

Settings → Developer → Edit Config opens claude_desktop_config.json (on macOS in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude\). Add:

{
  "mcpServers": {
    "kadmo-agent": {
      "command": "kadmo",
      "args": ["mcp"]
    }
  }
}

Restart Claude Desktop. If it cannot find kadmo, give the command's full path (which kadmo prints it).

Codex

codex mcp add kadmo-agent -- kadmo mcp

Or add it to ~/.codex/config.toml:

[mcp_servers.kadmo-agent]
command = "kadmo"
args = ["mcp"]

Cursor

Add to ~/.cursor/mcp.json (every project) or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "kadmo-agent": {
      "command": "kadmo",
      "args": ["mcp"]
    }
  }
}

VS Code

Run MCP: Add Server from the Command Palette, or add to .mcp.json at the root of your workspace (for every workspace: ~/.copilot/mcp-config.json):

{
  "mcpServers": {
    "kadmo-agent": {
      "command": "kadmo",
      "args": ["mcp"]
    }
  }
}

An older .vscode/mcp.json takes the same entry under "servers" with "type": "stdio".

Windsurf (Devin Desktop)

Windsurf is now Devin Desktop. Add to ~/.config/devin/mcp_config.json (on Windows %APPDATA%\devin\mcp_config.json), or .devin/mcp_config.json in a project; an older Windsurf install reads ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "kadmo-agent": {
      "command": "kadmo",
      "args": ["mcp"]
    }
  }
}

Gemini CLI

gemini mcp add -s user kadmo-agent kadmo mcp

Or add to ~/.gemini/settings.json (every project) or .gemini/settings.json in a project:

{
  "mcpServers": {
    "kadmo-agent": {
      "command": "kadmo",
      "args": ["mcp"]
    }
  }
}

Any other client

A client that starts stdio servers needs three things: the name kadmo-agent, the command kadmo and the argument mcp. Most read this shape:

{
  "mcpServers": {
    "kadmo-agent": {
      "command": "kadmo",
      "args": ["mcp"]
    }
  }
}

Check that it works

Ask your client something only the server can answer:

List the workflows Kadmo has.

A fresh install has none: the client says so, which proves the connection. Install a pack with kadmo install and ask again. To check the browser, ask for the browser status; it calls get_browser_status.

One runtime holds the browser

The Kadmo extension connects to port 9876 on your computer, and only one runtime process can hold that port. kadmo mcp opens it when your client starts the server. If kadmo serve (or another runtime) already holds it, kadmo mcp writes a warning to stderr and serves MCP without a browser: every browser tool then answers Browser not connected.

So run one of the two:

• Your client only. Stop kadmo serve; the client's kadmo mcp holds the extension. kadmo mcp serves only the extension's socket and /health on the port: no dashboard, no workflow count in the popup and no embed buttons.
• kadmo serve only, when you want the dashboard: then the stdio server has no browser, and browser automation runs through the dashboard and workflows instead.

Two clients that each start kadmo mcp have the same conflict: the first one holds the browser.

Over HTTP: agents

kadmo serve also serves MCP over HTTP at /mcp (Streamable HTTP), with the older /sse and /message pair beside it. This is how a Kadmo agent's own tools reach its runtime, and it always needs the agent's token:

Authorization: Bearer <KADMO_AGENT_TOKEN>

The token is required from loopback too, because a relayed request and a page in your browser both arrive from loopback. Without KADMO_AGENT_TOKEN set, or with a wrong token, every HTTP MCP request answers 401, and kadmo serve prints HTTP /mcp needs KADMO_AGENT_TOKEN; use kadmo mcp over stdio. at start. On your own computer, register kadmo mcp over stdio instead.

A client configured for HTTP sends the header itself:

{
  "mcpServers": {
    "kadmo-agent": {
      "type": "http",
      "url": "http://localhost:9876/mcp",
      "headers": { "Authorization": "Bearer ${KADMO_AGENT_TOKEN}" }
    }
  }
}

Troubleshooting

Symptom	Cause	Fix
The client shows kadmo-agent as failed or not connected	The client cannot start kadmo	Run kadmo --version in a terminal; give the full path from which kadmo, or use npx with ["-y", "@kadmo/cli", "mcp"]
Every browser tool answers Browser not connected.	The extension is not installed or has no tab, or another runtime holds port 9876	Check the extension's popup; stop kadmo serve (see One runtime holds the browser)
The client's log shows [kadmo] warning: could not start HTTP server	Port 9876 is taken	As above; lsof -i :9876 shows the process
401 from http://localhost:9876/mcp	The client is configured for HTTP without the agent's token	Use the stdio recipe above
The workflow list is empty	A fresh install has no packs	kadmo install

More on Troubleshooting.

Next steps

• MCP tools — every tool and its parameters
• Browser tools — snapshots, refs and selectors
• The Kadmo extension — let the runtime drive Chrome