Skip to main content

​
About the Ref Plans MCP Server

Ref Plans has its own MCP server, separate from the Ref Context MCP server. It lets coding agents read, write, and manage your plans directly. The streamable HTTP endpoint is available at https://api.plan.ref.tools/mcp.

​
Two modes

Plan-specific mode — Work on a single plan by appending the plan ID to the URL: 
https://api.plan.ref.tools/mcp?plan=<PLAN_ID>
In this mode, the agent has access to tools for reading, writing, editing, and commenting on that specific plan. General mode — Manage multiple plans using the base URL: 
https://api.plan.ref.tools/mcp
In this mode, the agent can list, create, and navigate across your plans.

​
Authentication

The Ref Plans API accepts authentication in three ways:
  1. As a header: x-ref-api-key: YOUR_API_KEY
  2. As a query parameter: ?apiKey=YOUR_API_KEY
  3. OAuth: Include neither header nor query param and your MCP client will initiate OAuth sign-in.
You can find your API key at ref.tools/keys.

​
Team-scoped access

To access plans under a specific team, add the team ID as a query parameter: 
https://api.plan.ref.tools/mcp?teamId=<TEAM_ID>

​
Available tools

Plan-specific mode provides:
  • Read — Read the current plan content
  • Write — Write or replace plan content
  • Edit — Edit specific sections of the plan
  • Manual — Access built-in planning guidance topics
  • Comments — Read and write comments on the plan
  • PrLinks — Attach pull request links to the plan
General mode adds:
  • List — List your plans
  • Create — Create a new plan

​
Installation Guides

Choose your coding environment below to get started:

Cursor

Connect Cursor to Ref Plans.

Claude Code

Connect Claude Code to Ref Plans.

Claude Desktop

Connect Claude Desktop and Web to Ref Plans.

VS Code

Connect VS Code to Ref Plans.

Antigravity

Connect Antigravity to Ref Plans.

Windsurf

Connect Windsurf to Ref Plans.

Cline

Connect Cline to Ref Plans.

Kiro

Connect Kiro to Ref Plans.

Roo Code

Connect Roo Code to Ref Plans.

Goose

Connect Goose to Ref Plans.

Amp

Connect Amp to Ref Plans.

Augment

Connect Augment to Ref Plans.

ChatGPT

Connect ChatGPT to Ref Plans.

Devin

Connect Devin to Ref Plans.

OpenCode

Connect OpenCode to Ref Plans.

Codex CLI

Connect Codex CLI to Ref Plans.

Droid CLI

Connect Factory Droid CLI to Ref Plans.

Gemini CLI

Connect Gemini CLI to Ref Plans.