MCP Integration

Connect your AI coding assistant to Version Pill

Quick Start

Connect your client

Version Pill uses OAuth for authentication - no API keys needed. Just run one command:

Claude CodeRecommended

claude mcp add --scope user --transport http versionpill https://mcp.versionpill.com/mcp

Global Installation

The --scope user flag makes MCP available in all your projects. You only need to run this command once, and Version Pill will work everywhere.

A browser opens for OAuth authorization on first use.

Per-project installation (not recommended)

If you only want MCP in the current project, omit the --scope user flag:

claude mcp add --transport http versionpill https://mcp.versionpill.com/mcp

You'll need to run this in each project separately.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "versionpill": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.versionpill.com/sse"]
    }
  }
}

Restart Claude Desktop. A browser opens for OAuth on first use.

Cursor

Add to ~/.cursor/mcp.json or Settings → MCP → Add Server:

{
  "mcpServers": {
    "versionpill": {
      "url": "https://mcp.versionpill.com/sse"
    }
  }
}

Restart Cursor. A browser opens for OAuth on first use.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "versionpill": {
      "serverUrl": "https://mcp.versionpill.com/sse"
    }
  }
}

Authorize in browser

On first use, a browser window will open to authorize access. Sign in and click "Authorize".

Verify installation

Check that Version Pill is available in Claude Code:

claude mcp list

You should see versionpill in the list. If you used --scope user, it will show as a global MCP.

Start using MCP tools

Once connected, you can ask your AI to manage tasks, create releases, and more. Try asking: "List my Version Pill projects"

API Key Authentication (Advanced)

For CI/CD pipelines and scripts where OAuth flow isn't practical, you can use API keys. Create one in Settings.

curl -X POST https://mcp.versionpill.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Never commit API keys to version control. Use environment variables for security.

Available Tools

57+ tools total

Getting Started

context

Project state — tasks, releases, docs. Multiple depth modes (state, work, full, smart).

"Get full context for my project"

brain_dump

Session sync — complete tasks, create follow-ups, persist discoveries and blockers.

"Brain dump: found a bug in auth, needs fixing before release"

list_projects

List all your projects.

"List my projects"

get_project

Project details with task counts per column.

"Get details for project xyz"

Tasks

save_task

Create or update a task (title, type, priority, column, labels, due date).

"Create a bug: login fails on mobile"

list_tasks

List tasks with column, type, priority, label, and epic filters.

"Show me all high-priority bugs"

get_task

Get full task details including comments and relations.

"Get details for task SHI-42"

archive_task

Archive completed tasks to keep the board clean.

"Archive all done tasks"

estimate_task

Add story point estimates to tasks.

"Estimate task SHI-42 at 5 points"

Releases

save_release

Create or update a release with version, title, and linked tasks.

"Create release v1.2.0"

plan_release

Preview unreleased done tasks grouped by semver type.

"Plan next release for my project"

ship_releases

Auto-group done tasks and create releases (bugs→patch, features→minor).

"Ship all pending releases"

Epics & Sprints

save_epic

Create or update an epic to group related tasks.

"Create epic: User Authentication"

save_cycle

Create a sprint cycle with start/end dates.

"Create a 2-week sprint"

link

Link tasks to epics, cycles, or releases.

"Link tasks SHI-10, SHI-11 to the auth epic"

Docs & Ideas

save_doc

Create or update project documentation.

"Save API guidelines doc"

save_idea

Track feature requests with status and response.

"Add idea: dark mode support"

convert_idea

Turn a feature request into a task.

"Convert the dark mode idea to a task"

Intelligence

search

Semantic search across tasks, docs, releases, and ideas.

"Search for anything related to authentication"

project_status

Quick status queries — next task, blockers, progress, stats.

"What should I work on next?"

memory

Store and recall decisions, patterns, and codebase facts.

"Remember: we use Zod for all API validation"

Example Workflows

Start of coding session

Get full project context before starting work:

"Get full context for my project and show me what's in progress"

During development

Move tasks as you work on them:

"Move the auth task to in-progress, I'm starting on it now"

End of session brain dump

Sync learnings and create follow-up tasks:

"Brain dump: completed auth, found a bug in the logout flow that needs fixing, also need to add rate limiting"

Create a release

Ship a new version with completed tasks:

"Create release v1.3.0 with the tasks we completed today"

Troubleshooting

MCP not available in other projects

If you installed MCP per-project (without --scope user), it won't work in other projects. To fix this:

1. Remove the per-project installation:

claude mcp remove versionpill

2. Install globally:

claude mcp add --scope user --transport http versionpill https://mcp.versionpill.com/mcp

Connection refused

Make sure you have npx installed and your API key is correct. Try running the command manually in terminal first.

Invalid API key

Check that your API key starts with vp_ and is active in Settings.

OAuth redirect fails

Make sure you're logged in to versionpill.com before authorizing. Clear browser cookies if issues persist.

Need to re-authenticate

If your OAuth session expires, restart Claude Code or run:

claude mcp remove versionpill && claude mcp add --scope user --transport http versionpill https://mcp.versionpill.com/mcp