> ## Documentation Index
> Fetch the complete documentation index at: https://sponson.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent tools

> The MCP server and the skill in Claude Code, Cursor, Codex CLI, Windsurf and VS Code.

`sponson mcp` serves three MCP tools over stdio: `sponson_plan`, `sponson_apply` and `sponson_receipt`. Every tool
answers with the same JSON envelope as `--json` on the command line. [SKILL.md](/guides/agents) tells the agent when
to write a plan line, when to stop and show a human the diff, and why it must never write a secret value or approve
production itself. Give an agent both: the MCP server to act, the skill to know when not to.

Each tool below gets two things: the MCP server configuration (copy it as it is) and a place for SKILL.md.

## Before you start

* Node.js 22 or later on the `PATH` the tool starts servers with: every configuration runs `npx -y sponson mcp`.
  To pin a version, write `sponson@0.5.0` instead of `sponson` in the arguments.
* The server reads `release.plan.yaml`, the git checkout and its `origin` (where receipts are pushed) from the
  directory it starts in, and provider tokens (`VERCEL_TOKEN`, `NEON_API_KEY`, `CLERK_SECRET_KEY`, every
  `env://NAME` the plan references) from its environment. Never write a token into one of these files: they are
  committed or shared. Each tool starts the server with the environment it was itself started with unless noted.
* When a tool starts servers outside the project (a global configuration), the agent can pass `plan`, `branch`,
  `sha` and `pr` to every tool, or start the server from the project:
  `"command": "sh", "args": ["-c", "cd /path/to/project && exec npx -y sponson mcp"]`.

## Claude Code

Add the server for this project (stored in your user configuration, not committed):

```bash theme={null}
claude mcp add sponson -- npx -y sponson mcp
```

Or share it with the team in `.mcp.json` at the repository root. `claude mcp add --scope project sponson -- npx -y
sponson mcp` writes exactly this:

```json theme={null}
{
  "mcpServers": {
    "sponson": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "sponson", "mcp"],
      "env": {}
    }
  }
}
```

Claude Code asks each person to approve a project's `.mcp.json` servers once. `claude mcp list` shows whether the
server started.

**The skill.** SKILL.md is already in Claude Code's skill format (a `name` and `description` frontmatter). Save it as
`.claude/skills/sponson/SKILL.md` in the repository (or `~/.claude/skills/sponson/SKILL.md` for every project); Claude
loads it when a task touches what its description names.

```bash theme={null}
mkdir -p .claude/skills/sponson
curl -fsSL https://raw.githubusercontent.com/MishaBear94/Sponson/main/SKILL.md -o .claude/skills/sponson/SKILL.md
```

## Cursor

`.cursor/mcp.json` in the repository (or `~/.cursor/mcp.json` for every project):

```json theme={null}
{
  "mcpServers": {
    "sponson": {
      "command": "npx",
      "args": ["-y", "sponson", "mcp"]
    }
  }
}
```

Enable the server under **Cursor Settings → MCP**. The agent uses MCP tools in Agent mode.

**The skill.** Save SKILL.md's text (without its frontmatter) as a project rule, `.cursor/rules/sponson.mdc`, with
this frontmatter so the agent pulls it in when the description matches:

```markdown theme={null}
---
description: Declare and apply everything that ships beside the code (database branches, env vars, callbacks) through release.plan.yaml and the sponson MCP tools, stopping for a human between plan and apply.
alwaysApply: false
---
```

## Codex CLI

`~/.codex/config.toml` (Codex's configuration is per user):

```toml theme={null}
[mcp_servers.sponson]
command = "npx"
args = ["-y", "sponson", "mcp"]
```

`codex mcp add sponson -- npx -y sponson mcp` writes exactly this. Codex does not hand MCP servers your whole
environment: name the provider tokens to forward in `env_vars`, and, since the configuration is global, give the
project directory as `cwd`:

```toml theme={null}
[mcp_servers.sponson]
command = "npx"
args = ["-y", "sponson", "mcp"]
env_vars = ["VERCEL_TOKEN", "NEON_API_KEY", "CLERK_SECRET_KEY"]
cwd = "/path/to/project"
```

**The skill.** Codex reads `AGENTS.md` at the repository root. Add SKILL.md's text there under a `## Sponson`
heading, or a line telling the agent to read `SKILL.md` before touching `release.plan.yaml` (with the file committed
next to it).

## Windsurf

Windsurf's MCP configuration is per user: `~/.codeium/windsurf/mcp_config.json` (**Windsurf Settings → Cascade →
MCP servers → View raw config**):

```json theme={null}
{
  "mcpServers": {
    "sponson": {
      "command": "npx",
      "args": ["-y", "sponson", "mcp"]
    }
  }
}
```

Refresh the server list in the MCP panel after saving. As the configuration is global, start the server from the
project (`sh -c "cd … && exec npx -y sponson mcp"`, above) when Cascade's tools cannot find the plan.

**The skill.** Save SKILL.md's text (without its frontmatter) as a workspace rule, `.windsurf/rules/sponson.md`, and
set its activation to **Model decision** with SKILL.md's description, so Cascade reads it when the task needs it.

## VS Code (GitHub Copilot agent mode)

`.vscode/mcp.json` in the repository (note the top-level key is `servers`, not `mcpServers`):

```json theme={null}
{
  "servers": {
    "sponson": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "sponson", "mcp"]
    }
  }
}
```

To give the server a token VS Code does not have in its environment, let VS Code prompt for it and store it encrypted
instead of writing it into the file:

```json theme={null}
{
  "inputs": [
    { "type": "promptString", "id": "vercel-token", "description": "Vercel token for Sponson", "password": true }
  ],
  "servers": {
    "sponson": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "sponson", "mcp"],
      "env": { "VERCEL_TOKEN": "${input:vercel-token}" }
    }
  }
}
```

Start the server from the file's **Start** code lens or **MCP: List Servers**, then pick the Sponson tools in the
Copilot Chat tools menu (agent mode).

**The skill.** Save SKILL.md's text (without its frontmatter) as `.github/instructions/sponson.instructions.md` with
this frontmatter, so Copilot adds it whenever the plan file is in play:

```markdown theme={null}
---
applyTo: "**/release.plan.yaml"
---
```

Or append it to `.github/copilot-instructions.md`, which Copilot reads on every request.

## How these configurations were checked

Every JSON and TOML block on this page parses, and each one's server runs `sponson mcp` (`scenarios/docs/integrations.test.ts`).
"Verified" means the tool's own CLI wrote or read the configuration back; "from the documentation" means it is
written from the tool's documentation and was not run:

| Tool | MCP configuration | Instructions |
| - | - | - |
| Claude Code | `claude mcp add`, and the `.mcp.json` it writes with `--scope project`: verified with the CLI | `.claude/skills/<name>/SKILL.md` and the frontmatter: from the documentation |
| Cursor | `.cursor/mcp.json` `mcpServers`: from the documentation | `.cursor/rules/*.mdc` frontmatter: from the documentation |
| Codex CLI | `codex mcp add` output, and `env_vars` and `cwd` read back by `codex mcp get --json`: verified with codex-cli 0.153.2. That only the named variables reach the server is from the documentation | `AGENTS.md`: from the documentation |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` `mcpServers`: from the documentation | `.windsurf/rules/` and its activation modes: not verified |
| VS Code | `.vscode/mcp.json` `servers`, `inputs`: from the documentation | `.github/instructions/*.instructions.md` `applyTo`: from the documentation |

If one of them has moved on, please open an issue or a pull request against this file.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.