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

​
Agent orchestration tools

When agent orchestration is enabled in Factory Settings, these additional tools become available in both plan-specific and general mode:
  • LaunchAgent — Launch a sub-agent on Cursor, Devin, or ref-thread to work in parallel. Specify the harness type, a prompt with full context, and the plan IDs to associate the agent with.
  • SendMessage — Send messages to child agents or back to a parent agent. Used for coordination — child agents report completion (with PR URLs), and parents send follow-up instructions.
These tools require:
  1. Factory Settings enabled — Go to Settings > Factory MCP at plan.ref.tools and toggle on the master switch
  2. Per-harness toggles — Enable the specific harnesses you want to use (Cursor, Devin)
  3. API keys configured — Set up Cursor and/or Devin API keys in Settings > Agent Settings
The Factory Settings page also provides a ready-to-paste MCP config snippet for connecting your orchestrating agent. See the multi-agent orchestration guide for full details on using these tools.

​
GitHub tools

A separate set of MCP tools for working with GitHub issues and pull requests is available at: 
https://api.plan.ref.tools/github-mcp
These tools are available when GitHub is connected and repos are indexed:
  • GetIssue — Get issue details and comments from an indexed repository
  • CommentOnIssue — Post a comment on a GitHub issue
  • SearchIssues — Search issues in an indexed repository
  • ReadPR — Read PR details, list changed files, and read diffs for specific files
  • ReviewPR — Submit a review (approve, request changes, comment) on a PR
  • MergePR — Merge a PR or mark a draft PR as ready for review
  • SearchPRs — Search pull requests in an indexed repository
These tools require:
  1. GitHub account connected at ref.tools/resources
  2. Repos added — Add the repositories you want to use with GitHub tools
ReviewPR and MergePR availability depends on your GitHub permissions settings. See the GitHub integration page for setup details.

​
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.