Refine Hub
Refine 4.3.2
Design intent / Surfaces

MCP

Key Ideas

  • Always Available: the MCP surface starts with the local daemon and shares its lifetime. Whenever Refine is running, MCP clients can connect.
  • Application Reuse, Not Reimplementation: every MCP tool dispatches back through the shared daemon API. MCP adds a protocol adapter, not a parallel implementation of work.
  • Standard Protocol For Agents: MCP gives external AI clients a discoverable, stable way to read and act on Refine without learning its internal HTTP routes.
  • Local Daemon Contract: MCP is served by the same local daemon as every other Surface. It is local Application access, not a hosted integration boundary.
  • Discoverable Tools: tools list themselves with names and input schemas so agents can find Application operations instead of guessing endpoints.

Purpose

The MCP surface exists so MCP-speaking AI clients can use Refine directly through the Model Context Protocol. It complements the CLI and HTTP API: where the CLI is the explicit, scriptable agent interface and the API is the contract between surfaces and the daemon, MCP is the standard protocol an external assistant already knows how to speak.

It exists to lower the cost of agent integration. An agent should be able to attach to a running Refine daemon, list the available tools, and start reading status, Goals, and Features or invoking Application routes — without bespoke wiring for Refine’s internals.

MCP is treated as a thin, always-on adapter. It is important because it widens who can operate Refine, but it is not the product center and it does not own Application behavior.

Expected Role

The MCP surface should be mounted by the daemon web server and reachable as soon as the daemon is up. It speaks JSON-RPC 2.0 and answers the core MCP methods: capability negotiation on initialize, tool discovery on tools/list, and tool execution on tools/call.

Its tools should map onto real Application operations the same way the API route groups do. Reads (system status, dashboard, Goals, Features) should be first-class and safe. A general request tool should remain available as an escape hatch so an agent can reach any daemon route — including writes — without the catalog having to enumerate every operation up front.

Because MCP delegates to the shared daemon API, it inherits the system’s local-first security, idempotency, logging, and state-repair behavior rather than re-deriving them.

It also inherits the daemon’s immutable checkout and port authority. MCP tools cannot redirect a stateful request into a caller-relative or user-global runtime, and provider work launched through MCP uses the same exact <product-home>/run/<port> root as CLI, HTTP, and browser callers.

Current agent-facing planning support includes refine_draft_goal, which sends a Plan transcript through the same one-Goal extraction capability used by the browser, CLI, and HTTP API and returns the draft for review without persisting it.

Current audit support includes refine_export_goal_jira, which maps a Goal id onto the shared Jira evidence export route rather than formatting a separate agent-only report.

Source status, check, promotion, operation status, retry, and owner-aware cancellation intentionally use refine_request. The adapter forwards those routes through the real daemon dispatcher, so MCP observes the same operation and attempt identifiers, redaction, idempotency, and terminal evidence as HTTP, CLI, SSE, and browser callers.

MCP exposes list_events, list_skills, event_catalog, and trigger_event. Dynamic definitions and typed runtime parameters use the same capability as CLI and browser. Generic capability requests provide revision-fenced editing, invocation inspection, and cancellation.

refine_workflow_control exposes shared revision-fenced workflow decisions; a Skill invocation is optional provenance. refine_hub_sites discovers Hub sites. refine_request provides full Hub management, query, import/export, assets, and publication through the shared API.

Future Direction

As agent-native interaction grows, MCP may become a primary way external assistants drive Refine. The tool catalog should grow toward the most valuable Application operations — planning, import, workflow advancement, review — while keeping each tool aligned to shared behavior rather than a one-off implementation.

Future versions may add streaming, richer tool schemas, or protocol capability scoping. Those should be intentional steps that preserve the core intent: an always-available, standard, local protocol over the same durable Application every other Surface uses.

Explicit human exception controls share the Application capability: refine_workflow_control with force: true selects any step on the current Round and stops active execution. refine_delete_round requires Goal identity, zero-based Round index, and expected revision; it removes the Round and associated records and parks the Goal in Backlog. Bulk step assignment is available through the shared /work/goals/bulk route using refine_request. These controls bypass automated transition requirements while preserving node ownership and concurrent-edit checks.