MCP App Store
by KeenEthics
Ref icon

Ref MCP Server for ChatGPT

By Ref Software, Inc.

Overview

Ref brings interactive, visual plan documents to your chats for you to review and agents to work from. Ask Ref for a plan and get a rich source of truth for your work with mockups, diagrams, HTML widgets, comment threads and task breakdowns for you to approve and share. Ref is multiplayer; your team can edit, comment on, review and approve from the browser or within their own agent. When you're ready to build, hand tasks back to Codex with a click; Ref updates the plan automatically as work moves forward or evolves.

How to connect

  1. ChatGPT: Open the Ref listing in the ChatGPT app directory and choose Connect. ChatGPT listing Ref exposes 17 tools here.

Tools

Automations

ChatGPT
Manages recurring automations in this space: list, get, runs, create, update, delete. Each fire launches a fresh ref-thread agent on a new ref or an existing one. delete is irreversible; update with enabled false pauses instead.

Clipboard

ChatGPT
Cuts, copies, lists, reads, pastes and clears named chunks of ref text, so you move content between refs without retyping it. Items belong to your user and never expire: any of your agents that knows a name can use it, and every response lists them. cut and copy save target, matched as in Write, under name; cut also removes it from the ref. read returns one item's full text. paste lands items in one atomic edit, each replacing its target's current; add clear: true to delete them once it lands. clear deletes names: clear anything no agent will paste again. An item holds at most 900 KB. Pasting into another space needs acrossSpaces: true.

Comments

ChatGPT
Manages comment threads on a ref: list, get, create, reply, resolve, unresolve. In a user session or as an orchestrator, addressing a comment usually means editing the ref rather than replying; reply when the thread asks you a question or the launch prompt says to. Resolve a thread once the document reflects it. list returns the latest review's verdict and summary alongside threads; earlier rounds are read with get + reviewRound. A thread marked visibility: private is visible only to the user you act for, so reply in that thread and don't repeat it in shared comments.

Home

ChatGPT
Use this when the user wants their Ref home: the Refs they opened recently, review requests and new comments. Don't use it for opening a specific Ref; use Open for that. Show the Ref home in the chat, rendered by the Ref web app: the Refs the user opened recently and what needs them. Takes no arguments.

LaunchAgent

ChatGPT
Launches a child agent that works in parallel and messages you when it is done. Use it for independent subtasks, for reviewing an open PR, and for research that can run alongside your own work. One task per child, a self-contained prompt, and a taskShortDescription. Ref edits and comment replies stay inline — a child is for work in a repo or on a PR.

List

ChatGPT
Use this when the user wants to find a shareable Ref plan their team reviews and agents build from. Don't use it for listing files, issues, or tasks that live outside a Ref. Lists all refs accessible to you — individual, team, and refs shared with you: title, url, owner, dates, attached PRs and a section overview. Narrow with owner, updated_since, or parent. With include_archived: true, each row includes archived: true or false.

ListDevices

ChatGPT
Lists the user's paired laptops available as ref-plan:LaunchAgent harness "local", each with the repo names its daemon advertised and whether it is launchable right now. When a machine has a description, read it when choosing where to launch.

ListSkills

ChatGPT
Lists the skills this session can load — Ref's authoring and workflow skills plus your team's — with the id for ref-plan:Skill and when each applies. One call, early.

Media

