# Brand Assets
Source: https://docs.ref.tools/brand/assets
Download Ref icons and wordmarks.
### Usage Guidelines
* Prefer the wordmark in nearly all cases.
* Icon should be used for buttons, icons, avatars etc.
* Always include the "." in wordmark and icon.
* It's fine to modify the color for the context.
The font is [Libre Baskerville](https://fonts.google.com/specimen/Libre+Baskerville?preview.text=Ref.).
For questions about brand usage, contact us at `hello@ref.tools`.
***
## Wordmark
Prefer the wordmark in nearly all cases. Ideal for headers, presentations, and marketing materials.
### For Light Backgrounds
**Download:**
* [SVG (Vector)](/logo/ref-wordmark-light.svg)
* [PNG (Light)](/logo/ref-wordmark-light.png)
### For Dark Backgrounds
**Download:**
* [SVG (Vector)](/logo/ref-wordmark-dark.svg)
* [PNG (Dark)](/logo/ref-wordmark-dark.png)
***
## Icon
Icon for buttons, icons, and avatars.
### For Light Backgrounds
**Download:**
* [SVG (Vector)](/logo/ref-logo-light.svg)
* [PNG (512x512)](/logo/ref-logo-512-light.png)
### For Dark Backgrounds
**Download:**
* [SVG (Vector)](/logo/ref-logo-dark.svg)
* [PNG (512x512)](/logo/ref-logo-512-dark.png)
***
## Text colors
* **Light**: `#e5e5e5`
* **Dark**: `#1a1a1a`
***
## Design Files
Figma file with icon and wordmark assets.
***
## Need Something Else?
If you need additional formats, sizes, or have questions about brand usage, please reach out to us at `hello@ref.tools`.
# Monthly Updates
Source: https://docs.ref.tools/changelog
Updates including new features launched, bugs fixed and relevant content.
* `2026-07`: [Ref July 2026 update](https://mailchi.mp/ref/july2026)
* `2026-06`: [Ref June 2026 update](https://mailchi.mp/ref/june2026)
* `2026-05`: [Ref May 2026 update](https://mailchi.mp/ref/may2026)
* `2026-04`: [Ref April 2026 update](https://mailchi.mp/ref/april2026)
* `2026-03`: [Ref March 2026 update](https://mailchi.mp/ref/march2026)
* `2026-02`: [Ref February 2026 update](https://mailchi.mp/ref/feb2026)
* `2026-01`: [Ref January 2026 update](https://mailchi.mp/ref/jan2026)
* `2025-12`: [Ref December 2025 update](https://mailchi.mp/ref/dec2025)
* `2025-11`: [Ref November 2025 update](https://mailchi.mp/ref/nov2025)
* `2025-10`: [Ref October 2025 update](https://mailchi.mp/ref/oct2025)
* `2025-09`: [Ref September 2025 update](https://mailchi.mp/ref/sept2025)
* `2025-08`: [Ref August 2025 update](https://mailchi.mp/ref/august2025)
* `2025-07`: [Ref July 2025 update](https://mailchi.mp/ref/july2025)
* `2025-06`: [Ref June 2025 update](https://mailchi.mp/ref/june2025)
* `2025-05`: [Ref May 2025 update](https://mailchi.mp/ref/may2025)
* `2025-04`: [Ref April 2025 update](https://mailchi.mp/ref/april2025)
* `2025-03`: [Ref March 2025 update](https://mailchi.mp/4837408ed44f/ref-updates-33125)
## Roadmap
We plan one month at a time. To see the current roadmap, checkout bottom of the most recent monthly update.
# Building the Best Documentation Search
Source: https://docs.ref.tools/comparison/building-doc-search
Principles for coding-agent context.
## Objectives
* Deliver precise answers with minimal tokens.
* Keep agents in flow without manual hunting.
* Blend public and private sources safely.
## Search Loop
1. Use session history to skip duplicate hits.
2. Return only the top \~5k relevant tokens per read.
3. Let agents adjust prompts while paging results.
## Token Discipline
* Favor HTTP MCP mode for fast responses.
* Trim payloads before handing context to the agent.
* Track credits per endpoint to spot waste.
## Source Coverage
* Index GitHub repos for code and docs.
* Add PDFs and Markdown libraries for gaps.
* Combine web search when private data misses.
## Agent Experience
* Verify installs with a sample MCP prompt early.
* Surface usage cards and alerts in the dashboard.
* Keep role-based guardrails tight for teams.
## Continuous Improvement
* Monitor credit logs after each feature launch.
* Re-run indexing when repos cross major releases.
* Capture wins and issues in a monthly changelog.
# Ref vs Context7
Source: https://docs.ref.tools/context/comparison/context7
Key differences between the popular documentation search MCP servers.
## Snapshot
| | Context7 | Ref |
| --------------------------- | ---------------------------------- | ------------------------------------------ |
| Approach | Batch retrieval | Iterative search + read |
| Content | Code snippets | Any content type (source of truth) |
| Token optimization | Consistent \~3k tokens/query | Adaptive 500-5k tokens/query |
| Tools | `resolve-library-id`, `query-docs` | `ref_search_documentation`, `ref_read_url` |
| Scrape any URL on the fly | No | Yes |
| Private repos | Paid add-on | Included |
| PDF & file upload | No | Yes |
| Repo indexing | Paid | Free |
| Prompt injection protection | In-house | [Centure.ai](https://centure.ai/) |
| Paid plan | \$10/mo for 500 queries | \$9/mo for 1,000 queries |
## Search Philosophy
Both Context7 and Ref now use stateful sessions to optimize token usage and avoid duplicate results. Where they differ is in search patterns and feature depth.
### Context7's Approach
Context7 asks your agent to pick a library and then query that library's docs.
**Strengths:**
* Pre-processed code snippets
* One of the most popular MCP servers showing why MCP is valuable
**Limitations:**
* Batch retrieval doesn't match iterative agent/human search patterns
* Limited to snippets from public documentation—no private repos, PDFs, or file uploads without paid upgrades
### Ref's Approach
Ref uses **agentic search with MCP sessions**: provides search() and read() tools, allowing agents to:
1. Issue queries and get result overviews
2. Selectively read only relevant documents
3. Iterate efficiently with session state
Ref emphasizes **source of truth** access so agents can read any content from docs (explanations, warnings, prose, code), not just pre-extracted code snippets. This prevents information loss from pre-processing while still returning only the relevant chunks needed.
**Session-powered improvements:**
* **Adaptive token usage** - agents choose which pages to read, so simple queries return only what's needed while complex queries can dig deeper
* **Never return same link twice** - agents can access prior results from context
* **On-the-fly extraction** - automatically filter large pages (e.g., 90K token Figma docs → 5K relevant tokens)
* **Pre-fetching** - results are cached for faster reads
## Why Token Efficiency Matters
Both servers optimize for **token usage** because:
* Tokens cost money
* [Context rot](https://research.trychroma.com/context-rot): irrelevant tokens degrade output quality
* Agents build context over multiple searches, so session-level metrics matter more than single-query precision
## Why Ref Wins
**2x the value:** \$9/month gets you 1,000 queries on Ref vs. 500 queries for \$10/month on Context7. That's more than double the queries per dollar.
**Agent-controlled retrieval:** Ref lets your agent decide which pages to read, adapting token usage to the task at hand. Context7 returns fixed batches—the agent only picks a library, then gets whatever the system decides to send back.
**Source of truth access:** Ref can retrieve any content type from documentation—explanatory text, warnings, prose, and code—returning only the relevant chunks needed. Context7 limits results to pre-extracted code snippets, which can miss important context and explanations.
**More sources, no extra cost:** Ref includes private GitHub repos, PDF indexing, and file uploads in the base plan. Context7 charges extra for private repos and doesn't support PDFs or file uploads at all.
**Free repo indexing:** Index your own repositories at no additional cost. Context7 charges for this feature.
**Matches how agents work:** Ref's search + read tools align with how frontier models are trained. OpenAI explicitly requires this pattern for Deep Research integration, signaling this is the future of agentic search.
**Prompt injection protection:** Ref uses [Centure.ai](https://centure.ai/) to detect and block prompt injection attacks in real-time. When your agent scrapes external websites or processes user-uploaded content, Centure's multi-modal analysis protects against malicious instructions embedded in text, images, or other data sources.
**Enterprise-ready:** Built-in GitHub, PDF, and Markdown indexing with team RBAC, no custom pipelines required.
## Learn more
Learn more about [how Ref evaluates agentic search](https://ref.tools/blog/how-make-search-good) and [how Ref leverages advanced MCP features](https://ref.tools/blog/how-does-ref-mcp) from the blog.
# Best Practices
Source: https://docs.ref.tools/context/getting-started/best-practices
How to prompt coding agents to use Ref effectively.
## TLDR
1. **Use the provided `search_docs` and `my_docs` prompts** - When you know your prompt will require working with a tricky library, use Ref's default prompts.
2. **Guide the model with rules files** - Set up a project rules file so the model always knows when you want it to use Ref.
# How coding agents use Ref
Coding agents leverage Ref's MCP tools to access documentation at the right moment. Understanding when and how agents use Ref helps you guide them more effectively.
### 1. When explicitly guided by the user
Agents use Ref when you explicitly instruct them to search documentation. This is the most reliable way to ensure agents access the latest docs.
**Example prompts:**
* `implement cors in my firebase functions, check docs with ref`
* `/Ref:search_docs langchain streaming callback handler implementation python`
* `look up how i explained ref.tools in my yc application in my private docs`
**Ref's built-in prompts:**
Ref provides two autocomplete prompts in compatible clients:
* **`search_docs`** - Guides agents to search public documentation
* **`my_docs`** - Directs agents to search your [private resources](/resources)
Typing `/Ref` and your IDE or CLI will autocomplete these prompts.
### 2. When encountering lint errors
When a coding agent detects errors related to library or API usage, they will search Ref for documentation without user guidance.
**Example flow:**
1. Agent hallucinates a function name that doesn't exist.
2. Linter flags the error.
3. Agent searches relevant documentation and applies the correct pattern.
The best way to encourage this behavior is with a simple prompt in an `AGENTS.md` or similar file.
# Guiding Agents with Rules Files
Rules files let you provide consistent instructions to coding agents. They're especially powerful for directing agents to use Ref automatically.
### Example Rules File Content
Rules files typically include project-specific instructions that guide AI agents in how to work with your codebase. For Ref integration, they should specify when and how to search documentation. They should generally be simple and direct.
**✅ Recommended for everyone**
It's helpful to provide a basic level of guidance to the agent that you want it to check docs with Ref.
```
When working with libraries, check the docs with Ref.
```
**✅ For sharing context between repos**
Ref is great for sharing context between repos. For example if you have microservices or client-server in different repos.
```markdown theme={null}
When working with APIs, search my private docs with Ref.
```
**❌ Do not over-prompt**
It's very unlikely your agent would need to search with Ref on every prompt.
```markdown theme={null}
Always start by checking the docs with Ref.
```
### Rules Files
Different AI coding tools support different rules file formats:
| File | Location | Supported Tools | Description |
| ------------------------- | -------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `AGENTS.md` | Project root | Cline, Windsurf, Roo Code, Goose, and other MCP-compatible tools | Vendor-neutral instructions file that works across multiple AI coding assistants |
| `.cursorrules` | Project root | Cursor (legacy) | Legacy rules file for Cursor IDE |
| `.cursor/rules/` | `.cursor/rules/` directory | Cursor | Recommended location for Cursor rules files |
| `CLAUDE.md` | Project root | Claude Code, Claude API integrations | Claude-specific instructions with tool-specific guidance |
| `.windsurfrules` | Project root | Windsurf | Windsurf Cascade-specific rules |
| `copilot-instructions.md` | `.github/` directory | GitHub Copilot | GitHub Copilot-specific instructions |
**Recommendation:** For maximum compatibility, use `AGENTS.md` as your primary rules file. It's supported by most modern AI coding tools that implement MCP or read standard project files.
## Next Steps
Build your own custom index of private documentation sources for you or your team.
# Intro to Ref
Source: https://docs.ref.tools/context/getting-started/intro
Ref MCP in one page.
Ref is a documentation search model MCP server that allows coding agents to search public and private docs.
Imagine your coding agent never made mistakes working with libraries (either public or private) and did it without blowing up the context window. The agent can always go find the exact snippet of documentation it needs to be successful. That's what Ref is built to do.
Install and try the Ref MCP server.
How to get the most out of Ref.
# What is MCP?
Source: https://docs.ref.tools/context/getting-started/mcp-overview
Understanding the Model Context Protocol and why it matters for AI coding agents.
## The Model Context Protocol
The **Model Context Protocol (MCP)** is an open standard that enables AI coding agents to connect with external tools, data sources, and services. Think of it as a universal translator that lets your AI assistant reach beyond its training data to access the specific information it needs, when it needs it.
Introduced by Anthropic in November 2024, MCP provides a standardized way for AI models to interact with the real world—reading files, querying databases, searching documentation, and executing tools—all through a common protocol.
## Why MCP Matters for Coding Agents
### The Documentation Problem
Modern development involves countless libraries, frameworks, and APIs. No AI model can memorize every API endpoint, every configuration option, or every recent update to every library. Traditional approaches either:
1. **Cram everything into the prompt** - This wastes tokens, blows up context windows, and still misses the exact information needed
2. **Hope the training data is current** - Models inevitably work with outdated information and hallucinate deprecated APIs
### The MCP Solution
MCP solves this by giving coding agents **just-in-time access** to accurate, up-to-date information:
* **Search documentation on-demand** - Find the exact code snippet or API reference needed for the current task
* **Access private resources** - Read your company's internal docs, not just public information
* **Stay current** - Always get the latest documentation, not what was known at training time
* **Preserve context** - Use tokens for reasoning instead of documentation
**The result?** Coding agents that make fewer mistakes, write better code, and never need to guess about API syntax or configuration options.
## MCP in Action with Ref
Ref is an MCP server specifically built for documentation search. It gives coding agents the ability to:
* **Search public documentation** - React, Next.js, Python, Go, and thousands of other libraries
* **Search private documentation** - Your team's internal docs, private repos, and custom APIs
* **Get precise answers** - Find the exact code snippet or configuration example needed
* **Stay up-to-date** - Always access the latest documentation versions
Instead of guessing about how to use a library, coding agents can simply ask Ref and get the authoritative answer.
## Learn More
Want to dive deeper into MCP? Check out these resources:
* [Official MCP Documentation](https://modelcontextprotocol.io) - The complete specification and guides
* [MCP Specification](https://modelcontextprotocol.io/specification/2024-11-05/index) - Technical details of the protocol
* [Visual Guide to MCP](https://block.github.io/goose/blog/2025/04/10/visual-guide-mcp/) - A beginner-friendly explanation with diagrams
Install the Ref MCP server and see it in action.
Explore the tools and capabilities Ref provides.
# Quick Start
Source: https://docs.ref.tools/context/getting-started/quick-start
Steps to get started with Ref.
## 1. Sign up
Sign up at [ref.tools/signup](https://ref.tools/signup) to create your account.
## 2. Install the MCP server
Follow the installation instructions at [ref.tools/install](https://ref.tools/install) with prepopulated API key.
Alternately, we provide [instructions for many different clients](/install#installation-guides).
## 3. Run a search
Ask your agent to search for documentation:
```
what is ref tools mcp, search the docs with ref
```
Confirm that the `ref_search_documentation` tool is called and returns relevant results.
## Next steps
How to get the most out of Ref.
# Amp
Source: https://docs.ref.tools/context/install/amp
Connect Amp to up-to-date and token-efficient documentation.
How to set up Ref with [Amp CLI](https://ampcode.com/manual#mcp).
## Install
Run the `claude` install command. You can copy a version of the command with your API key pre-populated at [ref.tools/install](https://ref.tools/install)
```
amp mcp add Ref https://api.ref.tools/mcp --header "x-ref-api-key: "
```
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Verify
Run the command:
```
claude mcp doctor
```
You should see:
```
➜ amp mcp doctor
User settings:
Workspace settings:
Ref (user settings): connected (2 tools: ref_search_documentation, ref_read_url)
```
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Antigravity
Source: https://docs.ref.tools/context/install/antigravity
Connect Antigravity to up-to-date and token-efficient documentation.
[Antigravity MCP docs](https://antigravity.google/docs/mcp)
You can find your Ref API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open Agent Chat.
2. Click the `...` Additional options button and select `MCP Servers`
3. Click `Manage MCP Servers`. This should open an editor tab called `Managed MCPS`
4. Update `mcp_config.json`
```mcp_config.json theme={null}
{
"mcpServers": {
"ref": {
"serverUrl": "https://api.ref.tools/mcp",
"headers": {
"x-ref-api-key": ""
}
}
}
}
```
## Verify
Go back to the `Manage MCP Servers` page and hit `Refresh`
You should see Ref with a green dot. It should say `2 tools, 2 prompts enabled`.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Augment
Source: https://docs.ref.tools/context/install/augment
Connect Augment to up-to-date and token-efficient documentation.
[Augment MCP docs](https://docs.augmentcode.com/setup-augment/mcp)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open `Augment Settings`. This can be done either from the VSCode command palette or the gear icon in Augment.
2. Under `Tools`, click `Add remote MCP`.
3. Update the settings to `Connection Type = HTTP` and `Authentication Type = Header`.
4. Fill in `Url` as `https://api.ref.tools/mcp` and add a header `x-ref-api-key` with your api key as the value.
5. Click `Add`.
## Verify
See the Ref server present with a green dot.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# ChatGPT
Source: https://docs.ref.tools/context/install/chatgpt
Connect ChatGPT to up-to-date and token-efficient documentation.
[ChatGPT MCP docs](https://platform.openai.com/docs/mcp)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open `Settings`
2. Click `Apps & Connectors`
3. If you are not already in developer mode, scroll to the bottom and click `Advanced settings` and toggle on Developer mode.
4. Click the `Create` button in the top right of the settings modal.
5. Fill in Name as `Ref`
6. Fill in MCP Server URL `https://api.ref.tools/mcp?apiKey=`
7. Under Authentication select `No authentication`. Your API key is set in the server url already.
8. Check the `I understand` box and click Create.
## Verify
1. To use Ref, click the `+` button in the left of the prompt input, go to `More` and select `Ref`.
2. Issue the following prompt.
```
what is ref tools mcp, search the docs with ref
```
This should results in a `ref_search_documentation` tool call.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Claude Code
Source: https://docs.ref.tools/context/install/claude-code
Connect Claude Code to up-to-date and token-efficient documentation.
How to set up Ref with [Claude Code](https://www.claude.com/product/claude-code).
## Install
Run the `claude` install command. You can copy a version of the command with your API key pre-populated at [ref.tools/install](https://ref.tools/install)
```
claude mcp add --transport http Ref https://api.ref.tools/mcp --header "x-ref-api-key: "
```
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Verify
Run the command:
```
claude mcp list
```
You should see:
```
➜ claude mcp list
Ref: https://api.ref.tools/mcp (HTTP)
```
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Claude Desktop and Web
Source: https://docs.ref.tools/context/install/claude-desktop
Connect Claude Desktop and Web to up-to-date and token-efficient documentation.
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open `Settings`
2. Click `Connectors`
3. Click `Add custom connector`
4. Fill in Name as `Ref`
5. Fill in Remote MCP Server URL `https://api.ref.tools/mcp?apiKey=`
## Verify
Start a new chat and issue the following prompt.
```
what is ref tools mcp, search the docs with ref
```
This should results in a `ref_search_documentation` tool call.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Cline
Source: https://docs.ref.tools/context/install/cline
Connect Cline to up-to-date and token-efficient documentation.
[Cline MCP docs](https://docs.cline.bot/mcp/configuring-mcp-servers)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open Cline plugin in VSCode and click the `MCP Servers` button at the top.
2. Select the `Configure` tab and click `Configure MCP Servers`. This should open `cline_mcp_settings.json`.
3. Update `cline_mcp_settings.json`
```
{
"mcpServers": {
"Ref": {
"command": "npx",
"args": ["ref-tools-mcp@latest"],
"env": {
"REF_API_KEY": ""
}
}
}
}
```
## Verify
Open a new chat with Cline and run the following prompt.
```
what is ref tools mcp, search the docs with ref
```
This should results in a `ref_search_documentation` tool call.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Codex CLI
Source: https://docs.ref.tools/context/install/codex
Connect Codex CLI to up-to-date and token-efficient documentation.
*Updated Oct 14, 2025*
[Codex MCP install docs](https://github.com/openai/codex/blob/main/docs/config.md#connecting-to-mcp-servers)
You can find your Ref API key at [ref.tools/keys](https://ref.tools/keys)
## Install
Codex is configured in a `config.toml` file. This typically lives at `~/.codex/config.toml`
To enable Ref update your `config.toml` to include:
```config.toml theme={null}
[mcp_servers.ref]
url = "https://api.ref.tools/mcp?apiKey="
```
If you are on an older version of Codex and you get the error `Error loading configuration: missing field 'command' in 'mcp_servers.ref'` and do not want to update, you can install the `stdio` server:
```config.toml theme={null}
[mcp_servers.ref]
command = "npx"
args = ["-y", "ref-tools-mcp@latest"]
env = { "REF_API_KEY" = "" }
```
## Verify
Run the command:
```
codex mcp list
```
You should see:
```
➜ codex mcp list
Name Url Bearer Token Env Var Status Auth
ref https://api.ref.tools/mcp?apiKey=. - enabled Unsupporte
```
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Cursor
Source: https://docs.ref.tools/context/install/cursor
Connect Cursor to up-to-date and token-efficient documentation.
[Cursor MCP docs](https://cursor.com/docs/context/mcp)
You can find your Ref API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
Installing in Cursor is as easy as 1-click. Visit [ref.tools/install]()
You can also manually install via Cursor's settings.
1. Open `Cursor Settings`
2. Click `Tools & MCP`
3. Click `New MCP Server`. This will open an `mcp.json` file.
4. Update `mcp.json`
```mcp.json theme={null}
{
"mcpServers": {
"Ref": {
"type": "http",
"url": "https://api.ref.tools/mcp",
"headers": {
"x-ref-api-key": "your-api-key"
}
}
}
}
```
## Verify
In `Cursor Settings` click `Tools & MCP`.
You should see Ref with a green dot. It should say `2 tools, 2 prompts enabled`.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Devin
Source: https://docs.ref.tools/context/install/devin
Connect Devin to up-to-date and token-efficient documentation.
[Devin MCP Marketplace docs](https://docs.devin.ai/work-with-devin/mcp)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Log into Devin and visit [https://app.devin.ai/settings/mcp-marketplace](https://app.devin.ai/settings/mcp-marketplace)
2. Search `Ref.tools` and select Ref from the results.
3. Enter your API key and click `Enable` and enable the integration.
## Verify
Open a new chat and run the following prompt.
```
what is ref tools mcp, search the docs with ref
```
This should results in a `ref_search_documentation` tool call.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Droid CLI
Source: https://docs.ref.tools/context/install/droid-cli
Connect Factory Droid CLI to up-to-date and token-efficient documentation.
*Updated Oct 20, 2025*
[Droid CLI MCP install docs](https://docs.factory.ai/cli/configuration/mcp)
You can find your Ref API key at [ref.tools/keys](https://ref.tools/keys)
## Install
Start Droid
```
droid
```
Run the `/mcp` command
```
/mcp add --type http Ref "https://api.ref.tools/mcp?apiKey="
```
## Verify
Start Droid:
```
droid
```
Run the `/mcp` command in the Droid TUI
```
/mcp list
```
You should see:
```
● Configured MCP servers:
Ref
Type: http
URL: https://api.ref.tools/mcp?apiKey=ref-3be3e42726eaebd3b8b7
```
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Gemini CLI
Source: https://docs.ref.tools/context/install/gemini-cli
Connect Gemini CLI to up-to-date and token-efficient documentation.
[Gemini CLI Docs](https://github.com/google-gemini/gemini-cli)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
Gemini CLI is configured through a `settings.json` file, typically found at `~/.gemini/settings.json`.
To enable Ref, update `settings.json`:
```settings.json theme={null}
{
"mcpServers": {
"ref": {
"httpUrl": "https://api.ref.tools/mcp?apiKey="
}
}
}
```
## Verify
Run the command:
```
gemini mcp list
```
You should see:
```
➜ gemini mcp list
✓ ref: https://api.ref.tools/mcp?apiKey= (http) - Connected
```
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Goose
Source: https://docs.ref.tools/context/install/goose
Connect Goose to up-to-date and token-efficient documentation.
[Goose Extensions docs](https://block.github.io/goose/docs/getting-started/using-extensions)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Click the `Extensions` button in the left side nav.
2. Click `Add custom extension`
3. Fill in Extension Name as `Ref`
4. Fill in Endpoint as `https://api.ref.tools/mcp`
5. Add a Request Header `x-ref-api-key` with value being your API key.
6. IMPORTANT: make sure you hit "+ Add" next to the request header to ensure it is actually added.
7. Click `Add extension`
## Verify
Open a new chat and issue the prompt.
```
what is ref tools mcp, search the docs with ref
```
This should results in a `ref_search_documentation` tool call.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Installation
Source: https://docs.ref.tools/context/install/index
Install Ref in your preferred coding environment
## About Ref's MCP Server
Ref runs as a **streamable HTTP server** that implements the Model Context Protocol (MCP). This means you can connect to Ref's documentation search capabilities from any MCP-compatible client without installing additional packages locally.
### Authentication
Ref's 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 or query param and your MCP client will initiate OAuth sign-in.
The streamable HTTP endpoint is available at `https://api.ref.tools/mcp`.
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
### OAuth and Teams
If you use OAuth in combination with [Teams](/usage/teams), you may need to specify the team you want Ref to access. Ref will do it's best to intelligently pick the correct team but you may want to manually force a specific team.
Here is the algorithm Ref uses to pick the user or team scope:
```
For base OAuth url https://api.ref.tools/mcp if the user belongs to:
- no teams -> user scope
- one team -> team scope for the users single team
- multiple teams -> user scope, require specifying team
When specifying scope in OAuth url https://api.ref.tools/mcp?scope=(user|{team_id})
- scope=user -> user scope
- scope={team_id} -> team scope
```
Team ids have the format `t-`. You can find the team OAuth url at [ref.tools/install](https://ref.tools/install)
***
## Installation Guides
Choose your coding environment below to get started:
Connect Cursor to up-to-date and token-efficient documentation.
Connect Claude Code to up-to-date and token-efficient documentation.
Connect Claude Desktop and Web to up-to-date and token-efficient documentation.
Connect VS Code to up-to-date and token-efficient documentation.
Connect Antigravity to up-to-date and token-efficient documentation.
Connect Windsurf to up-to-date and token-efficient documentation.
Connect Cline to up-to-date and token-efficient documentation.
Connect Kiro to up-to-date and token-efficient documentation.
Connect Roo Code to up-to-date and token-efficient documentation.
Connect Goose to up-to-date and token-efficient documentation.
Connect Amp to up-to-date and token-efficient documentation.
Connect Augment to up-to-date and token-efficient documentation.
Connect ChatGPT to up-to-date and token-efficient documentation.
Connect Devin to up-to-date and token-efficient documentation.
Connect OpenCode to up-to-date and token-efficient documentation.
Connect Codex CLI to up-to-date and token-efficient documentation.
Connect Factory Droid CLI to up-to-date and token-efficient documentation.
Connect Gemini CLI to up-to-date and token-efficient documentation.
# Kiro
Source: https://docs.ref.tools/context/install/kiro
Connect Kiro to up-to-date and token-efficient documentation.
[Kiro MCP configuration docs](https://kiro.dev/docs/mcp/configuration/)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
Option 1: Click this link.
Make sure you update `disabled: false` and fill in your API key.
Option 2: Manual install.
1. Open the Kiro left side panel via the Kiro ghost icon.
2. At the bottom, see the `MCP SERVERS` sections and mouse over it to see the `Open MCP Config` button. This will open `mcp.json`
3. Update `mcp.json` as follows:
```json theme={null}
{
"mcpServers": {
"Ref": {
"url": "https://api.ref.tools/mcp",
"headers": {
"x-ref-api-key": ""
},
"disabled": false,
"autoApprove": ["ref_search_documentation", "ref_read_url"]
}
}
}
```
## Verify
1. Open the MCP Server view in the Kiro feature panel
2. You should see `Ref` listed with a green status indicator
3. Start a new chat and issue the following prompt:
```
what is ref tools mcp, search the docs with ref
```
This should result in a `ref_search_documentation` tool call being executed.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# OpenCode
Source: https://docs.ref.tools/context/install/opencode
Connect OpenCode to up-to-date and token-efficient documentation.
[Opencode MCP docs](https://opencode.ai/docs/mcp-servers/)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Create an `opencode.jsonc` file in your project that matches the following:
```
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"Ref": {
"type": "remote",
"url": "https://api.ref.tools/mcp",
"enabled": true,
"headers": {
"x-ref-api-key": "YOUR_API_KEY"
}
}
}
}
```
## Verify
Open a new chat and issue the prompt.
```
what is ref tools mcp, search the docs with ref
```
This should results in a `ref_search_documentation` tool call.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Roo Code
Source: https://docs.ref.tools/context/install/roo-code
Connect Roo Code to up-to-date and token-efficient documentation.
[Roo Code MCP docs](https://docs.roocode.com/features/mcp/using-mcp-in-roo)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Click the `...` icon in the top right to expand additional menu items and selecte `MCP Servers`
2. Click either `Edit Global MCP` or `Edit Project MCP`.
3. Update the json file that is opened to match the following.
```
{
"mcpServers": {
"Ref": {
"type": "streamable-http",
"url": "https://api.ref.tools/mcp",
"headers": {
"X-ref-API-Key": ""
}
}
}
}
```
## Verify
Open a new chat and issue the prompt.
```
what is ref tools mcp, search the docs with ref
```
This should results in a `ref_search_documentation` tool call.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# VS Code
Source: https://docs.ref.tools/context/install/vscode
Connect VS Code to up-to-date and token-efficient documentation.
[VSCode MCP docs](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open the VSCode command palette `Shift + Command + P (Mac)` or `Ctrl + Shift + P (Windows/Linux)`
2. Type `mcp` and select the `MCP: Add server...` action.
3. Select the `HTTP` option.
4. Enter Server URL `https://api.ref.tools/mcp?apiKey=`
5. Enter Server ID `Ref`
At this point the server should be installed.
## Verify
1. Open the Chat UI.
2. In the chat input box, you should see a tools icon next to the send message icon. Click it.
3. This should open the `Configure Tools` menu. At the bottom of the list, you should see `MCP Server: Ref` with two tools enabled.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Windsurf
Source: https://docs.ref.tools/context/install/windsurf
Connect Windsurf to up-to-date and token-efficient documentation.
[Windsurf Cascade MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open the `mcp_config.json` file. This can be found at a path like `~/.codium/windsurf/mcp_config.json` or by opening Cascade Chat and clicking the `Customizations` icon (looks like a packing box) in the top right then clicking the settings button.
2. Update `mcp_config.json` as follows:
```
{
"mcpServers": {
"Ref": {
"command": "npx",
"args": ["ref-tools-mcp@latest"],
"env": {
"REF_API_KEY": ""
}
}
}
}
```
## Verify
Click the Cascade Chat Customizations button and see that Ref is active with 2 tools.
If it is not, you can click on `Ref` and click the `Refresh` button on the Manage MCPs page to refresh MCPs.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Zed
Source: https://docs.ref.tools/context/install/zed
Connect Zed to up-to-date and token-efficient documentation.
[Zed MCP docs](https://zed.dev/docs/ai/mcp)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open the agent thread UI in right dock with `cmd + R`.
2. In the top right, click the `...` icon and under MCP Servers, select `Add Custom Server...`. This should open the `Add MCP Server` modal.
3. In the bottom left of the modal click `Configure Remote` server.
4. Replace the entire content of the input JSON with the following and click `Add Server`.
```json theme={null}
{
"Ref": {
"url": "https://api.ref.tools/mcp?apiKey="
}
}
```
## Verify
1. Open a new thread in the agent thread panel and select the `...` settings icon then click `Settings`.
2. You should see Ref enabled in the Model Context Protocol (MCP) Servers section.
## Using Ref in Zed
You can use the built in auto-complete prompt `/search_docs` to search documentation with Ref.
Example prompt:
```
/search_docs what is ref tools mcp server
```
This should result in a `ref_search_documentation` tool call.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Prompts
Source: https://docs.ref.tools/context/mcp/prompts
Pre-configured prompts available through the Ref MCP Server.
The Ref MCP Server includes pre-configured prompts to help you work more effectively with your documentation. These prompts follow the [MCP Prompts specification](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts) and provide structured ways to search and access your documentation.
## Available Prompts
### `search_docs`
Guides your coding agent to search public documentation for libraries, frameworks, and APIs.
**Example usage:**
```
/Ref:search_docs langchain streaming callback handler implementation python
```
### `my_docs`
Directs your coding agent to search your [private resources](/resources), including indexed GitHub repositories and uploaded documentation.
**Example usage:**
```
/Ref:my_docs how we implement authentication in our backend
```
## Using Prompts
Prompts are designed to be **user-controlled** and are typically invoked through slash commands in your coding assistant.
**To use a Ref prompt:**
1. Type `/Ref` in your coding assistant
2. Your IDE or CLI will autocomplete the available prompts
3. Select either `search_docs` or `my_docs`
4. Add your search query
## Best Practices
For more information on how to effectively prompt coding agents to use Ref, see our [Best Practices guide](/context/getting-started/best-practices).
# MCP Registry
Source: https://docs.ref.tools/context/mcp/registry
Include Ref in your MCP registry or subregistry
## What is the MCP Registry?
The **MCP Registry** ([registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)) is the official directory of MCP servers - like an app store for AI coding agents. It's community-owned and serves as the canonical source for publicly-available MCP servers.
## Building Subregistries
Many organizations build **subregistries** that add value through curation, enhanced metadata, or focus on specific use cases. These subregistries typically:
* Pull servers from the official registry via API
* Add custom metadata, ratings, or curation
* Serve specific communities or enterprise needs
## Including Ref in Your Registry
**Ref** is available in the official MCP registry and provides essential documentation search capabilities for AI coding agents.
```title: Ref MCP registry name theme={null}
tools.ref/ref-tools-mcp
```
### Get Ref's Registry Data
```bash theme={null}
curl "https://registry.modelcontextprotocol.io/v0/servers?search=tools.ref/ref-tools-mcp"
```
This returns Ref's complete server metadata that you can import into your own registry.
## Resources
* **Official Registry**: [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)
* **Registry API**: [REST API Documentation](https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/consuming/use-rest-api.md)
* **Build Your Own**: [Registry Implementation Guide](https://github.com/modelcontextprotocol/registry/blob/main/docs/README.md)
Explore all available MCP servers.
View Ref's source code and documentation.
# Tools
Source: https://docs.ref.tools/context/mcp/tools
Available tools in the Ref MCP Server.
The Ref MCP Server provides powerful tools for searching and retrieving documentation.
## Available Tools
### `ref_search_documentation`
Search across your indexed documentation resources.
**Parameters:**
* `query` (string): Your search query. Include programming language, framework, or library names for best results.
### `ref_read_url`
Read the full content of a documentation URL. Can read URLs from search results or any URL from the web.
**Parameters:**
* `url` (string): The exact URL from a search result.
## Best Practices
For more information on how to effectively prompt coding agents to use Ref, see our [Best Practices guide](/context/getting-started/best-practices).
# GitHub
Source: https://docs.ref.tools/context/resources/github
Connect repos and control sync.
Manage your synced repos at [ref.tools/resources?tab=github](https://ref.tools/resources?tab=github)
## Which repos can I index?
* You may only index repos that you are a member of.
* If you would like a public repo indexed that is not already, [fill out the form here](https://tally.so/r/nrvBY2).
## What files are indexed?
* Small repos below 2,000 files index every file, including code files.
* Repos above 2,000 files index documentation files only.
## Synchronization
* Repos are synced on a 5 minute cron.
* Indexing is incremental so Ref will compare the current commit to the most recently indexed commit. This means if you modify the git history for your repo, indexing could fail and you will need to remove and re-add the repo from Ref.
## Authentication
* Ref uses personal access tokens to find and access your private repos.
* Adding a GitHub App for organizations is on the roadmap but not yet supported.
# Resources Overview
Source: https://docs.ref.tools/context/resources/overview
Connect your private documentation sources to Ref.
Ref allows you or your team to build a private index of context for your coding agent. We refer to each of these sources of context as `Resources`.
View your individual or team resources at [ref.tools/resources](https://ref.tools/resources)
## Available Resource Types
### GitHub Repositories
Connect your GitHub repositories to automatically index and sync documentation and code.
[Learn more about GitHub indexing →](/resources/github)
### PDF & Markdown Files
Upload documentation files directly to Ref.
[Learn more about PDF & Markdown uploads →](/resources/pdf-markdown)
# PDF & Markdown
Source: https://docs.ref.tools/context/resources/pdf-markdown
Upload docs outside GitHub.
Manage your PDF & Markdown files at [ref.tools/resources?tab=pdf](https://ref.tools/resources?tab=pdf)
## What can you upload?
* Upload any `*.pdf` or `*.md` files. They will be automcatically chunked and indexed.
* The hard files size limit is 100MB per file.
* If upload is failing with less than 100MB files, try breaking down the files into smaller peices. We've seen this be necessary for some users will medium size files and poor to mediocre internet connects.
## Roadmap
* Long-term we would like this experience to feel like Google Drive where you can easily manage files.
# Dashboard
Source: https://docs.ref.tools/getting-started/dashboard
Key widgets to watch.
## First Login
* Complete email verification if prompted.
* Review the onboarding steps for install and sample prompt.
## Action Cards
* `Quick Install` opens direct MCP client links.
* `Search Documentation` runs live searches across indexed sources.
* `Add Resources` launches GitHub and PDF indexing flows.
* `Usage & Credits` shows daily spend and endpoint counts.
## Usage Drilldown
* The usage table lists every credit transaction.
* Filters separate search, read, chat, and web calls.
* Export data for audits by copying the table into CSV.
## Team Alerts
* Pending invites surface inline with accept and decline.
* Teams with low credits trigger upgrade prompts.
* The `Add members` card routes to role management.
## Quick Recovery
* The snackbar toast log keeps recent system messages.
* Use it to confirm new API keys or bulk imports.
# Welcome!
Source: https://docs.ref.tools/index
Everything you need to know about Ref — documentation search and plan orchestration for coding agents.
## Ref Plans
The shared source of truth for AI-generated software: create the plan, align the team, and orchestrate agents from one place.
Overview of what Ref Plans is and how it works.Create your first plan and send it to an agent.
## Ref Context
Search public and private documentation from any MCP-compatible coding agent.
Overview of what Ref Context is and why you might use it.Install the Ref MCP server and try it yourself.
# Ref Plans
Source: https://docs.ref.tools/plans/beta
Overview of Ref Plans and information for beta users
Thank you for your interest in [https://plan.ref.tools](https://plan.ref.tools)!
# TLDR; What is this?
Ref Plans is a tool for iterating and collaborating on plans for coding agents. It's a place for context engineering and orchestration.
You can research, revise and share plans with other humans for feedback. When a plan is ready, send it to your coding agent of choice (Claude Code, Cursor, Codex, Conductor etc) to implement and that agent will report progress back to Ref.
It works great for large or complex plans that go beyond a single commit.
# How to get started
1. Signup for Ref [https://ref.tools/signup](https://ref.tools/signup)
2. *(Optional but recommended)* Connect your GitHub and repos to the index [https://ref.tools/resources?tab=github](https://ref.tools/resources?tab=github)
3. Visit [https://plan.ref.tools](https://plan.ref.tools) to create your first plan.
4. Iterate on the Plan yourself and with Ref's agent cloud Claude Code then send it to a coding agent to implement.
# I am a \_\_\_\_. How do I use Plans?
Ref Plans is flexible and meant for teams. How you use it depends on your role.
## Early-career — Research and learn
Your main job is learning and developing your taste as an engineer. You practice these skills in Ref by researching and writing implementation plans then asking teammates for feedback. You work with AI to create a plan and spend your time considering the design choices and checking assumptions. This is how you learn and advance in your career.
## Senior / Staff — Orchestrate complex projects
You're juggling as many agents as possible while also supporting junior engineers. You use Ref to manage complex projects spanning multiple days in parallel without going insane. You provide feedback on other engineers' Plans to help them learn and to avoid slop code review.
## Tech Lead / Manager — Guide the organization
You need to help a team of engineers operate with high through-put with AI while maintaining coherence towards company objectives. You use Ref Plans as basis for organizational process around Plan review and to have a single view into all of the team's work.
## Vibecoder — Scale context beyond single sessions
You have tons of ideas and your project’s complexity is growing. You use Ref to maintain a single cohesive source of context across large projects. You research and refine your ideas in Ref and then dispatch multiple parallel agents to bring them into reality.
# Quick Demo: My workflow with Plans
Ref Plans is a tool for researching and writing Plans and orchestrating agents to implement them. It take `/plan` mode beyond single changes to multi-day, multi-PR arches of work.
Here's a quick demo of my coding workflow with Ref Plans. I'm a solo developer so see below for more collaborative workflows.
# Why use Ref Plans?
* **Write and iterate on multi-PR AI plans that span multiple days** - The */plan* modes in tools like Claude or Cursor are ephemeral. Commonly I'm building a feature that should be broken down to multiple code changes and I want to write and review one cohesive plan.
* **Lower the mental load of context switching** - Managing multiple agents means context switching regularly. Plans provide a clean space to organize and clarify your thinking. When I was managing a bunch of agents ad hoc prior to Plans I felt tense and frazzled and with Ref Plans I felt noticably calmer and more relaxed.
* **Gather context and feedback from other humans** - One of the richest sources of context is the wisdom and expertise of our human teammates. Plans lets you send AI plans to teammates for comments and collaborative editing, as easily as any other web-based collaboration tool.
* **Build a rich history of all features and changes** - As you and your team do more planning in Ref, you naturally build up an knowledge base that's easily kept up-to-date of all feature decisions and code changes.
* **Background agents let you work on your phone and close your tabs** - Ref runs Claude Code as a background agent in the cloud so you can open the web app on your phone or start an agent and close browser tabs without worrying about losing state.
* **It's composible, use only the parts you want** - Ref's MCP-first architecture means you can connect use Ref's built-in Claude Code or buid custom workflows and connect any agent of your choosing.
# Options and different ways to work
Plans are intended to be flexible to match your workflow but here are a few high-level choices to make.
### (Recommended) Index your codebase with Ref and do research in the web client
Use Ref as your main driver and orchestrator. Here's my two-phase workflow which I call **Plan and Polish**.
1. Do research and context engineering in Plan. I start with my notes and ask the agent to research the codebase and breakdown in to tasks.
2. Once a plan feels good, I launch a background or cloud agent to implement it task by task. Sometimes multiple tasks in parallel.
3. As background agents finish, checkout the branch locallly to test and verify. Ask the background agent for any fixes. Checkout and test other branches while it works.
4. As tasks are finished, have my local agent open and merge PRs and update the Plan doc based on progress and ways we've diverged from the initial plan.
### Provide context from Linear or Github PRs and Issues
Lots of your context for planning lives outside the codebase, often in Linear or GitHub. Here's a Linear/GitHub Issues driven version of the same workflow.
To connect Linear, click the Linear logo button in the chat panel. To connect GitHub issues and PRs you must connect GitHub and add repos to Ref.
1. Do research and context engineering in Plan. Add Linear ticket or GitHub issue links and ask the agent to research the codebase and breakdown in to tasks.
2. Once a plan feels good, launch a background or cloud agent to implement it task by task. Sometimes multiple tasks in parallel.
3. As background agents finish, checkout the branch locallly to test and verify. Ask the background agent for any fixes. Checkout and test other branches while it works.
4. As tasks are finished, have my local agent open and merge PRs and update the Plan doc based on progress and ways we've diverged from the initial plan.
5. Have the Ref agent update Linear and GitHub based on progress.
### Connect to the MCP and do planning locally
If you prefer not to have Ref index your codebase or are out of Ref credits and don't want to buy more, you can still use Ref to manage and iterate on your Plans. The MCP server provides all the same tools to any agent of your choosing.
### Claude Code /plan hook
If you have the perfect local Claude Code setup and you just want to collaborate on Plans more easily, we got you! Install is as simple as:
```
curl -fsSL https://api.plan.ref.tools/plugins/install/ref-plan-hook | bash
```
Note: if you are at the limit number of plans, the hook will fail silently.
## Working with a Team
There are a few ways Ref Plans get better with teams:
* Share and comment on each others plans.
* As a manager or lead, connect the MCP server and have you agent review active and recently finished plans to understand your team's state.
## Enabling agent progress reporting
When sending a plan to an agent, Ref will include instructions for how that agent can report progress. Settings for this are available in the `Webhooks` tab.
If you are running a cloud agent in a sandboxed environment with limited network access (eg. Claude Code Web), make sure to update your Cloud Environment to allow network access to `https://api.plan.ref.tools`
# New tiers and prices
This new launch comes with an update to Ref's pricing. Since Ref credits can now be used for AI generation, we're adding tiers with more credits at discounted prices for heavy users. See [Pricing](/usage/pricing) for the current lineup.
**There will be no price changes to existing subscriptions.** Existing Basic and Team subscriptions will continue to get 1000 credits for \$9/mo and will have Free tier limits for indexing and Plans.
Extra usage now costs \$10 per 1000 credits.
# Roadmap
* **WYSIWYG Editor** - There is so much work I'd like to do to make the editor experience better. The highest priority is a beautiful WYSIWYG editor.
* **MCP Client** - You should be able to connect other MCP servers to Ref's background agent.
* **Main app integation** - Plans is almost an entirely separate app from the classic Ref MCP server. It needs to be integrated and included in landing pages and docs etc
* **Custom HTTP Endpoint Agents** - I'd like to make it easier to connect to any agent platform.
Let me know what else should be on there!
# Questions?
Email: [matt@ref.tools](mailto:matt@ref.tools)
Discord: [https://discord.gg/dUuz5V2TM3](https://discord.gg/dUuz5V2TM3) (tag @mjd)
# Review Requests
Source: https://docs.ref.tools/plans/collaboration/reviews
PR-style review workflow for plans.
Ref Plans supports a PR-style review workflow so you can get structured feedback on your plans before sending them to agents.
## How it works
1. **Request a review** — The plan owner requests a review by entering a reviewer's email address
2. **Reviewer is notified** — The reviewer receives an email notification and sees an unread indicator in their sidebar
3. **Open in review mode** — When the requested reviewer opens the plan, they land directly in review mode instead of a normal read view
4. **Review the plan** — The reviewer reads through the plan and either:
* **Approves** the plan — signals it's ready for implementation
* **Requests changes** — signals the plan needs more work
5. **Iterate** — If changes are requested, the owner updates the plan and re-requests review
6. **Withdraw** — A reviewer can withdraw their review at any time
## Review statuses
| Status | Meaning |
| ----------------- | -------------------------------------------- |
| Review requested | Waiting for the reviewer to look at the plan |
| Approved | The reviewer has approved the plan |
| Changes requested | The reviewer wants changes before approving |
When an agent requests a review with the `Comments` MCP tool's `request_review` action or waits on one with `AwaitReview`, the tool result includes a direct link to the review, not just the review status.
## Access and permissions
Requesting a review automatically grants the reviewer **write access** to the plan. This lets them leave inline comments and suggest edits directly.
Reviewer replies and comment threads also appear in the plan's sidebar, so feedback stays available in a persistent thread list as well as inline in the document.
## Email notifications
Both the reviewer and the plan owner receive email notifications:
* **Reviewer** gets notified when a review is requested
* **Owner** gets notified when a review is submitted (approved or changes requested)
You can configure notification preferences in your account settings to control which emails you receive.
# Sharing Plans
Source: https://docs.ref.tools/plans/collaboration/sharing
Share plans with teammates via links, email, or team visibility.
Ref Plans offers several ways to share your work with others.
## Link sharing
Toggle on **link sharing** from the Share button in the plan header. Anyone with the link can view and edit the plan — no account required for viewing.
This is the fastest way to share a plan for quick feedback.
## Email-based access
Add specific people by email from the Share modal:
1. Click the **Share** button in the plan header
2. Enter an email address
3. The recipient receives an invitation email with a link to the plan
4. They get edit access once they sign in
## Team visibility
For plans created under a team, you can control how the plan appears to other team members:
* **Personal** — Only you see the plan in your sidebar. Other team members won't discover it through search or browsing.
* **Shared** — The entire team can discover the plan in their sidebar and search results.
**Note:** Team visibility only controls sidebar and search discoverability. Team members who have a direct link can always access the plan regardless of the visibility setting.
## How to share
1. Open your plan
2. Click the **Share** button in the plan header
3. Choose your sharing method:
* Toggle **link sharing** for open access
* Add emails for targeted access
* Set **visibility** to control team discoverability
# Team Plans & Visibility
Source: https://docs.ref.tools/plans/collaboration/team-visibility
Manage plan visibility and discoverability within your team.
When you create a plan under a team, you control how visible it is to other team members.
## Creating team plans
When creating a new plan, you can choose to create it under your personal account or under a team you belong to. Team plans share the team's credit pool and are subject to team visibility settings.
## Visibility settings
Each team plan has a visibility setting:
* **Personal** — The plan appears only in your sidebar. Other team members won't find it through browsing or search, but they can still access it with a direct link.
* **Shared** — The plan appears in every team member's sidebar and shows up in search results. This is how you make a plan discoverable to the whole team.
You can change the visibility setting at any time from the plan header.
## Default visibility
You can set your default visibility preference in your account settings. This controls whether new team plans start as personal or shared.
## Notification preferences
Team plans support email notifications for collaborative activity:
| Event | Description |
| ---------------- | --------------------------------------- |
| Comments | Someone comments on your plan |
| Replies | Someone replies to your comment |
| Review requests | Someone requests your review |
| Review responses | A reviewer approves or requests changes |
Configure these in your notification preferences to stay informed without getting overwhelmed.
## Working with a team
# Ref vs Markdown in the Repo
Source: https://docs.ref.tools/plans/comparison/markdown-in-repo
How Ref plans complement README files, design docs, ADRs, and agent instructions.
Looking for an alternative to managing engineering specs in repo Markdown, READMEs, design docs, `AGENTS.md`, or `CLAUDE.md`? Teams often put planning docs in the repo because it is close to the code, but markdown files were not built for cross-functional spec review, rich planning, or the plan -> do -> plan rhythm that AI-assisted engineering creates. Ref is built for teams doing more planning and spec review: a focused place for engineers and cross-functional partners to review the plan, launch coding agents, and track the resulting PRs.
## Snapshot
| | Markdown in the Repo | Ref |
| ---------------- | ----------------------------------------------- | ----------------------------------------------------------------------------- |
| Best for | Versioning plans with the code | Cross-functional collaboration and orchestration |
| ⭐ Collaboration | Static artifact plus PR comments | Comments, review mode, rich content, agent threads, and progress updates |
| Format | Text-only markdown files | Rich plans with images, diagrams, widgets, comments, and agent threads |
| Access | Requires repo access and comfort working in Git | Shareable with engineers, PMs, designers, and other cross-functional partners |
| Repo scope | Tied to one repository | Works across repos, teams, and pre-repo ideas |
| Agent handoff | Agents read files after you point them there | Agents launch from the plan and report back to it |
| Long-term record | Versioned with the codebase | Can graduate settled decisions into repo docs |
## Repo Docs vs Live Plans
Markdown in the repo is valuable. READMEs, `/docs`, design docs, ADRs, `AGENTS.md`, and `CLAUDE.md` keep durable knowledge close to the code and make it available to people and agents later.
Ref solves a different part of the workflow: the live, collaborative planning phase before the implementation PR exists.
### Markdown in the Repo's Approach
Committed markdown gives engineering teams a versioned record.
**Strengths:**
* Lives next to the code it describes
* Reviewed, versioned, and searchable through normal Git workflows
* Great for stable decisions, onboarding docs, architecture records, and agent instructions
**Limitations for in-flight work:**
* It is often reviewed after or alongside the code change, when much of the implementation direction is already set
* Collaboration happens through commits and PR comments rather than a dedicated planning review flow that cross-functional partners can easily join
* Markdown is text-only, while in-flight planning often benefits from images, diagrams, prototypes, and richer context
* A repo document is naturally scoped to that repo, which can be awkward for cross-repo or pre-repo work
* Agent launch, progress reporting, and PR tracking require separate tooling or manual coordination
### Ref's Approach
Ref puts the plan before the diff. The team can discuss scope, architecture, risks, and task breakdown while the work is still cheap to reshape, and cross-functional collaborators can participate without living inside the repo.
Plans are live workspaces for in-flight engineering:
1. **Front-loaded decisions** - Review the plan before agents or people start changing files, instead of discovering disagreement in the implementation PR.
2. **Cross-functional collaboration** - PMs, designers, support, and operators can review the same plan as engineers, without needing repo access or a Git workflow.
3. **Rich context** - Plans can include images, diagrams, widgets, comments, and agent threads alongside the written plan.
4. **Cross-repo scope** - A plan can cover multiple repos, a new repo that does not exist yet, or a product decision that has not been mapped to code.
5. **Agent-native execution** - Agents launch from the plan, read it as context, ask questions there, and report PRs back to the same workspace.
## Why Ref Wins for This Job
**Earlier alignment:** Repo markdown is usually part of the same change set as the code. Ref plans are reviewed before the diff, so teams can agree on the shape of the work first.
**Cross-functional collaboration:** Ref plans are accessible to the people who need to shape the work, not only the people who live in the repo. Product, design, support, and engineering can comment on the same plan before implementation starts.
**A rich workspace, not only an artifact:** Ref keeps images, diagrams, widgets, comments, review state, agent threads, progress updates, and PR links together while the work is happening.
**Better fit for multi-repo work:** A single plan can coordinate work across services, apps, docs, and infrastructure without forcing the plan into one repository.
**Direct agent orchestration:** Ref does not just tell agents what to read. It can launch agents, pass the plan as context, and receive updates back through MCP tools.
**Designed to compose with repo docs:** This is not either/or. Once decisions settle, the durable parts can graduate into README files, ADRs, `/docs`, or agent instruction files so the codebase keeps the long-term record.
## Learn more
Learn more about [writing your first plan](/plans/getting-started/your-first-plan), [best practices for plan quality](/plans/getting-started/best-practices), and [multi-agent orchestration](/plans/workflows/multi-agent).
# Ref vs Notion & Google Docs
Source: https://docs.ref.tools/plans/comparison/notion-google-docs
Why general-purpose document tools are different from Ref's plan-to-agent workflow.
Looking for a Notion alternative or Google Docs alternative for engineering specs, planning, or spec review? Teams often start there because those tools are familiar document editors, but they were not built for the plan -> do -> plan rhythm that AI-assisted engineering creates. Ref is built for teams doing more planning and spec review: a focused place for engineers and cross-functional partners to review the plan, launch coding agents, and track the resulting PRs.
## Snapshot
| | Notion & Google Docs | Ref |
| ------------------ | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| Best for | Full-featured document editing for many kinds of teams and docs | Focused engineering plans that drive agent implementation |
| Scope | Broad editor features for writing, publishing, databases, wikis, and general collaboration | Scoped to the engineering plan -> agent -> PR loop |
| Developer workflow | Comments, suggestions, and collaborative editing | Comment -> review -> resolve workflow modeled after PR review |
| Codebase awareness | Manual links, pasted snippets, or context you add yourself | Reads connected repos to research and ground plans in your code |
| Agent handoff | Copy a doc or prompt into an external agent | Launch and track Cursor, Devin, Codex, Claude Code, and more from the plan |
| Progress tracking | Separate from the doc unless you build a custom process | Agent status, updates, and PR links flow back into the plan |
## General Docs vs Engineering Plans
Notion and Google Docs are excellent document editors. They have broad feature sets for writing, publishing, databases, wikis, and general collaboration across many kinds of teams. Ref is intentionally narrower: it is scoped specifically for engineers moving work through the plan -> agent -> PR loop.
### Notion and Google Docs' Approach
Notion and Google Docs give teams familiar, full-featured document editing surfaces.
**Strengths:**
* Fast collaborative editing for prose and specs
* Flexible formatting, comments, and sharing
* Broad document-editor features that support many non-engineering workflows
* Strong fit for evergreen company docs, meeting notes, and broad knowledge bases
**Limitations for this workflow:**
* Many document-editor features are useful in other contexts but unnecessary for engineering planning and agent orchestration
* Comments and suggestions are not connected to an engineering review state, task handoff, or PR outcome
* The document does not know your codebase unless someone manually pastes links and snippets
* Coding agents do not launch from the doc or report progress back into it by default
### Ref's Approach
Ref treats the plan as the live workspace for in-flight engineering work. It does not try to be a general document editor; it focuses on the pieces engineers need to review decisions, start agents, and track what comes back.
Ref emphasizes three pieces that general-purpose docs do not try to own:
1. **Developer workflow** - Ref's comment -> review -> resolve loop works more like a PR review than an open-ended document thread. Feedback can be tied to plan changes before implementation starts.
2. **Codebase indexing** - Ref reads connected repos, researches existing patterns, and grounds the plan in your actual code instead of relying only on manually pasted context.
3. **Coding-agent integration** - Launch Cursor, Devin, Codex, Claude Code, and more from the plan. Agents read the plan as context, work from the same source of truth, and report progress back through MCP tools.
## Why Ref Wins for This Job
**Plan review before implementation:** Ref gives teams a place to review the important decisions before a diff exists. That moves alignment earlier, when it is cheaper to change direction.
**Code-aware planning:** Because Ref can read your connected repos, plans can reference real file paths, architecture, APIs, and existing patterns. The plan starts closer to the code the agent will change.
**Agent-native handoff:** The same document that captures the decision can launch the implementation agent. There is less copy/paste between a planning doc, a chat thread, and a PR.
**Progress comes back to the source of truth:** Agents can send status, questions, and PR links back to the plan, keeping the coordination surface in one place.
**Scoped for engineers:** Notion and Google Docs remain great tools for prose and general docs. Ref is deliberately scoped to collaborative engineering plans that become agent work and PRs, without carrying a broad document editor's full feature surface into that workflow.
## Learn more
Learn more about [writing your first plan](/plans/getting-started/your-first-plan), [reviewing plans](/plans/collaboration/reviews), and [orchestrating multiple agents](/plans/workflows/multi-agent).
# Best Practices
Source: https://docs.ref.tools/plans/getting-started/best-practices
How to write plans that get great results from coding agents.
## TLDR
1. **Start with a clear outline** — Be specific about what to build, include constraints, and reference existing patterns.
2. **Let the agent research** — Don't try to write perfect tasks yourself. Give the agent your intent and let it research the codebase.
3. **Review before launching** — Read through the agent's proposed tasks and implementation steps. Catch issues early.
## Plan structure
A good plan follows this structure:
1. **Summary** — One or two paragraphs describing what you're building and why.
2. **Relevant Files** — Key files the agent should read to understand the existing codebase patterns.
3. **Relevant Docs** — Links to external documentation, API references, or design specs.
4. **Tasks** — Each task has:
* A clear title
* Implementation steps (specific enough that an agent can follow them)
* Verification criteria (how to confirm the task is done correctly)
See [Rich Content](/plans/getting-started/rich-content) for the full syntax for collapse blocks, HTML widgets, and other rich plan content.
## Tips for writing good outlines
**Be specific about what to build.** "Add dark mode" is vague. "Add a dark mode toggle to the settings page that persists the user's preference in localStorage and applies a dark theme using our existing Tailwind dark: classes" gives the agent something to work with.
**Include constraints.** If there are libraries you want to use (or avoid), performance requirements, or compatibility needs, say so up front.
**Reference existing patterns.** If your codebase has conventions, point to an example. "Follow the same pattern as `UserSettings.tsx` for the new component" saves a lot of back-and-forth.
## Iterative refinement
Plans are collaborative documents. Use comments in the chat panel to:
* Ask the agent to dig deeper into a specific area
* Request changes to the task breakdown
* Add context you forgot in the initial outline
* Get the agent to update tasks based on what you learned during implementation
## When to use multiple plans vs. multiple tasks
**Multiple tasks in one plan** when the work is part of a single coherent feature or change. The tasks share context and should be understood together.
**Multiple plans** when the work is independent. Different features, different areas of the codebase, or different timelines. Each plan is self-contained.
## Using Manual tool topics
Ref's agent has built-in knowledge about plan structure and workflows. You can use these topics in the chat panel via the `Manual` tool:
* **`structure-a-plan`** — Ask the agent to organize your rough notes into a well-structured plan
* **`update-a-plan`** — Ask the agent to revise the plan based on new information or progress
* **`read-code-or-docs`** — Guidance on researching code and documentation using Ref tools before writing or updating plans
* **`html-widgets`** — Guidance for using sandboxed HTML widgets for wireframes, dashboards, and prototypes
* **`planning-guidance`** — Guidance on when to draft a Ref plan, request a review, and wait for the verdict
### Role-based topics
These topics are primarily used by the system during [multi-agent orchestration](/plans/workflows/multi-agent), but you can reference them directly too:
* **`role-orchestrator`** — Workflow guidance for orchestrator agents managing teams of implementation and review agents. Covers how to launch agents, coordinate via messaging, and update the plan after merges.
* **`role-implementer`** — Workflow guidance for coding agents creating PRs. Covers rules for implementation agents: focus on code, message parent with PR URL when done, don't update the plan.
* **`role-reviewer`** — Workflow guidance for agents reviewing PRs. Covers how to use GitHub tools (`ReadPR`, `ReviewPR`, `MergePR`) to review diffs, approve, and report results to the orchestrator.
## Install the MCP server in all your agents
For the best results, install the Ref Plans MCP server in every coding agent you use — Cursor, Claude Code, Devin, and any others. This ensures:
* **Full plan context** — Agents can read the plan directly instead of relying on a pasted prompt snippet
* **Progress updates** — Agents can update the plan with progress and mark tasks complete as they work
* **Built-in guidance** — Agents can use the `Manual` tool for workflow guidance
* **Orchestration support** — Agents can communicate with the orchestrator via `SendMessage` during multi-agent workflows
Without the MCP server, agents only see the initial prompt you send them. With it, they have access to the full plan, can report back, and can coordinate with other agents.
See the [installation guide](/plans/install/index) for setup instructions for each agent.
Different ways to use Ref Plans.
Connect Ref Plans to your tools.
# Overview
Source: https://docs.ref.tools/plans/getting-started/intro
Ref Plans in one page.
Ref Plans is the shared source of truth for AI-generated software: the place teams create the plan before code gets written, review the decisions that matter, and keep humans and agents aligned while the work is in flight.
AI coding makes individual engineers faster, but it can make the team slower when review cannot keep up with everything people and agents are building. Ref closes that gap by moving alignment earlier: review the plan before the diff, then let agents build with the context already agreed on.
For leaders, the pain is that review cannot keep up; Ref gives the team a shared place to align on the plan before the diff. For individual engineers, AI velocity creates brain-fry — too many changes, too little context, too many places to look — and Ref keeps the work understandable.
## How it works
Start with your notes, a Linear ticket, a GitHub issue, or just a rough idea. Drop it into a new plan at [plan.ref.tools](https://plan.ref.tools).
Ref's agent researches your codebase, reads relevant files, and breaks your outline into structured tasks with implementation steps and verification criteria.
When you're happy with the plan, send individual tasks to Claude Code, Cursor Background Agents, Codex, Devin, or any other agent. They report progress back to Ref as they work.
## Why use Ref Plans?
* **Planning is not polishing** — Writing the plan is where you decide what should happen; polishing the diff is too late to discover the team disagreed on the approach.
* **Engineering is deciding what matters** — You make the decisions that shape the work, and agents fill in the implementation details around them.
* **Engineering is multiplayer by default** — Plans give teammates, reviewers, and agents one shared workspace for comments, review, progress, and handoff.
* **The doc is the state; chat is the action** — The plan stays as the primary focus of the work, while AI threads help research, refine, launch agents, and report progress back.
## FAQ
**How is this different from Notion or Google Docs?**
Ref is built for the developer workflow: comments become reviewable and resolvable like a PR, Ref reads your repos to ground the plan, and coding agents launch and report progress from the doc. [See the full comparison.](/plans/comparison/notion-google-docs)
**How is this different from markdown in the repo?**
Repo markdown usually lands after code and gets reviewed with the diff; a Ref plan front-loads decisions before the diff and stays a live workspace during in-flight work. [See the full comparison.](/plans/comparison/markdown-in-repo)
**Is this session logging?**
No. Ref pulls the key decisions out front so human eyes get on them early, instead of archiving an LLM summary no one reads.
**Is this agent memory/skills?**
No. Decisions stay reviewable in refs that agents read as context; this is not auto-generated skills.
Create your first plan and send it to an agent.
How to write plans that get great results.
# Rich Content
Source: https://docs.ref.tools/plans/getting-started/rich-content
Add images, diagrams, interactive widgets, and collapsible detail sections to your plans.
Ref Plans support more than plain markdown. Use rich content when screenshots, diagrams, prototypes, or long supporting details make the plan easier to understand.
## Images
Drag an image file onto the doc or paste one from your clipboard to insert it. Standalone images with no explicit width render at most about 480px tall, based on their intrinsic dimensions, and scaled-down images are centered so smaller screenshots do not hug the left edge. Existing docs get this cap automatically; nothing needs to be rewritten. Click an image to open it in a lightbox for the full-size view.
Click below an image to add or edit its caption. Drag a corner handle to resize a standalone image. Click an image to select it; press **Backspace** to delete the selected image.
Two or more image lines with no blank line between them render side by side as one grid, with up to three equal-width cells per row before wrapping. This uses normal markdown image syntax, so the same lines stay portable and render as stacked images on GitHub.
```markdown theme={null}
```
Add a blank line between image lines to split them back into standalone blocks.
```markdown theme={null}
```
For agents, the caption is what they see inline as a lightweight placeholder on every read, and agents can view the actual pixels or upload new images via the Ref Plans MCP server tools.
When an agent already has an image URL, such as a short-lived Figma MCP asset URL like `https://www.figma.com/api/mcp/asset/...`, it can call `upload_media` with `url` to let the server fetch and store the image. That returns a `mediaId`, which the agent then passes to `insert_media` with the target line and optional alt text.
If the agent has raw image bytes instead, it can use the signed-URL flow: call `upload_media` with `mimeType`, PUT the bytes to the returned `uploadUrl`, then call `insert_media` with the same `mediaId`.
`insert_media` also accepts an optional `displayWidth` integer from 120 to 2000. It sets the rendered width in pixels for a standalone image and writes the same `w` URI parameter that the editor's drag-resize handle writes, such as ``. `displayWidth` is ignored for images inside a grid, where cells are equal-width; omit it when you want the default height cap.
To build a browsable layout, call `insert_media` at successive `afterLine` values so the image lines land adjacent and form a grid. Use `displayWidth` when you want one standalone image at a specific size.
## Mermaid diagrams
Fenced ` ```mermaid ` code blocks render as live diagrams inline. They include zoom and expand controls, and their styling is theme-aware so diagrams match light and dark mode.
```mermaid theme={null}
flowchart TD
A[Write rough idea] --> B[Ref drafts a plan]
B --> C{Ready?}
C -- Yes --> D[Launch agents]
C -- Not yet --> E[Comment and refine]
E --> B
```
## HTML widgets
Fenced ` ```html-ref ` code blocks render as sandboxed, interactive HTML. They are useful for wireframes, dashboards, and prototypes right inside the plan.
Individual DOM nodes inside an HTML widget can be commented on directly, so reviewers can leave feedback on the exact part of a prototype or visualization they mean.
```html-ref theme={null}
Launch checklist
Review the plan, then start agents.
```
## Collapse blocks
Use collapse blocks for long detail sections, like big file lists, that should default to collapsed.
```mdx theme={null}
:::collapse
## Files — 12 files, 4 directories
Mostly in `src/components/` and `src/lib/`
:::
- `src/components/Editor.tsx` - root editor component
- `src/lib/wysiwygPlugin.ts` - decoration engine
:::end
```
`:::collapse` opens the block. Everything between `:::collapse` and the bare `:::` is the header region: it is always visible, editable markdown, and should usually start with a heading like `## Files — 12 files, 4 directories`.
Everything between the bare `:::` and `:::end` is the body region. It is appended below the header when expanded and hidden when collapsed.
A collapse block must close with `:::end` or it renders as plain text.
Agents write Mermaid diagrams, HTML widgets, and collapse blocks automatically when they are relevant, such as auto-collapsing long file lists. Ask Ref for a wireframe/diagram to discover widgets.
# Your First Plan
Source: https://docs.ref.tools/plans/getting-started/your-first-plan
Get Ref Plans running at full power in about ten minutes.
In this guide you'll connect a repo, plan a feature with AI, and hand off the work to coding agents that open PRs for you. It takes about ten minutes.
By the end you'll have a connected repo, a configured agent, and a clear path from rough idea to merged code.
Create an account at [plan.ref.tools](https://plan.ref.tools). You'll land on a blank doc — your space to think through what you want to build.
Link a GitHub repo so Ref can read your code and write plans that match your architecture.
1. Go to [ref.tools/resources](https://ref.tools/resources?tab=github)
2. Click **Connect GitHub** and authorize Ref
3. Select the repos you want to index and click **Add to Ref**
Once indexed, Ref can read files, find existing patterns, and reference them when structuring your tasks.
Choose which coding agent Ref should use to implement your tasks.
1. Open **Settings** (gear icon)
2. Click the **Agents** tab
3. Select an agent and follow the setup instructions below
**1. Add your API key**
Paste your **Cursor** API key in the Agents settings tab. Get one from [cursor.com/dashboard](https://cursor.com/dashboard?tab=cloud-agents) under the **Cloud Agents** tab.
Installing the Ref Plans MCP server lets Cursor read, write, and collaborate on plan documents. It's optional for single-agent workflows but required for [multi-agent orchestration](/plans/workflows/multi-agent).
**Add the MCP server**
Open **cursor.com**, click **MCPs**, click the `+` button and select `Custom MCP` then fill in the form or json as follows.
```json theme={null}
{
"mcpServers": {
"ref-plan": {
"type": "http",
"url": "https://api.plan.ref.tools/mcp",
"headers": {
"x-ref-api-key": "YOUR_REF_API_KEY"
}
}
}
}
```
Replace `YOUR_REF_API_KEY` with your key from [ref.tools/keys](https://ref.tools/keys).
**Configure security rules**
Cursor's cloud agents run in a sandbox that blocks external network requests by default. You need to allowlist `api.plan.ref.tools` so the agent can reach the MCP server.
In the Cursor dashboard, go to **Cloud Agents > Security Rules** and add `api.plan.ref.tools` to the allowed domains.
See the full [Cursor MCP install guide](/plans/install/cursor) for details.
**1. Add your API key**
Paste your **Devin** API key in the Agents settings tab. Get one from [app.devin.ai/settings/api-keys](https://app.devin.ai/settings/api-keys).
Installing the Ref Plans MCP server lets Devin read, write, and collaborate on plan documents. It's optional for single-agent workflows but required for [multi-agent orchestration](/plans/workflows/multi-agent).
**Add the MCP server**
In the Devin dashboard, go to [Settings > MCP Marketplace](https://app.devin.ai/settings/mcp-marketplace) and click **Add MCP Server**:
1. **Name:** `ref-plan`
2. **URL:** `https://api.plan.ref.tools/mcp`
3. Add a header `x-ref-api-key` with your API key from [ref.tools/keys](https://ref.tools/keys)
4. Click **Enable**
**Configure security rules**
Devin runs in a sandboxed environment. If your workspace has network restrictions, ensure `api.plan.ref.tools` is allowed. Devin typically permits MCP server URLs automatically once enabled.
See the full [Devin MCP install guide](/plans/install/devin) for details.
**1. Add your API key**
Paste your **Warp API key** (starts with `wk-...`) in the Agents settings tab. In the Warp desktop app, open **Settings > Platform** and create an API key.
* **Environment ID** (optional) — most users with a single environment can leave this blank.
Installing the Ref Plans MCP server lets Warp read, write, and collaborate on plan documents. It's optional for single-agent workflows but required for [multi-agent orchestration](/plans/workflows/multi-agent).
See the [MCP install docs](/plans/install/index) for step-by-step setup. If your environment restricts outbound network access, ensure `api.plan.ref.tools` is allowed.
**1. No API key needed**
These work as **launcher** agents — Ref generates a prompt with embedded webhook commands. You paste it into the agent yourself, and it reports progress back via the webhooks.
Supported launchers:
* Claude Code Web
* Codex (Cloud and Desktop)
* Conductor
* Factory
* Windsurf
* Zed
* GitHub Copilot
* Cursor Desktop
Installing the Ref Plans MCP server lets these agents read, write, and collaborate on plan documents directly. It's optional for single-agent workflows but required for [multi-agent orchestration](/plans/workflows/multi-agent).
See the [MCP install docs](/plans/install/index) for step-by-step setup instructions for your agent.
No need for perfect formatting — just get your ideas down:
* A rough description of the feature or bug
* Links to a Linear ticket or GitHub issue
* A schema, API shape, or data model
* Bullet points, stream of consciousness, whatever gets it across
This is your thinking space. Get everything important out of your head and onto the page.
If you want to pull in context from Linear, Asana, or GitHub Issues, you'll need to connect those first — see the [Integrations guide](/plans/integrations/overview) for setup.
Open the chat panel and ask Ref to turn your notes into tasks. For example:
```
Research the codebase and break this into tasks with
implementation steps and verification criteria.
```
Ref reads through your indexed repos, finds the patterns that matter — auth flows, DB models, API routes — and turns your notes into concrete tasks with file paths and verification steps. Ask it to split a task, add more detail, or reconsider an approach until the plan feels right.
Once the draft is down, use comments to leave feedback or tag teammates for review. Ref can address comments directly, updating the plan based on what you and your team surface.
When your tasks are ready, tell Ref to start implementing. You can pick specific tasks or hand off the whole plan:
```
Implement tasks 1-3.
```
```
Implement the plan.
```
Ref spins up a separate coding agent for each task, pre-loaded with the task details, file references, and repo context. Multiple tasks run in parallel, each on its own branch.
You can keep working while implementation runs. Progress flows back automatically — watch status updates come in, and continue refining upcoming tasks.
When a task finishes, a PR appears directly in your plan. You can provide higher-level feedback as work progresses, or enable **auto-merge** to let Ref review and merge PRs on your behalf.
## What's next?
Learn how to write plans that get great results.
Set up fully automated multi-agent orchestration.
Connect Linear or GitHub issues for richer context.
Using Claude Code, Codex, or another local agent? Install the MCP server to connect them to Ref.
# Amp
Source: https://docs.ref.tools/plans/install/amp
Connect Amp to Ref Plans.
How to set up the Ref Plans MCP server with [Amp CLI](https://ampcode.com/manual#mcp).
## Install
Run the `amp` install command:
```
amp mcp add RefPlan https://api.plan.ref.tools/mcp --header "x-ref-api-key: "
```
You can find your API key at [ref.tools/keys](https://ref.tools/keys).
For plan-specific mode:
```
amp mcp add RefPlan "https://api.plan.ref.tools/mcp?plan=" --header "x-ref-api-key: "
```
## Verify
Run the command:
```
amp mcp doctor
```
You should see:
```
➜ amp mcp doctor
User settings:
Workspace settings:
RefPlan (user settings): connected
```
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Antigravity
Source: https://docs.ref.tools/plans/install/antigravity
Connect Antigravity to Ref Plans.
[Antigravity MCP docs](https://antigravity.google/docs/mcp)
You can find your Ref API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open Agent Chat.
2. Click the `...` Additional options button and select `MCP Servers`
3. Click `Manage MCP Servers`. This should open an editor tab called `Managed MCPS`
4. Update `mcp_config.json`
```mcp_config.json theme={null}
{
"mcpServers": {
"ref-plan": {
"serverUrl": "https://api.plan.ref.tools/mcp",
"headers": {
"x-ref-api-key": ""
}
}
}
}
```
For plan-specific mode, use `"serverUrl": "https://api.plan.ref.tools/mcp?plan="`.
## Verify
Go back to the `Manage MCP Servers` page and hit `Refresh`
You should see ref-plan with a green dot.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Augment
Source: https://docs.ref.tools/plans/install/augment
Connect Augment to Ref Plans.
[Augment MCP docs](https://docs.augmentcode.com/setup-augment/mcp)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open `Augment Settings`. This can be done either from the VSCode command palette or the gear icon in Augment.
2. Under `Tools`, click `Add remote MCP`.
3. Update the settings to `Connection Type = HTTP` and `Authentication Type = Header`.
4. Fill in `Url` as `https://api.plan.ref.tools/mcp` and add a header `x-ref-api-key` with your API key as the value.
5. Click `Add`.
For plan-specific mode, use `https://api.plan.ref.tools/mcp?plan=` as the URL.
## Verify
See the RefPlan server present with a green dot.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# ChatGPT
Source: https://docs.ref.tools/plans/install/chatgpt
Connect ChatGPT to Ref Plans.
[ChatGPT MCP docs](https://platform.openai.com/docs/mcp)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open `Settings`
2. Click `Apps & Connectors`
3. If you are not already in developer mode, scroll to the bottom and click `Advanced settings` and toggle on Developer mode.
4. Click the `Create` button in the top right of the settings modal.
5. Fill in Name as `RefPlan`
6. Fill in MCP Server URL `https://api.plan.ref.tools/mcp?apiKey=`
7. Under Authentication select `No authentication`. Your API key is set in the server url already.
8. Check the `I understand` box and click Create.
For plan-specific mode, use `https://api.plan.ref.tools/mcp?plan=&apiKey=` as the URL.
## Verify
1. To use Ref Plans, click the `+` button in the left of the prompt input, go to `More` and select `RefPlan`.
2. Ask the agent to list your plans or read a specific plan.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Claude Code
Source: https://docs.ref.tools/plans/install/claude-code
Connect Claude Code to Ref Plans.
How to set up the Ref Plans MCP server with [Claude Code](https://www.claude.com/product/claude-code).
## Install
Run the `claude` install command:
```
claude mcp add --transport http RefPlan https://api.plan.ref.tools/mcp --header "x-ref-api-key: "
```
You can find your API key at [ref.tools/keys](https://ref.tools/keys).
For plan-specific mode, append the plan ID:
```
claude mcp add --transport http RefPlan "https://api.plan.ref.tools/mcp?plan=" --header "x-ref-api-key: "
```
## Verify
Run the command:
```
claude mcp list
```
You should see:
```
➜ claude mcp list
RefPlan: https://api.plan.ref.tools/mcp (HTTP)
```
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Claude Desktop and Web
Source: https://docs.ref.tools/plans/install/claude-desktop
Connect Claude Desktop and Web to Ref Plans.
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open `Settings`
2. Click `Connectors`
3. Click `Add custom connector`
4. Fill in Name as `RefPlan`
5. Fill in Remote MCP Server URL `https://api.plan.ref.tools/mcp?apiKey=`
For plan-specific mode, use `https://api.plan.ref.tools/mcp?plan=&apiKey=` as the URL.
## Verify
Start a new chat and ask the agent to list your plans or read a specific plan.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Cline
Source: https://docs.ref.tools/plans/install/cline
Connect Cline to Ref Plans.
[Cline MCP docs](https://docs.cline.bot/mcp/configuring-mcp-servers)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open Cline plugin in VSCode and click the `MCP Servers` button at the top.
2. Select the `Configure` tab and click `Configure MCP Servers`. This should open `cline_mcp_settings.json`.
3. Update `cline_mcp_settings.json`
```
{
"mcpServers": {
"RefPlan": {
"command": "npx",
"args": ["ref-tools-mcp@latest", "--plan-server"],
"env": {
"REF_API_KEY": "",
"REF_PLAN_SERVER": "https://api.plan.ref.tools/mcp"
}
}
}
}
```
For plan-specific mode, set `"REF_PLAN_SERVER": "https://api.plan.ref.tools/mcp?plan="`.
## Verify
Open a new chat with Cline and ask the agent to list your plans or read a specific plan.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Codex CLI
Source: https://docs.ref.tools/plans/install/codex
Connect Codex CLI to Ref Plans.
[Codex MCP install docs](https://github.com/openai/codex/blob/main/docs/config.md#connecting-to-mcp-servers)
You can find your Ref API key at [ref.tools/keys](https://ref.tools/keys)
## Install
Codex is configured in a `config.toml` file. This typically lives at `~/.codex/config.toml`
To enable Ref Plans, update your `config.toml` to include:
```config.toml theme={null}
[mcp_servers.ref-plan]
url = "https://api.plan.ref.tools/mcp?apiKey="
```
For plan-specific mode:
```config.toml theme={null}
[mcp_servers.ref-plan]
url = "https://api.plan.ref.tools/mcp?plan=&apiKey="
```
## Verify
Run the command:
```
codex mcp list
```
You should see `ref-plan` listed with the Ref Plans MCP URL.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Cursor
Source: https://docs.ref.tools/plans/install/cursor
Connect Cursor to Ref Plans.
[Cursor MCP docs](https://cursor.com/docs/context/mcp)
You can find your Ref API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open `Cursor Settings`
2. Click `Tools & MCP`
3. Click `New MCP Server`. This will open an `mcp.json` file.
4. Update `mcp.json`
```mcp.json theme={null}
{
"mcpServers": {
"RefPlan": {
"type": "http",
"url": "https://api.plan.ref.tools/mcp",
"headers": {
"x-ref-api-key": "your-api-key"
}
}
}
}
```
For plan-specific mode, use `"url": "https://api.plan.ref.tools/mcp?plan="`.
## Verify
In `Cursor Settings` click `Tools & MCP`.
You should see RefPlan with a green dot.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Devin
Source: https://docs.ref.tools/plans/install/devin
Connect Devin to Ref Plans.
[Devin MCP Marketplace docs](https://docs.devin.ai/work-with-devin/mcp)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Log into Devin and visit [https://app.devin.ai/settings/mcp-marketplace](https://app.devin.ai/settings/mcp-marketplace)
2. Click `Add MCP Server` to add a custom server.
3. Fill in Name as `ref-plan`
4. Fill in URL as `https://api.plan.ref.tools/mcp`
5. Add a header `x-ref-api-key` with your API key as the value.
6. Click `Enable` to enable the integration.
## Verify
Open a new chat and ask the agent to list your plans or read a specific plan.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Droid CLI
Source: https://docs.ref.tools/plans/install/droid-cli
Connect Factory Droid CLI to Ref Plans.
[Droid CLI MCP install docs](https://docs.factory.ai/cli/configuration/mcp)
You can find your Ref API key at [ref.tools/keys](https://ref.tools/keys)
## Install
Start Droid
```
droid
```
Run the `/mcp` command
```
/mcp add --type http RefPlan "https://api.plan.ref.tools/mcp?apiKey="
```
For plan-specific mode:
```
/mcp add --type http RefPlan "https://api.plan.ref.tools/mcp?plan=&apiKey="
```
## Verify
Start Droid:
```
droid
```
Run the `/mcp` command in the Droid TUI
```
/mcp list
```
You should see `RefPlan` listed with the Ref Plans MCP URL.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Gemini CLI
Source: https://docs.ref.tools/plans/install/gemini-cli
Connect Gemini CLI to Ref Plans.
[Gemini CLI Docs](https://github.com/google-gemini/gemini-cli)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
Gemini CLI is configured through a `settings.json` file, typically found at `~/.gemini/settings.json`.
To enable Ref Plans, update `settings.json`:
```settings.json theme={null}
{
"mcpServers": {
"ref-plan": {
"httpUrl": "https://api.plan.ref.tools/mcp?apiKey="
}
}
}
```
For plan-specific mode, use `"httpUrl": "https://api.plan.ref.tools/mcp?plan=&apiKey="`.
## Verify
Run the command:
```
gemini mcp list
```
You should see:
```
➜ gemini mcp list
✓ ref-plan: https://api.plan.ref.tools/mcp?apiKey= (http) - Connected
```
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Goose
Source: https://docs.ref.tools/plans/install/goose
Connect Goose to Ref Plans.
[Goose Extensions docs](https://block.github.io/goose/docs/getting-started/using-extensions)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Click the `Extensions` button in the left side nav.
2. Click `Add custom extension`
3. Fill in Extension Name as `RefPlan`
4. Fill in Endpoint as `https://api.plan.ref.tools/mcp`
5. Add a Request Header `x-ref-api-key` with value being your API key.
6. IMPORTANT: make sure you hit "+ Add" next to the request header to ensure it is actually added.
7. Click `Add extension`
For plan-specific mode, use `https://api.plan.ref.tools/mcp?plan=` as the endpoint.
## Verify
Open a new chat and ask the agent to list your plans or read a specific plan.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Installation
Source: https://docs.ref.tools/plans/install/index
Install the Ref Plans MCP server in your preferred coding environment
## About the Ref Plans MCP Server
Ref Plans has its own MCP server, separate from the [Ref Context MCP server](/context/install/index). 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=
```
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 two ways:
1. **As a header**: `x-ref-api-key: YOUR_API_KEY`
2. **As a query parameter**: `?apiKey=YOUR_API_KEY`
You can find your API key at [ref.tools/keys](https://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=
```
### 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
* `upload_media` — Upload an image and receive a `mediaId`. Pass either `url` for a publicly fetchable HTTPS image URL, or `mimeType` to receive a signed `uploadUrl` for a client-side PUT. `mimeType` is required only when `url` is absent; never pass both. `request_media_upload` remains as a deprecated alias for one release.
* `insert_media` — Insert uploaded image markdown into the plan using the `mediaId` returned by `upload_media`
**General mode** adds:
* `List` — List your plans
* `Create` — Create a new plan
### Agent orchestration tools
These additional tools are available in both plan-specific and general mode:
* `LaunchAgent` — Launch a sub-agent on Cursor, Devin, Warp OZ, Conductor Cloud, 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.
`LaunchAgent` requires API keys configured for the harnesses you want to use — set up Cursor and/or Devin API keys in **Settings > Agent Settings**.
See the [multi-agent orchestration guide](/plans/workflows/multi-agent) 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](https://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](/plans/integrations/github) for setup details.
***
## Installation Guides
Choose your coding environment below to get started:
Connect Cursor to Ref Plans.
Connect Claude Code to Ref Plans.
Connect Claude Desktop and Web to Ref Plans.
Connect VS Code to Ref Plans.
Connect Antigravity to Ref Plans.
Connect Windsurf to Ref Plans.
Connect Cline to Ref Plans.
Connect Kiro to Ref Plans.
Connect Roo Code to Ref Plans.
Connect Goose to Ref Plans.
Connect Amp to Ref Plans.
Connect Augment to Ref Plans.
Connect ChatGPT to Ref Plans.
Connect Devin to Ref Plans.
Connect OpenCode to Ref Plans.
Connect Codex CLI to Ref Plans.
Connect Factory Droid CLI to Ref Plans.
Connect Gemini CLI to Ref Plans.
# Kiro
Source: https://docs.ref.tools/plans/install/kiro
Connect Kiro to Ref Plans.
[Kiro MCP configuration docs](https://kiro.dev/docs/mcp/configuration/)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open the Kiro left side panel via the Kiro ghost icon.
2. At the bottom, see the `MCP SERVERS` section and mouse over it to see the `Open MCP Config` button. This will open `mcp.json`
3. Update `mcp.json` as follows:
```json theme={null}
{
"mcpServers": {
"RefPlan": {
"url": "https://api.plan.ref.tools/mcp",
"headers": {
"x-ref-api-key": ""
},
"disabled": false
}
}
}
```
For plan-specific mode, use `"url": "https://api.plan.ref.tools/mcp?plan="`.
## Verify
1. Open the MCP Server view in the Kiro feature panel
2. You should see `RefPlan` listed with a green status indicator
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# OpenCode
Source: https://docs.ref.tools/plans/install/opencode
Connect OpenCode to Ref Plans.
[Opencode MCP docs](https://opencode.ai/docs/mcp-servers/)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Create or update an `opencode.jsonc` file in your project:
```
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"RefPlan": {
"type": "remote",
"url": "https://api.plan.ref.tools/mcp",
"enabled": true,
"headers": {
"x-ref-api-key": "YOUR_API_KEY"
}
}
}
}
```
For plan-specific mode, use `"url": "https://api.plan.ref.tools/mcp?plan="`.
## Verify
Open a new chat and ask the agent to list your plans or read a specific plan.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Roo Code
Source: https://docs.ref.tools/plans/install/roo-code
Connect Roo Code to Ref Plans.
[Roo Code MCP docs](https://docs.roocode.com/features/mcp/using-mcp-in-roo)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Click the `...` icon in the top right to expand additional menu items and select `MCP Servers`
2. Click either `Edit Global MCP` or `Edit Project MCP`.
3. Update the json file that is opened to match the following.
```
{
"mcpServers": {
"RefPlan": {
"type": "streamable-http",
"url": "https://api.plan.ref.tools/mcp",
"headers": {
"X-ref-API-Key": ""
}
}
}
}
```
For plan-specific mode, use `"url": "https://api.plan.ref.tools/mcp?plan="`.
## Verify
Open a new chat and ask the agent to list your plans or read a specific plan.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# VS Code
Source: https://docs.ref.tools/plans/install/vscode
Connect VS Code to Ref Plans.
[VSCode MCP docs](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open the VSCode command palette `Shift + Command + P (Mac)` or `Ctrl + Shift + P (Windows/Linux)`
2. Type `mcp` and select the `MCP: Add server...` action.
3. Select the `HTTP` option.
4. Enter Server URL `https://api.plan.ref.tools/mcp?apiKey=`
5. Enter Server ID `RefPlan`
For plan-specific mode, use `https://api.plan.ref.tools/mcp?plan=&apiKey=`.
## Verify
1. Open the Chat UI.
2. In the chat input box, you should see a tools icon next to the send message icon. Click it.
3. This should open the `Configure Tools` menu. You should see `MCP Server: RefPlan` with tools enabled.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Windsurf
Source: https://docs.ref.tools/plans/install/windsurf
Connect Windsurf to Ref Plans.
[Windsurf Cascade MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open the `mcp_config.json` file. This can be found at a path like `~/.codium/windsurf/mcp_config.json` or by opening Cascade Chat and clicking the `Customizations` icon (looks like a packing box) in the top right then clicking the settings button.
2. Update `mcp_config.json` as follows:
```
{
"mcpServers": {
"RefPlan": {
"command": "npx",
"args": ["ref-tools-mcp@latest", "--plan-server"],
"env": {
"REF_API_KEY": "",
"REF_PLAN_SERVER": "https://api.plan.ref.tools/mcp"
}
}
}
}
```
Alternatively, if Windsurf supports HTTP MCP servers, use:
```
{
"mcpServers": {
"RefPlan": {
"type": "http",
"url": "https://api.plan.ref.tools/mcp",
"headers": {
"x-ref-api-key": ""
}
}
}
}
```
For plan-specific mode, append `?plan=` to the URL.
## Verify
Click the Cascade Chat Customizations button and see that RefPlan is active.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Zed
Source: https://docs.ref.tools/plans/install/zed
Connect Zed to Ref Plans.
[Zed MCP docs](https://zed.dev/docs/ai/mcp)
You can find your API key at [ref.tools/keys](https://ref.tools/keys)
## Install Steps
1. Open the agent thread UI in right dock with `cmd + R`.
2. In the top right, click the `...` icon and under MCP Servers, select `Add Custom Server...`. This should open the `Add MCP Server` modal.
3. In the bottom left of the modal click `Configure Remote` server.
4. Replace the entire content of the input JSON with the following and click `Add Server`.
```json theme={null}
{
"RefPlan": {
"url": "https://api.plan.ref.tools/mcp?apiKey="
}
}
```
For plan-specific mode, use `"url": "https://api.plan.ref.tools/mcp?plan=&apiKey="`.
## Verify
1. Open a new thread in the agent thread panel and select the `...` settings icon then click `Settings`.
2. You should see RefPlan enabled in the Model Context Protocol (MCP) Servers section.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Asana
Source: https://docs.ref.tools/plans/integrations/asana
Connect Asana tasks to Ref Plans for context and status updates.
The Asana integration lets you attach Asana tasks to your plans for context and have agents update task status based on progress.
## Connect Asana
1. Go to **Settings** in Ref Plans
2. Click the **Integrations** tab
3. Find the **Asana** section
4. Enter your Personal Access Token (PAT)
5. Click **Test Connection** to verify
6. Click **Save**
You can generate a PAT from the [Asana developer console](https://app.asana.com/0/my-apps).
## Usage
Once connected, agents can work with Asana tasks in your plans.
When you provide an Asana task, the agent can:
* **Read task details** — The agent uses the task name, description, assignee, due date, and status as context when researching and structuring your plan
* **Update task fields** — As tasks are completed, the agent can update the task status, assignee, due date, and other fields
* **Add comments** — The agent can add comments to tasks to report progress or share context
## Tips
* Agents need a task GID to work with specific Asana tasks — you can find the GID in the task URL or share the task link directly in conversation
* Share Asana task links in conversation so the agent can extract the task GID automatically
* You can reference multiple tasks in a single plan if they're related
* The agent can update Asana based on progress, keeping your project management in sync
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Claude Code Web
Source: https://docs.ref.tools/plans/integrations/claude-code-web
Send tasks to Claude Code in the cloud from Ref Plans.
Claude Code Web is a webhook-based integration that lets you send plan tasks to Claude Code running in a cloud environment.
## Setup
1. Go to **Settings** in Ref Plans
2. Click the **Agent Settings** tab
3. Select the **Webhooks** tab
4. Toggle on **Claude Code Web**
## How it works
When you send a task to Claude Code Web, Ref appends progress-reporting instructions to the task prompt. These instructions include curl commands that the agent uses to report status back to Ref.
This means Claude Code Web will automatically update your plan with its progress as it works through the task.
## Cloud environment configuration
If you are running Claude Code Web in a sandboxed environment with limited network access, you must allow outbound requests to:
```
https://api.plan.ref.tools
```
Update your cloud environment settings to whitelist this URL, otherwise the agent won't be able to report progress back to Ref.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Codex
Source: https://docs.ref.tools/plans/integrations/codex
Send tasks to OpenAI Codex from Ref Plans.
Codex is a webhook-based integration that lets you send plan tasks to OpenAI Codex for implementation.
## Setup
1. Go to **Settings** in Ref Plans
2. Click the **Agent Settings** tab
3. Select the **Webhooks** tab
4. Toggle on **Codex**
## How it works
When you send a task to Codex, Ref appends progress-reporting instructions to the task prompt. These instructions include curl commands that Codex uses to report status back to Ref.
This means Codex will automatically update your plan with its progress as it works through the task.
## Cloud environment configuration
If Codex is running in a sandboxed environment with limited network access, make sure to allow outbound requests to:
```
https://api.plan.ref.tools
```
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Conductor Cloud
Source: https://docs.ref.tools/plans/integrations/conductor-cloud
Launch Conductor Cloud agents from Ref Plans.
Conductor Cloud integration lets you launch Conductor agents directly from your plans and track their progress.
This is the **API-based** harness (`api.conductor.build`). It is separate from the **Conductor** desktop deep-link launcher, which opens the Conductor desktop app via webhook-style prompts. Both can appear in Ref; configure and launch **Conductor Cloud** when you want Ref to create and track sessions through the Conductor API.
## Get a Conductor API key
1. Open [app.conductor.build/users/api-keys](https://app.conductor.build/users/api-keys)
2. Create an API key
3. Copy the key for the next step
## Connect Conductor Cloud
1. Go to **Settings** in Ref Plans
2. Click the **Agent Settings** tab
3. Select the **Conductor Cloud** tab
4. Paste your Conductor API key and use **Test** to validate it
5. Pick a **default project**
Optionally set a default agent and model. Conductor's docs recommend passing an explicit model rather than relying on defaults.
## How Conductor is organized
Conductor nests work in three layers:
**project** (1 repo) → **workspace** (1 branch, 1 git worktree, 1 cloud sandbox) → **session** (1 agent chat tab)
Sessions inside a workspace share files, branch, and running processes. A branch can be checked out in only one workspace at a time, which makes the workspace the PR unit.
## Choose a workspace mode
In the Conductor Cloud settings tab, choose how launches create workspaces:
* **New workspace per launch (default)** — Each launch gets its own branch and sandbox, matching how Cursor, Devin, and Warp OZ behave. Each agent produces its own PR.
* **Always use one workspace** — New sessions land as additional chat tabs in one configured workspace, sharing its sandbox and branch. Pick a workspace after selecting a default project.
Orchestrators fanning out parallel children should stay on **new workspace per launch**. A fixed workspace is for *sequential* work — a follow-up, a reviewer, or a specialist picking up the same branch with a warm sandbox. Several agents running at once in one workspace would share a worktree, compete for the same sandbox ports, and can only produce one PR between them.
## Launch an agent
1. Open your plan and select a task
2. Click **Launch Agent** and choose **Conductor Cloud**
3. Review the prompt — Ref pre-populates it with the task details
4. Click **Launch**
## Status tracking
Ref tracks the Conductor Cloud agent status:
* **Working** — The agent is actively implementing the task
* **Finished** — The agent has completed its work
Conductor reports only `idle`, `working`, and `error`, and has no terminal "finished" state. Ref treats a session as finished once it goes idle *after* having been observed working.
Unlike Cursor, Devin, and Warp OZ, Conductor's API exposes no PR URL, so completion notifications do not include a pull request link. The link Ref stores is Conductor's `deepLink`, which opens the Conductor desktop app.
You can monitor agent progress directly from your plan without switching to Conductor.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Cursor Background Agents
Source: https://docs.ref.tools/plans/integrations/cursor
Launch Cursor background agents from Ref Plans.
Cursor Background Agents let you launch coding agents that run in the background, directly from your plans.
## Connect Cursor
1. Go to **Settings** in Ref Plans
2. Click the **Agent Settings** tab
3. Select the **Cursor** tab
4. Enter your Cursor API key
5. Configure the repository and ref/branch you want the agent to work on
## Launch an agent
1. Open your plan and select a task
2. Click **Launch Agent** and choose **Cursor**
3. Configure the prompt — Ref pre-populates it with the task details
4. Click **Launch**
The agent will start working on your task in the background.
## Status tracking
Once launched, Ref tracks the agent's progress:
* **Working** — The agent is actively implementing the task
* **Finished** — The agent has completed its work
* **PR Created** — A pull request URL is shown when the agent creates one
Cursor reports progress back to Ref automatically, so you can monitor multiple agents from your plan.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Custom Launchers
Source: https://docs.ref.tools/plans/integrations/custom-launchers
Deep-link into Ref Plans from any tool that can construct a URL.
Custom launchers let external tools open Ref Plans directly. Build a link to `https://plan.ref.tools/new`, optionally include starting content or a first agent prompt, and send users into a new plan.
## URL pattern
Use the `/new` route with optional URL-encoded query parameters:
```text theme={null}
https://plan.ref.tools/new?content=&prompt=
```
| Parameter | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | Seeds the new plan's initial markdown content. |
| `prompt` | Sends the first chat message immediately after the plan is created. This starts an agent thread, and the plan opens focused on that thread. |
Both parameters are optional. If you omit both, Ref creates a blank untitled plan, the same as clicking **New Plan** in the UI.
## Examples
Create a blank plan:
```text theme={null}
https://plan.ref.tools/new
```
Create a plan with initial markdown content:
```text theme={null}
https://plan.ref.tools/new?content=%23%20API%20cleanup%0A%0A-%20%5B%20%5D%20Audit%20legacy%20endpoints%0A-%20%5B%20%5D%20Draft%20migration%20plan
```
Create a plan with initial content and immediately ask Ref to research it:
```text theme={null}
https://plan.ref.tools/new?prompt=Research%20this%20request%20and%20draft%20an%20implementation%20plan&content=%23%20Checkout%20performance%20issue%0A%0AUsers%20report%20slow%20checkout%20after%20the%20latest%20release.%0A%0Ahttps%3A%2F%2Flinear.app%2Facme%2Fissue%2FENG-123%2Fcheckout-performance
```
## Worked example: Linear
You can wire this pattern into any tool that can construct a URL. For Linear, add a custom link, automation, or internal workflow that builds a Ref URL from the ticket title and ticket link.
For example, start with:
```text theme={null}
prompt=Research this ticket and draft a plan
content=# ENG-123: Checkout performance
https://linear.app/acme/issue/ENG-123/checkout-performance
```
URL-encode those values and append them to `/new`:
```text theme={null}
https://plan.ref.tools/new?prompt=Research+this+ticket+and+draft+a+plan&content=%23%20ENG-123%3A%20Checkout%20performance%0A%0Ahttps%3A%2F%2Flinear.app%2Facme%2Fissue%2FENG-123%2Fcheckout-performance
```
When the user opens the link, Ref creates a new plan with the ticket title and link already in the document. It also sends the prompt as the first chat message, so the plan opens directly into an agent thread researching the ticket.
If your automation can run code, build the URL with your platform's URL encoder instead of hand-encoding strings:
```js theme={null}
const url = new URL('https://plan.ref.tools/new');
url.searchParams.set('prompt', 'Research this ticket and draft a plan');
url.searchParams.set(
'content',
`# ${ticket.identifier}: ${ticket.title}
${ticket.url}`
);
```
## Requirements
* The user must be logged in to [plan.ref.tools](https://plan.ref.tools)
* The new plan is created in the user's currently selected workspace, whether personal or team
* Both `content` and `prompt` should be URL-encoded before they are added to the link
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Custom MCP Servers
Source: https://docs.ref.tools/plans/integrations/custom-mcp
Connect your own remote MCP servers to ref-thread agents.
Custom MCP servers let you attach remote MCP tools to ref-thread agents. Connect a server once, then choose which connected servers and integrations are available to each thread.
## Connect a custom MCP server
1. Go to **Settings** in Ref Plans
2. Click the **Integrations** or **Connectors** tab
3. Add a custom MCP server with a name and URL
4. Choose an authentication method:
* **None** — Use for public or unauthenticated servers
* **Custom headers** — Add static headers, such as an API key or bearer token
* **OAuth** — Use the authorization-code flow with dynamic client registration; no manual client ID or client secret setup is required
5. Click **Verify** or **Save** to connect to the server
6. Review the tools Ref found on the server, then save the connection
Ref verifies the server before saving it. If the server is unreachable or returns an invalid MCP response, Ref rejects the connection and shows an inline error.
## Usage
After you connect a custom MCP server, choose when to attach it to a ref-thread:
1. Open a plan and start or select a ref-thread
2. In the message composer, click the **+** connectors button
3. Use the checkbox rows grouped under **MCP Servers** and **Integrations** to choose which connected tools attach to that thread's runs
4. Send your message
Connector selection is per-thread. Changing the checkboxes overrides your Settings defaults for that thread only; other threads and your defaults are unaffected.
Use **Configure Integrations** in the connectors menu to jump back to Settings when you need to add, remove, or update a connection.
## Support
| Feature | Support | Notes |
| ------------------------------------------------------ | --------------- | --------------------------------------------------- |
| Transport: Streamable HTTP | ✅ Supported | The only transport supported for custom servers. |
| Transport: stdio / legacy HTTP+SSE | ❌ Not supported | Only remote HTTP(S) servers can be added. |
| Capability: Tools | ✅ Supported | The only capability currently exercised. |
| Capability: Resources | ❌ Not supported | Not surfaced to the agent. |
| Capability: Prompts | ❌ Not supported | Not surfaced to the agent. |
| Auth: None | ✅ Supported | |
| Auth: Custom headers (API key / bearer token) | ✅ Supported | |
| Auth: OAuth 2.0 with dynamic client registration | ✅ Supported | Tokens refresh automatically. |
| Attach scope: ref-thread agents | ✅ Supported | |
| Attach scope: other harnesses (Cursor, Devin, Warp OZ) | ❌ Not supported | Those harnesses manage their own MCP configs today. |
| Sharing scope: team-shared servers | ❌ Not supported | Configs are user-scoped only, like Linear/Asana. |
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Devin
Source: https://docs.ref.tools/plans/integrations/devin
Launch Devin sessions from Ref Plans.
Devin integration lets you launch Devin sessions directly from your plans and track their progress.
## Install the Ref MCP server in Devin
Give Devin access to your plans and tasks by connecting the **Ref Plans MCP server** in Devin’s MCP marketplace (streamable HTTP endpoint `https://api.plan.ref.tools/mcp`). Full steps—URL, API key header, and plan-specific URLs—are in **[Connect Devin to Ref Plans](/plans/install/devin)**.
This will allow Devins to send messages back to a Ref agent orchestrator.
## Connect Devin
1. Go to **Settings** in Ref Plans
2. Click the **Agent Settings** tab
3. Select the **Devin** tab
4. Enter your Devin API key
## Launch an agent
1. Open your plan and select a task
2. Click **Launch Agent** and choose **Devin**
3. Review the prompt — Ref pre-populates it with the task details
4. Click **Launch**
## Status tracking
Ref tracks the Devin session status:
* **Working** — The session is actively running
* **Blocked** — The session needs input or has encountered an issue
* **Finished** — The session has completed its work
* **Expired** — The session has timed out
You can monitor session progress directly from your plan without switching to the Devin dashboard.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# GitHub Issues & PRs
Source: https://docs.ref.tools/plans/integrations/github
Connect GitHub issues and pull requests to Ref Plans.
The GitHub integration lets you attach issues and pull requests to your plans for context, and track PRs linked to plan tasks.
## Setup
GitHub integration requires connecting your GitHub account and adding repos to Ref:
1. Visit [ref.tools/resources](https://ref.tools/resources) and connect your GitHub account
2. Add the repositories you want to use with Ref Plans
Once connected, you can reference GitHub issues and PRs in your plans.
## Attaching issues and PRs
Paste a GitHub issue or PR link directly into your plan editor. The agent can read the issue details for context when researching and structuring your plan.
## PR tracking
As agents implement tasks and create pull requests, you can link those PRs to your plan:
* Use the **PR dropdown** in the plan UI to attach PRs to specific tasks
* The agent can also use the **PrLinks** tool via MCP to attach PRs programmatically
This gives you a single view of all the code changes associated with your plan.
## Tips
* Attach GitHub issues before asking the agent to research — it provides valuable context about what needs to be built
* Link PRs to tasks as agents create them to track implementation progress
* The agent can read issue comments and PR descriptions for additional context
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Linear
Source: https://docs.ref.tools/plans/integrations/linear
Connect Linear tickets to Ref Plans for context and status updates.
The Linear integration lets you attach Linear tickets to your plans for context and have agents update ticket status based on progress.
## Connect Linear
1. Go to **Settings** in Ref Plans
2. Click the **Integrations** tab
3. Select **Linear**
4. Enter your Linear API key
5. Click **Test Connection** to verify
## Usage
Once connected, click the **Linear logo** in the chat panel to attach tickets to your plan.
When you attach a Linear ticket, the agent can:
* **Read ticket details** — The agent uses the ticket title, description, and comments as context when researching and structuring your plan
* **Update ticket status** — As tasks are completed, the agent can update the corresponding Linear ticket
## Tips
* Attach tickets before asking the agent to research — it will use the ticket context to produce better plans
* You can attach multiple tickets to a single plan if they're related
* The agent can update Linear based on progress, keeping your project management in sync
Want a Ref plan to open automatically from a Linear ticket? See [Custom Launchers](/plans/integrations/custom-launchers) for the `/new?prompt&content` URL pattern.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Integrations Overview
Source: https://docs.ref.tools/plans/integrations/overview
Connect Ref Plans to coding agents and external services.
Ref Plans integrates with coding agents (where you send tasks for implementation) and context sources (where you pull planning context from).
## Cloud agents (API-based)
Cloud agents connect directly through API keys. Ref launches the agent and tracks its progress automatically — no manual intervention required. These agents can also be launched programmatically by an orchestrator agent via the [`LaunchAgent`](/plans/workflows/multi-agent) MCP tool as part of [multi-agent orchestration](/plans/workflows/multi-agent).
| Agent | Description |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| [Cursor Background Agents](/plans/integrations/cursor) | Launches a Cursor background agent via API key. Writes code, creates branches, and opens PRs. |
| [Devin](/plans/integrations/devin) | Launches a Devin session via API key. Writes code, creates branches, and opens PRs. |
| [Warp OZ](/plans/integrations/warp-oz) | Launches a Warp OZ agent via API key. Writes code, creates branches, and opens PRs. |
| [Conductor Cloud](/plans/integrations/conductor-cloud) | Launches a Conductor Cloud session via API key. Writes code and creates branches in a Conductor workspace. |
Cloud agents provide:
* **Automatic launch** — Ref starts the agent session for you
* **Status tracking** — Progress updates flow back to Ref automatically
* **Orchestration support** — Can be launched by an orchestrator agent via `LaunchAgent` with `harness: "cursor"`, `harness: "devin"`, `harness: "warp-oz"`, or `harness: "conductor-cloud"`
Configure API keys in **Settings > Agent Settings** at [plan.ref.tools](https://plan.ref.tools).
## Launcher agents (webhook-based)
Launcher agents work by appending progress-reporting instructions (curl commands) to the task prompt. You initiate the agent session yourself, and the agent reports back to Ref by executing the webhook commands included in the prompt.
| Agent | Description |
| ------------------------------------------------------ | -------------------------------------------------- |
| [Claude Code Web](/plans/integrations/claude-code-web) | Sends task to Claude Code in the cloud |
| [Codex](/plans/integrations/codex) | Sends task to OpenAI Codex |
| Cursor Local | Sends task to your local Cursor instance |
| Copy & Paste | Copies the task prompt for manual use in any agent |
Launcher agents require you to:
1. Click **Launch Agent** in the plan UI to generate the prompt
2. Start the agent session yourself (or paste the prompt)
3. The agent executes the embedded webhook commands to report progress back to Ref
## Context sources
Pull context from your project management and development tools into your plans:
| Source | Description |
| ------------------------------------------------- | ----------------------------------------------------------------------------- |
| [Linear](/plans/integrations/linear) | Attach Linear tickets for context; agent can update ticket status |
| [Asana](/plans/integrations/asana) | Attach Asana tasks for context; agent can update task fields and add comments |
| [GitHub Issues & PRs](/plans/integrations/github) | Attach GitHub issues and PRs; track PRs linked to plans |
| [Slack](/plans/integrations/slack) | Create and update plans from Slack threads via @mention |
## Custom MCP servers
Connect your own remote MCP server to make its tools available to ref-thread agents. Custom MCP servers are configured in Settings and can be attached per thread from the message composer — see [Custom MCP Servers](/plans/integrations/custom-mcp).
## Custom Launchers
Use [Custom Launchers](/plans/integrations/custom-launchers) to deep-link into Ref from any tool that can construct a URL. The `/new` URL can seed plan content and optionally start an agent thread immediately.
Launch Cursor background agents from your plans.
Launch Devin sessions from your plans.
Launch Warp OZ agents from your plans.
Launch Conductor Cloud agents from your plans.
Send tasks to Claude Code in the cloud.
Send tasks to OpenAI Codex.
Connect Linear tickets to your plans.
Connect Asana tasks to your plans.
Connect GitHub issues and PRs to your plans.
Create and update plans from Slack threads.
Connect your own remote MCP server.
Deep-link into Ref from any tool.
# Slack
Source: https://docs.ref.tools/plans/integrations/slack
Create and update Ref Plans directly from Slack threads.
The Slack integration connects your team's conversations to structured plans. @mention the Ref bot in any Slack thread, and it automatically creates a plan from the conversation — researching your codebase and producing tasks, decisions, and verification criteria.
## Connect Slack
1. Go to **Settings** in Ref Plans
2. Click the **Integrations** tab
3. Select **Slack**
4. Click **Connect Slack**
5. Authorize Ref in the Slack popup
6. Once authorized, the integration is active for your team
Only team admins can connect the Slack integration.
## Create Plans from Slack
@mention the Ref bot in any Slack thread to create a plan. The agent reads the full thread, researches your indexed repositories, and produces a structured implementation plan. It replies in the thread with a link to the finished plan.
## Follow Up in Threads
@mention the bot again in the same thread to update the existing plan. Ask it to add a section, change the scope, or refine a task — the agent picks up where it left off. It only creates a new plan if you explicitly ask for one.
## Key Features
* **Thread → Plan in seconds** — @mention the bot in a thread and get a fully researched implementation plan
* **Conversational updates** — Follow-up @mentions update the existing plan instead of creating duplicates
* **Codebase-aware** — The agent researches your indexed repositories to produce plans grounded in your actual code
* **Team-connected** — Plans are created under your Ref team with team-level visibility
## Requirements
* A Ref account
* A Ref team with at least one indexed GitHub repository (recommended for best results)
* Team admin permissions to install the Slack integration
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Warp OZ
Source: https://docs.ref.tools/plans/integrations/warp-oz
Launch Warp OZ agents from Ref Plans.
Warp OZ integration lets you launch Warp OZ agents directly from your plans and track their progress.
## Install the Ref MCP server in Warp OZ
Give Warp OZ access to your plans and tasks by connecting the **Ref Plans MCP server** with the streamable HTTP endpoint `https://api.plan.ref.tools/mcp`. Full steps for installing the MCP server, including API key setup, are in the **[Ref Plans MCP install guide](/plans/install/index)**.
This will allow Warp OZ agents to send messages back to a Ref agent orchestrator.
## Connect Warp OZ
1. Go to **Settings** in Ref Plans
2. Click the **Agent Settings** tab
3. Select the **Warp OZ** tab
4. Paste your Warp API key
5. Optionally enter an **Environment ID**
Warp API keys start with `wk-...`. In the Warp desktop app, open **Settings > Platform** and create an API key.
Most users with a single environment can leave **Environment ID** blank.
## Launch an agent
1. Open your plan and select a task
2. Click **Launch Agent** and choose **Warp OZ**
3. Review the prompt — Ref pre-populates it with the task details
4. Click **Launch**
## Status tracking
Ref tracks the Warp OZ agent status:
* **Working** — The agent is actively implementing the task
* **Finished** — The agent has completed its work
* **PR Created** — A pull request URL is shown when the agent creates one
You can monitor agent progress directly from your plan without switching to Warp.
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Claude Code /plan Hook
Source: https://docs.ref.tools/plans/workflows/claude-code-hook
Automatically create a Ref Plan when you exit plan mode in Claude Code.
The Claude Code `/plan` hook automatically creates a Ref Plan when you exit plan mode in Claude Code. Your plan opens in the browser, ready to share, refine, and send to agents.
## Install
Run the install script:
```
curl -fsSL https://api.plan.ref.tools/plugins/install/ref-plan-hook | bash
```
## Configuration
The hook authenticates with your Ref API key. You can configure it in two ways:
**Environment variable:**
```
export REF_API_KEY=your-api-key
```
**Config file** (`~/.ref/config.json`):
```json theme={null}
{
"apiKey": "your-api-key"
}
```
You can find your API key at [ref.tools/keys](https://ref.tools/keys).
## How it works
1. You enter `/plan` mode in Claude Code as usual
2. When you exit plan mode, the hook fires
3. A new Ref Plan is created with your plan content
4. The plan opens in your default browser
**Note:** If you are at the limit number of plans for your tier, the hook will fail silently.
# Multi-Agent Orchestration
Source: https://docs.ref.tools/plans/workflows/multi-agent
Launch and coordinate multiple coding agents working in parallel from a single plan.
Multi-agent orchestration lets a Ref agent (the orchestrator) spawn sub-agents on Cursor, Devin, Warp OZ, or internal ref-threads, send them messages, and receive updates back — all via MCP tools. This is the most automated way to use Ref Plans.
## How it works
An orchestrator agent reads your plan, then launches child agents to implement and review tasks in parallel. The agents communicate through a parent/child messaging system — no polling required.
```mermaid theme={null}
graph TD
A[Orchestrator Agent] -->|LaunchAgent: cursor| B[Cursor Agent - Task 1]
A -->|LaunchAgent: devin| C[Devin Agent - Task 2]
B -->|SendMessage: PR URL| A
C -->|SendMessage: PR URL| A
A -->|LaunchAgent: ref-thread| D[Reviewer Agent]
D -->|SendMessage: Review results| A
```
## The tools
Two MCP tools power orchestration:
### LaunchAgent
Launches a sub-agent to work in parallel. Available harness types:
| Harness | Use for | What it does |
| ------------ | ---------------------------- | ---------------------------------------------------------------------------------- |
| `cursor` | Implementation tasks | Launches a Cursor background agent that writes code and creates PRs |
| `devin` | Implementation tasks | Launches a Devin session that writes code and creates PRs |
| `warp-oz` | Implementation tasks | Launches a Warp OZ agent that writes code and creates PRs |
| `ref-thread` | Review and lightweight tasks | Launches an internal Ref agent that can read PRs, review diffs, approve, and merge |
Key parameters:
* **`planIds`** — Plan IDs the agent should be associated with
* **`prompt`** — The complete task request with all context, requirements, and instructions
* **`harness`** — Where to run the agent: `cursor`, `devin`, `warp-oz`, or `ref-thread`
* **`taskShortDescription`** — Brief label for the agent (\~10 words)
* **`repo`** / **`branch`** / **`model`** — Optional overrides (Cursor only)
### SendMessage
Sends a message between parent and child agents. This is how agents communicate:
* **Child agents** MUST message their parent when work is complete (including the PR URL) or when stuck
* **Parent agents** use this to send follow-up instructions or course corrections
Parameters:
* **`agentId`** — The agent to send the message to
* **`message`** — The message content
## Typical workflow
Research and iterate on your plan in the web client or via MCP. Break work into tasks that can be implemented independently.
An orchestrator agent reads the plan and launches implementation agents (Cursor, Devin, or Warp OZ) in parallel via `LaunchAgent`. Each agent gets a self-contained prompt with all the context it needs.
As implementation agents finish and report back with PR URLs, the orchestrator launches `ref-thread` agents to review each PR. Reviewers have access to GitHub tools (`ReadPR`, `ReviewPR`, `MergePR`) to inspect diffs and approve.
Once reviewers approve, they merge the PRs (if permitted). The orchestrator updates the plan to mark tasks complete. Repeat until the plan is done.
## Example session
Here's what a typical orchestration session looks like:
1. The orchestrator reads the plan and identifies three independent tasks
2. It launches two Cursor agents for Task 1 and Task 2 in parallel, and a Devin agent for Task 3
3. Task 1's agent finishes first and messages back: *"Task complete. PR: [https://github.com/org/repo/pull/42](https://github.com/org/repo/pull/42)"*
4. The orchestrator launches a ref-thread reviewer to review PR #42
5. Task 2's agent finishes and messages back with its PR URL
6. The reviewer approves and merges PR #42, then messages the orchestrator with results
7. The orchestrator updates the plan, marking Task 1 complete
8. The process continues until all tasks are implemented, reviewed, and merged
## Harness selection guide
**Use `cursor`, `devin`, or `warp-oz` for implementation** — these agents write code, create branches, and open PRs. Choose based on which service you have configured and prefer.
**Use `ref-thread` for reviews** — ref-thread agents have access to GitHub PR tools (`ReadPR`, `ReviewPR`, `MergePR`, `SearchPRs`) that implementation agents do not. Always use ref-thread for PR review tasks.
## Requirements
To use multi-agent orchestration, you need:
1. **Ref Plans MCP server installed** in your orchestrating agent — see the [install guide](/plans/install/index)
2. **API keys configured** for Cursor, Devin, and/or Warp OZ in [Agent Settings](https://plan.ref.tools/settings) — required for `cursor`, `devin`, and `warp-oz` harnesses
3. **GitHub connected** at [ref.tools/resources](https://ref.tools/resources) — required for ref-thread reviewers to access PR tools
## Parent/child messaging rules
* Child agents **must** message their parent when done (include the PR URL if one was created) or when stuck
* Parents can send follow-up instructions or corrections to any child via `SendMessage`
* Agents can only message their direct parent or their own children — no cross-communication
* The workflow is message-driven: after launching agents, wait for messages rather than polling
## Get help
If you have any issues, please reach out to `help@ref.tools`. We're happy to help you get started!
# Ways to Work with Plans
Source: https://docs.ref.tools/plans/workflows/overview
Different approaches to planning and orchestrating coding agents.
Ref Plans is flexible — there's no single "right" workflow. Here are the most common approaches.
## Plan and Polish (recommended)
Use Ref as your main driver and orchestrator. This is a two-phase workflow:
1. **Plan phase** — Research and context engineer in the web client. Start with your notes and ask the agent to research the codebase and break the work into tasks.
2. **Launch phase** — Send tasks to background or cloud agents. Sometimes multiple tasks in parallel.
3. **Test phase** — As agents finish, checkout branches locally to test and verify. Ask the agent for any fixes.
4. **Merge phase** — Have your local agent open and merge PRs. Update the plan based on progress and any changes from the initial approach.
## Agent Orchestration
For fully automated multi-agent workflows. An orchestrator agent manages the entire cycle — launching implementation agents, coordinating reviews, and merging PRs — with minimal human intervention.
1. **Plan** — Research and iterate on the plan in the web client or via MCP.
2. **Orchestrate** — An orchestrator agent launches implementation agents (Cursor, Devin) in parallel via `LaunchAgent`. Each agent gets a self-contained prompt with all context.
3. **Review** — The orchestrator launches `ref-thread` agents to review PRs. Reviewers read diffs, approve, and report back.
4. **Merge** — Ref agents merge approved PRs. The orchestrator updates the plan and repeats until done.
This builds on "Plan and Polish" by automating the launch, review, and merge phases. It requires the MCP server installed and agent API keys configured.
Full guide to launching and coordinating multiple agents from a plan.
## Linear / GitHub-driven planning
Pull context from your project management tools directly into your plans.
1. **Research** — Add Linear ticket or GitHub issue links to your plan. Ask the agent to research the codebase and break the work into tasks.
2. **Launch** — Send tasks to agents for implementation.
3. **Track** — As agents finish, test locally and merge PRs.
4. **Update** — Have the Ref agent update Linear and GitHub based on progress.
To connect Linear, click the Linear logo button in the chat panel. To connect GitHub issues and PRs, connect GitHub and add repos at [ref.tools/resources](https://ref.tools/resources).
## Local MCP server
If you prefer not to have Ref index your codebase, or you're out of credits and don't want to buy more, you can still use Ref to manage and iterate on your plans. The MCP server provides all the same tools to any agent of your choosing.
## Claude Code /plan hook
If you have a great local Claude Code setup and just want to collaborate on plans more easily, install the `/plan` hook. Every time you exit plan mode in Claude Code, it automatically creates a Ref Plan and opens it in your browser.
Learn more in the [Claude Code /plan hook guide](/plans/workflows/claude-code-hook).
How different roles use Ref Plans.
Connect agents and external services.
# Early-Career Engineer
Source: https://docs.ref.tools/plans/workflows/role-early-career
How early-career engineers use Ref Plans to research and learn.
## Research and learn
Your main job is learning and developing your taste as an engineer. You practice these skills in Ref by researching and writing implementation plans, then asking teammates for feedback.
You work with AI to create a plan and spend your time considering the design choices and checking assumptions. This is how you learn and advance in your career.
**Your workflow:**
* Research unfamiliar codebases by asking the agent to explain patterns and architecture
* Write plans and share them with senior engineers for [review](/plans/collaboration/reviews)
* Build understanding of how features connect across the codebase
# Senior / Staff Engineer
Source: https://docs.ref.tools/plans/workflows/role-senior-staff
How senior and staff engineers use Ref Plans to orchestrate complex projects.
## Orchestrate complex projects
You're juggling as many agents as possible while also supporting junior engineers. You use Ref to manage complex projects spanning multiple days in parallel without losing track of where things stand.
**Your workflow:**
* Maintain tech plans across multi-PR projects
* Run parallel agents on different tasks simultaneously
* Provide [feedback on other engineers' plans](/plans/collaboration/reviews) to help them learn and catch issues early
# Tech Lead / Manager
Source: https://docs.ref.tools/plans/workflows/role-tech-lead
How tech leads and managers use Ref Plans to guide their organization.
## Guide the organization
AI moved the bottleneck from writing code to reviewing what everyone — and every agent — is building. You need to help a team of engineers operate with high throughput while maintaining coherence towards company objectives, so use Ref Plans to review the plan before the diff and keep plan review at the center of the process.
**Your workflow:**
* Review plans before code is written — align on the plan before the diff and catch architecture issues early
* Use the [MCP server](/plans/install/index) to have your agent review active and recently finished plans to understand the team's state
* Set up [team visibility](/plans/collaboration/team-visibility) to see all active plans in one place
# Vibecoder
Source: https://docs.ref.tools/plans/workflows/role-vibecoder
How vibecoders use Ref Plans to scale context beyond single sessions.
## Scale context beyond single sessions
You have tons of ideas and your project's complexity is growing. You use Ref to maintain a single cohesive source of context across large projects.
**Your workflow:**
* Research and refine ideas in Ref before writing any code
* Dispatch multiple parallel agents to bring ideas into reality
* Maintain context that survives across agent sessions — no more re-explaining your project from scratch
# Plans for Your Role
Source: https://docs.ref.tools/plans/workflows/roles
How different roles use Ref Plans.
Ref Plans is flexible and built for teams. How you use it depends on your role.
Research and learn. Write plans, build understanding, get feedback from senior engineers.
Orchestrate complex projects. Run parallel agents, maintain multi-PR tech plans.
Guide the organization. Review plans before code, understand team state at a glance.
Scale context beyond single sessions. Maintain cohesive context across large projects.
# Contact
Source: https://docs.ref.tools/support/contact
How to reach the Ref team.
## Email
* General inquiries: `hello@ref.tools`
* Talk to a founder: `matt@ref.tools`
## Hours
* Guaranteed support: 9am–5pm PT on weekdays.
* Critical issues: 24/7 with pager escalation.
## Need phone or Zoom support?
Reach out to `matt@ref.tools` about an Enterprise plan.
# Privacy & Security
Source: https://docs.ref.tools/support/privacy-security
Providing a secure search environment is important to us. This page outlines how we approach security for Ref.
Please submit potential vulnerabilities or any security-related questions to [security@ref.tools](mailto:security@ref.tools).
*While many teams and individuals already trusting Ref, please note that we are still in the journey of growing our product and improving our security posture. If you're working in a highly sensitive environment, you should be careful when using Ref (or any other AI tool). We hope this page gives insight into our progress and helps you make a proper risk assessment.*
## Overview
Ref is built with security and privacy as core principles. This page outlines our security architecture, data handling practices, and compliance efforts. Key areas include:
* **MCP Implementation**: Local and remote server protocols with API key authentication
* **Data Protection**: End-to-end encryption, isolated multi-tenant architecture, and comprehensive audit logging
* **Compliance**: SOC2 certification in process with Vanta (see our [Trust Center](https://trust.ref.tools))
* **Monitoring**: Real-time health checks and public status updates
## MCP
### Protocols
Ref provides an [open-source](https://github.com/ref-tools/ref-tools-mcp) `stdio` server that can be run locally and a `streamable-http` that is connected to remotely.
### Authentication
Ref allows use of API keys or OAuth for authentication. Ref's implementation of MCP OAuth is in beta as of Nov 15, 2025. Ref also supports SSO for organizations via [Scalekit](https://www.scalekit.com/).
The easiest way to rollout Ref to an organization is a combination of SSO and MCP OAuth. If you are interested in MCP OAuth and/or SSO, please reach out to `help@ref.tools`
## Data Handling
### Encryption
* **In Transit**: All data is encrypted during transit. Ref uses MCP streamable-http transport.
* **At Rest**: Documents and search indices are encrypted at rest in our database.
* **Customer Managed Keys**: Turbopuffer supports customer managed encryption keys (available upon request).
### Data Isolation
We take data isolation very seriously in our multi-tenant environment:
* Each team and user has their own isolated namespace in Turbopuffer.
* Indexing jobs run in single, transient, isolated containers. Your documents and credentials are never present at the same time as another team's data.
* All application data reads go through Firestore rules that enforce user access at the database level.
### Audit Logging
* Complete activity logging for users and teams available at [ref.tools/activity](https://ref.tools/activity)
* Logs include user identity, tool calls, and arguments
### Incident Response
* Internal monitoring via Sentry and Google Cloud alerting tools
* Status updates published at [ref.tools/status](https://ref.tools/status) during incidents
## Compliance
### Certifications
* **SOC2**: Currently in progress with [Vanta](https://www.vanta.com)
* For more information, see out [Trust Center](https://trust.ref.tools)
### Subprocessors & Data Access
Our security model includes the following subprocessors with specific data access patterns:
* **[Turbopuffer](https://turbopuffer.com)**: `Stores docs` Turbopuffer is the primary search store used by Ref. It is also used by Cursor and Notion. Stores documents, descriptions, and vector embeddings with encryption at rest and isolated namespaces.
* **[Firebase](https://firebase.google.com)**: `Sees and stores docs` Temporarily processes search results through Functions and temporarily caches results in Firestore with database-level access controls. All data is encrypted at rest.
* **[Google Cloud Run](https://cloud.google.com/run)**: `Sees docs` Processes indexing jobs in isolated, transient containers. User docs will be loaded
* **[Google Vertex AI](https://ai.google.dev/gemini-api/docs)**: `Sees docs` Generates document description with zero-data retention policy.
* **[VoyageAI](https://www.voyageai.com/)**: `Sees docs` Creates vector embeddings of docs with zero-data retention policy
* **[OpenAI](https://openai.com)**: `Sees docs` Powers research agent functionality with zero-data retention policy. User data will be included in prompts sent to OpenAI.
* **[Anthropic](https://www.anthropic.com)**: `Sees no docs` Powers evals on public documentation sets with zero-data retention policy.
* **[Stripe](https://stripe.com)**: `Sees no docs` Processes payment information with PCI-compliant security standards.
* **[Postmark](https://postmarkapp.com)**: `Sees no docs` Delivers transactional emails with user contact information.
* **[Mailchimp](https://mailchimp.com)**: `Sees no docs` Manages marketing communications and newsletter subscriptions.
* **[Mixpanel](https://mixpanel.com)**: `Sees no docs` Analyzes product usage analytics.
* **[Sentry](https://sentry.io)**: `Sees no docs` Monitors errors and performance with anonymized telemetry data.
* **[Google Workspace](https://workspace.google.com)**: `Sees no docs` Used for communication and coordination.
* **[Slack](https://slack.com)**: `Sees no docs` Used to communicate with partners.
* **[GitHub](https://github.com)**: `Sees no docs` Used for version control.
* **[Scalekit](https://scalekit.com)**: `Sees no docs` Used for SSO (Firebase is the IdP) and MCP OAuth.
### Monitoring & Health Checks
* Health check endpoint: `api.ref.tools/ping`
* Internal monitoring and alerting infrastructure
* Status page: [ref.tools/status](https://ref.tools/status)
# Report a Bug
Source: https://docs.ref.tools/support/report-bug
Share reproduction steps fast.
## Web Form
Use our bug report form:
**[Submit Bug Report](https://tally.so/r/wQW0x8)**
## Email
Email us at `hello@ref.tools` with:
* A clear description of the issue
* Reproduction steps
* Logs and screenshots attached
## Follow Up
* Expect a response within one business day although often within the hour during San Francisco day time.
* Status and outage reports can be found at [ref.tools/status](https://ref.tools/status)
# Request Docs
Source: https://docs.ref.tools/support/request-docs
Ask Ref to index new materials.
We strive to have everything indexed. However, if we're missing something, we're happy to add it.
## Submit a Request
Please reach out here to request new documentation:
[Request Documentation](https://tally.so/r/nrvBY2)
## Future Plans
In the future, we may add the ability to let users index their own pages, but that feature is still in the backlog.
# Status
Source: https://docs.ref.tools/support/status
Check the current status of Ref services.
Check the real-time status of Ref services and view incident history:
**[View Status Page](https://ref.tools/status)**
This page provides:
* Current operational status
* Ongoing incidents and maintenance
* Historical uptime data
# Credits
Source: https://docs.ref.tools/usage/credits
How credits work across Ref Context and Ref Plans.
Credits are the shared currency across both Ref products. The same credit pool is used for documentation search (Ref Context) and AI generation in the plan editor (Ref Plans).
## Ref Context tool costs
| Endpoint | Credits |
| -------------------------- | ------- |
| ref\_search\_documentation | 1 |
| ref\_read\_url | 1 |
## Ref Plans credit usage
Credits are consumed when you use AI generation in the Ref Plans editor — for example, asking the agent to research your codebase, structure a plan, or refine tasks.
## Viewing your usage
For users and teams you can view your usage at [ref.tools/activity](https://ref.tools/activity).
## How to get credits
All accounts start with 200 free credits that never expire. Paid tiers include monthly credit allowances, and you can purchase additional credits as pay-as-you-go.
[Learn more about pricing tiers](/usage/pricing)
# Enterprise
Source: https://docs.ref.tools/usage/enterprise
SSO, security, and centralized management for large organizations.
For larger organizations requiring enhanced security, compliance, and centralized user management, Ref offers an Enterprise add-on to the Team plan.
# Enterprise Features
### Single Sign-On (SSO)
Ref supports SAML and OIDC authentication, allowing your team to log in using your existing Identity Provider (IdP) such as:
* Okta
* Azure AD (Microsoft Entra ID)
* Google Workspace
SSO enforcement ensures that all team members access Ref through your corporate credentials, improving security and simplifying onboarding/offboarding.
### Centralized Billing
Consolidate your team's usage into a single invoice. Enterprise plans include unified billing for all seat management and credit usage.
### Account Migration
We provide tooling to seamlessly migrate existing individual Ref accounts into your corporate Enterprise organization, ensuring no history or private indices are lost during the transition.
### Zoom Support
We'll provide your team with a link to schedule same-day support Zoom sessions.
# Getting Started
The Enterprise plan is an add-on to our Team plan. Here is the process to get set up:
## 1. Upgrade to a Team
Ensure you have a Ref Team set up. You can create one at [ref.tools/create-team](https://ref.tools/create-team).
## 2. Contact Support
Reach out to us at [hello@ref.tools](mailto:hello@ref.tools) to request Enterprise activation. We'll enable SSO for your team which cost an additional \$200/month that will be added to your existing invoice.
## 3. Configure Identity Provider
Once approved, you will receive a secure setup link to configure your IdP. See the [SSO setup docs from Scalekit](https://docs.scalekit.com/guides/integrations/sso-integrations) for steps you'll follow
## 4. Share Ref with your team
Once you've setup SSO, you can provide your team with Ref's OAuth url `https://api.ref.tools/mcp` and they will be prompted to sign-in with SSO.
# Pricing
Source: https://docs.ref.tools/usage/pricing
Plans and pricing for Ref Context and Ref Plans.
## Plans
Ref offers tiers for individuals, teams, and organizations. Credits are shared across both [Ref Context](/context/getting-started/intro) (documentation search) and [Ref Plans](/plans/getting-started/intro) (plan writing and agent orchestration). If you have questions, reach out to `help@ref.tools`.
| | Free | Pro | Max | Enterprise |
| --------------- | ------------ | --------- | --------- | ---------- |
| **Price** | \$0 | \$50/mo | \$200/mo | Custom |
| **Credits** | 200 one-time | 6,000/mo | 30,000/mo | Custom |
| **Plans** | Unlimited | Unlimited | Unlimited | Unlimited |
| **Small repos** | 3 | 50 | Unlimited | Custom |
| **Large repos** | 1 | 5 | 25 | Custom |
| **PDF pages** | 100 | 5,000 | 25,000 | Custom |
### Tier details
* **Free** — \$0 with 200 one-time credits that never expire. Great for trying Ref out. Limited to 3 small repos and 1 large repo.
* **Pro** — \$50/mo with 6,000 credits per month (\~8% discount per credit). 50 small repos, 5 large repos.
* **Max** — \$200/mo with 30,000 credits per month (\~26% discount per credit). Unlimited small repos, 25 large repos.
* **Enterprise** — Custom pricing with custom limits, SSO, and dedicated support.
### Pay-as-you-go
Available to Pro tier and above: **\$10 per 1,000 additional credits**. Pay-as-you-go credits are charged at the end of the billing cycle based on usage.
## Credits and expected usage
Ref uses a credit system to support multiple user types with a single straightforward billing system. Credits are consumed by both Ref Context (documentation search queries) and Ref Plans (AI generation in the plan editor).
**For most individual developers**, 6,000 credits is way more than you'll use in a month. The Pro plan should feel like a subscription with predictable pricing and you will rarely, if ever, run out of credits.
**For heavy users and teams** who use Ref Plans for AI-assisted planning and run multiple agents, the Max tier provides a significant per-credit discount at higher volume.
**For agent developers** who want to deploy Ref as part of a coding agent, you can use a single API key for all your users and buy additional credits. Your cost will scale with your usage.
## Legacy subscriptions
Existing \$9/mo Basic and Team subscriptions continue unchanged. Legacy subscribers receive their existing 1,000 credits for \$9/mo, have unlimited plans, and have Free-tier limits for indexing. There are no price changes to existing subscriptions.
Existing \$19/mo Basic subscriptions also continue unchanged. Basic subscribers keep their current credits, limits, and billing; the plan is no longer offered for new purchases.
## Managing your subscription
Subscriptions can be managed through your Stripe portal. You can access this at [ref.tools/account](https://ref.tools/account) for individuals and [ref.tools/team](https://ref.tools/team) for teams.
# Access Control
Source: https://docs.ref.tools/usage/rbac
Role-based access control for Ref teams.
Ref allows you to give different members of your team different capabilities, so that you're in control of how your team uses Ref.
## Roles
| Role | Capabilities |
| ------ | -------------------------------------------------------------------------- |
| Admin | Search context index, add content to index, invite members, manage billing |
| Writer | Search context index and add content to index |
| Reader | Search context index |
> All team members can read and write plans regardless of role. Reader and Writer roles only affect permissions for the shared context index (indexed repositories).
## Management
Roles can be managed from [ref.tools/team](https://ref.tools/team). Make sure that your team is selected in the workspace picker in the top-left of the page.
## How to only use public docs
Some teams use Ref to only search public documentation sources. The best way to manage this is have one user sign up as an `admin` and invite the rest of the users as `readers`. Then no one will be able to index private sources.
# Teams
Source: https://docs.ref.tools/usage/teams
Share credits, resources, and plans with teammates.
Manage your team at [ref.tools/team](https://ref.tools/team)
Create a team at [ref.tools/create-team](https://ref.tools/create-team)
# Benefits of a Team
### 1. Shared private index
Build an index of private documentation based on the libraries and platforms your team uses. All team members can search the shared index with [Ref Context](/context/getting-started/intro).
### 2. Pooled credits
Your team gets a shared credit pool based on your tier. Credits are shared across both Ref Context (documentation search) and [Ref Plans](/plans/getting-started/intro) (plan writing and agent orchestration).
### 3. Team plans
Create plans under your team in Ref Plans. Control [visibility](/plans/collaboration/team-visibility) — make plans discoverable to the whole team or keep them personal. Request [reviews](/plans/collaboration/reviews) from teammates.
### 4. Access control
Manage the capabilities of different team members with role-based access control.
| Role | Capabilities |
| ------ | -------------------------------------------------------------------------- |
| Admin | Search context index, add content to index, invite members, manage billing |
| Writer | Search context index and add content to index |
| Reader | Search context index |
> All team members can read and write plans regardless of role. Reader and Writer roles only affect permissions for the shared context index (indexed repositories).
### 5. Unified billing
Manage your team's bill from a single account.
# Get the most out of your Team
Our goal is to make it risk-free to try Ref and only charge users that are actually using the product. Here's how you can do that.
## 1. Everyone starts Free
Everyone who signs up for Ref gets 200 free credits in their account that never expire. You may invite people to your team without upgrading them and let them use their free starter credits on their account.
This allows you to let everyone on your team try Ref for free.
## 2. Upgrade as needed
When a team member runs out of credits, you can upgrade them from the [team management page](https://ref.tools/team).
This allows you to pay only for users who are actively using the product.
# Team Pricing
Team pricing follows the same tier structure as individual plans. Per-seat pricing is based on your chosen tier.
Learn more about [pricing](/usage/pricing) and [credit usage](/usage/credits)