Skip to content
selvedge

Claude Code MCP setup

Selvedge works with any compatible agent. This page covers one optional client integration; see general MCP and CLI setup for other agents.

Two ways in: the plugin (/plugin install, no separate Selvedge install — it bootstraps the server and ships a skill, the PreToolUse enforcement hook, and slash commands), or a single claude mcp add for just the MCP server. The auto-detecting selvedge setup wizard works too.

Before you start

Section titled “Before you start”

Install uv, then install the Selvedge CLI and MCP server:

Terminal window
uv tool install --upgrade selvedge

The MCP config below launches the server with uvx instead of a bare selvedge-server, so the package can be fetched on demand — the editor still needs to find uv installed. Prefer the global binary? Swap uvx --from selvedge selvedge-server for selvedge-server.

Add the MCP server

Section titled “Add the MCP server”

The fastest path — register the stdio server with one command:

Terminal window
claude mcp add selvedge -- uvx --from selvedge selvedge-server

Add --scope user to make it available across all your projects, or --scope project to write a shared .mcp.json you can commit so the whole team gets it. Local scope (the default) keeps it to you in the current project.

That writes the equivalent MCP config to ~/.claude.json (local/user scope) or .mcp.json at the project root (project scope):

{
  "mcpServers": {
    "selvedge": {
      "command": "uvx",
      "args": ["--from", "selvedge", "selvedge-server"]
    }
  }
}

Prefer not to touch config files? selvedge setup detects Claude Code and writes this for you (with a .bak first).

Install as a Claude Code plugin (no separate Selvedge install)

Section titled “Install as a Claude Code plugin (no separate Selvedge install)”
/plugin marketplace add masondelan/selvedge
/plugin install selvedge@selvedge

Two commands — the plugin bootstraps the server via uvx/pipx, so no separate Selvedge install is needed. One install brings the MCP server, a skill that tells the agent when to use it, the PreToolUse enforcement hook, and the /selvedge:status, blame, history, and prior-attempts slash commands. Prefer a pinned install? pip install selvedge and the launcher uses it instead of uvx.

Tell your agent when to call it

Section titled “Tell your agent when to call it”

Selvedge captures decisions when your agent calls it. Install the instruction block into your project’s CLAUDE.md:

Terminal window
selvedge prompt --install CLAUDE.md

It’s also a copy-paste block on the site: the Selvedge agent prompt block.

Verify

Section titled “Verify”

Run /mcp inside Claude Code (or claude mcp list in a terminal). selvedge should show as connected with its 8 tools.

If it doesn’t connect

Section titled “If it doesn’t connect”

If claude mcp list shows selvedge as failed, uvx (from uv) isn’t on the PATH Claude Code spawns with — install uv, then re-run. Prefer a global install? Register -- selvedge-server after pip install selvedge instead.

Next

Section titled “Next”