ChatGPT
Handles images and videos in a ref. upload stores an image from an HTTPS url or returns a signed uploadUrl for raw image or video bytes; insert places ![alt](ref-media://mediaId) or ![alt](ref-media://mediaId?k=video) after a line. The same ref-media://mediaId URI works inside html-ref widgets as an <img>, <video> or CSS url() source. Image view returns a signed URL or inline pixels. For video, view the contact sheet first; its media id also works with image view and insert. Call digest when you need narration, transcript, or a summary; it costs the estimate shown by view. Then call view again. Pass fromSeconds and toSeconds to inspect exact frames and transcript. Pass question when the answer depends on motion, audio, or events between stored frames. Questions cost credits and cover at most 10 minutes; pass fromSeconds and toSeconds on longer videos.

Metadata

ChatGPT
Reads or updates one ref's metadata. Use action: 'read' for its parent, dates, owner, PRs, descendants (children by default; depth selects more levels or 'all'), and agents with status, last activity and who started them. Use Read for document text. Use action: 'update' only for an explicitly requested metadata change: archived true archives, archived false unarchives, title renames, and parentPlanId moves the ref under a parent id or URL. parentPlanId: null moves it to the top level; omit a field to leave it unchanged. A parent in another space changes nothing unless you pass moveToParentSpace: true, which moves the ref into that space first and leaves the refs nested directly under it at the top level of the old space, so pass it only when the user asked for that move. Supply at least one update field and combine changes in one call. Updates change this ref's metadata, never its document text; descendants change only in that space move. Each update returns what changed plus an undo call. Clarify ambiguous cleanup requests before changing anything. Agents message you when they finish; never call this to wait.

Open

ChatGPT
Use this when the user wants a shareable Ref plan opened in the chat, the document they and their team review and agents build from. Don't use it for quick answers that belong in the chat. Show a Ref ref in the chat, rendered by the Ref web app itself: live, editable, with comments and Tasks. Takes a ref id or URL.

Read

ChatGPT
Use this when the user wants to read a shareable Ref plan, the document they and their team review and agents build from. Don't use it for reading code, files, or docs that are not a Ref. Reads a ref. Image markdown comes back raw as ![alt](ref-media://mediaId); pass the mediaId to ref-plan:Media action "view".

SendMessage

ChatGPT
Sends a message to your parent or to a child. Children report completion and PR URLs this way; parents send follow-ups and corrections. Set summary to an optional one-line preview (80 characters maximum) shown in the recipient's thread; the full message still reaches the agent. A finished Cursor, Devin or ref-thread child still takes messages and resumes (a local child gets it as a resumed turn when its device is online); Warp agents can't be messaged. A send that can't be delivered returns an error.

Skill

ChatGPT
Loads a skill by full id, for example ref/writing-a-ref. Load it before doing that kind of work; a bare name does not resolve. The body includes a manifest of asset paths and sizes; pass resource with a path from it to load that file.

UpdateDevice

ChatGPT
Set or clear owner preferences on a paired machine. Today the only field is description — a short plain-text note (max 280 characters) for what the machine is for. Pass fields: { description: "" } to clear it. Omitted keys are left as is. Use ListDevices first to find the deviceId.

Write

ChatGPT
Use this when the user wants a plan, spec or design written up as a shareable Ref document they can review, comment on and hand to an agent. Don't use it for quick answers that belong in the chat. Write: prepare and apply changes to a ref; create a new ref only where none exists. To move existing text without retyping it, use Clipboard. In a thread opened on an empty ref (the run context's currentPlanId), that ref is the one to write, whatever words the user used: initialize it with title and outline. Do not create. Each Write call is atomic. An edit changes one target. On apply, replacements pair with prepared targets by array position and land together as one atomic write. Prepare declares its targets together without changing the document. Theme groups related writes for review; separate calls remain independently atomic. The first write into an empty ref is initialize, with no preparedId, since there is nothing to match. It lands title and outline: the opening the finished ref will keep, one or two sentences stating the problem and the outcome, taken from the request, plus the TODO box of steps when your instructions ask for one. Not working notes, and not a skeleton of empty sections. It is preserved exactly, including its trailing newline, and grows through later prepare/apply calls. Action "create" makes an additional ref where none exists, from title, why, and an outline string, and returns planId and URL. In a thread opened on an empty ref it is the wrong call: it leaves that ref empty and puts the work in a second one. Creation is available only in a general-mode session. Read the ref, unless the run context says it is empty. On an empty ref, the opening needs no research; write it first. For every other claim, and for any ref that already has content, finish the research and decisions needed for each write before prepare. Prepare immediately before composing its replacements and apply as soon as they are ready. Independent writes may progress in parallel. Do not compose several writes serially, hold their completed replacements, and then apply them in a burst. Supply planId, why, optional theme, and a nonempty edits array. A plan-bound session must name its bound planId. Each prepared edit has target: { prefix, current, suffix }. Copy one contiguous passage from the document into these three strings. Their concatenation must match exactly once, whitespace included. Include enough context to keep the match unique; a bare word or phrase is fragile. Current is the block you intend to modify; prefix and suffix are unchanged matching context. Empty current declares an insertion point. An empty ref has nothing to match: initialize it with title and outline. The UI shows an insertion placeholder or highlights the existing block while you compose the content. Land only a small edit in one call: apply without preparedId, each edit carrying its target and its replacement, plus why. Small means ticking a TODO step, a table cell, a word or a single line. For anything longer, such as a paragraph, a table, a Task, a widget or a diagram, prepare first and then compose and apply, so the reader sees where you are working while you write it. Start a new Task with a bare ::: task line above its heading; the server writes the id and its ::: end task line. Keep both lines when you rewrite a Task, and read the ids from the reply's taskIds. Prepare returns one preparedId for its edits, editCount, expiresAt, and next { action, preparedId }. An empty ref can also be prepared first, with edits: "outline", to show where the opening will land while you compose it; the id starts with init- and next.action is initialize. Call action "initialize" with the same planId, that preparedId, title and outline. Call action "apply" with the same planId, that preparedId, and edits: [{ replacement }, ...], in the same order and with exactly the same count. Each replacement replaces only its corresponding current. Do not repeat prefix or suffix. An empty replacement deletes current. Do not resend matching text or metadata in apply. All targets in o…

Capabilities

InteractiveWrites

Similar Apps

Listed on MCP App Store

Listed on MCP App Store

Add this badge to your site or README. It links to this page.

HTML

<a href="https://mcp-app-store.keenethics-labs.com/app/ref"><img src="https://mcp-app-store.keenethics-labs.com/badges/listed-on-mcp-app-store.svg" alt="Listed on MCP App Store" width="220" height="44"></a>

Markdown

[![Listed on MCP App Store](https://mcp-app-store.keenethics-labs.com/badges/listed-on-mcp-app-store.svg)](https://mcp-app-store.keenethics-labs.com/app/ref)