MCP reference

Choose a connection#

Use direct hosted MCP when the service and client support OAuth. It needs no Mockspace checkout, CLI relay, or per-project registration.

Use the service relay for an existing CLI-based registration or when local source-management tools should be available from the matching checkout. Use a local canvas connection while building a flow and steering the viewer someone is watching.

Direct hosted MCP#

Register the service endpoint in the client:

claude mcp add --transport http --scope user mockspace https://mockspace.ynext.co/mcp
codex mcp add mockspace --url https://mockspace.ynext.co/mcp

The client discovers OAuth metadata, opens browser consent, and keeps the resulting bearer credential outside review URLs. In a published review, Use with AI supplies the exact review and selected frame as conversation context. The agent calls set_mockspace_context to switch the stable session to that build.

The hosted endpoint can also register a project with create_project and find your work with list_projects, before a review exists. See project creation for fields, authentication, and the first publish. It reads published context, reports local-agent activity, and can focus the shared view. It has no access to files in a local checkout.

Connect your local conversation to the deck#

Open Agents in a deck’s left navigation, choose Codex or Claude Code, and copy the connection prompt into your repository’s agent conversation. The panel includes one-time setup instructions and shows progress without requiring a web chat. See Work with your own agent.

These tools are available on authenticated hosted MCP after selecting a review with set_mockspace_context:

| Tool | Input | Result | | --- | --- | --- | | connect_agent | provider (codex, claude, or other), optional label, summary, and context_id | Connects to the selected review and optionally links one owned browser tab in the same project. Returns an owned session. | | list_agent_sessions | project | Lists your agents and retained activity without changing the active conversation. | | get_agent_context | project, session_id | Reads one agent’s exact review, progress, history and recovery prompt. | | restore_agent | project, session_id, expected_version | Restores the saved agent and review, preserving its ID, history and tab binding. Use the saved connection_version as expected_version. Old writers are rejected; other agents remain connected. | | report_agent_activity | session_id; status and summary for progress, optional components, files, frame, flow, build, view, and fit | Records a progress milestone and current work area. View-only updates may omit progress fields. | | set_agent_view | session_id, plus one or more of view, fit, frame, flow, or build | Updates this connected agent’s view while preserving its reported work progress. | | disconnect_agent | session_id | Ends contact while preserving activity history. |

Statuses are working, waiting, done, and error. A focus uses one canonical frame or flow identifier from the selected build. The same account must own the session and have access to its review. Local activity does not claim or trigger the hosted workbench automation lease.

Set the connected agent view#

Call set_agent_view after set_mockspace_context and connect_agent, using the returned session_id. It can control only this MCP conversation’s connected session in the active project. MCP supplies the current connection version; do not include connection_version in this tool’s arguments. A foreign session, stale restored connection, or expired/disconnected session cannot update the view.

| Field | Accepted values and behavior | | --- | --- | | view | all for All screens, diff for Changes, or live for Prototype (Live app). prototype is accepted and saved as live. | | frame or flow | One canonical target that exists in the selected build. Copy its identifier from the context tools. Supplying a new target replaces the previous target. | | fit | screen requires a supplied or retained frame. flow requires a supplied or retained frame or flow. null clears a saved fit. | | build | An accessible published build ID or ref in this project. Retained targets and view settings must also be valid for that build. |

Omitted fields preserve their saved values. For example, this actual tools/call request switches to All screens while retaining the target, fit, and reported status, summary, files, and components. Replace the session ID with the one returned by connect_agent:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "set_agent_view",
    "arguments": { "session_id": "agent_returned-id", "view": "all" }
  }
}

To fit a screen, add its frame and fit: "screen"; to fit a flow, use flow and fit: "flow". Do not supply both targets. To clear the target and any saved fit, send frame: null and fit: null. View-only updates add a view history entry without reporting a new work milestone.

Changes requires a draft with an accessible recorded comparison and detected changes. Prototype requires the project’s service-configured live app. Unavailable modes are rejected; the tool accepts no app URLs or scripts. View changes require project view permission, while progress reports require request permission.

The user selects that session in Agents and enables Follow agent to apply its updates. Tool calls cannot enable Follow or select another agent for the user. Manual navigation, including panning, zooming, or choosing another view or target, stops following. See the local-agent guide.

Read the user's current work area#

The deck’s Share my focus control makes that tab’s current project, review, view, and selected frame or flow available to your authenticated identity.

| Tool | Input | Result | | --- | --- | --- | | list_browser_contexts | Optional project | Lists your visible, recent browser contexts with identifiers, review URLs, activity state, and freshness. | | get_user_focus | Optional context_id or project | Reads an explicit context, the connected agent’s linked tab, or an unambiguous active context in scope. |

get_user_focus reports ready, paused, stale, selection_required, or unavailable. Multiple matching tabs require an explicit choice. A linked context never falls back to another tab when contact stops. Each connected conversation keeps its own binding, so several agents can work on different projects or areas simultaneously.

These tools do not change the MCP session’s active review, move the canvas, or trigger edits. Call them before interpreting a new user instruction, then select the returned review URL with set_mockspace_context if it belongs to that task. Verify the local repository separately; browser context cannot determine the terminal's current directory.

Service relay through the CLI#

One CLI relay registration can follow shared context across every published review on the service:

mockspace mcp --service https://mockspace.ynext.co

Register that command with the MCP client using the absolute Mockspace executable path or the supported service launcher. Sign in first for a private service. The relay resolves an explicit token, environment credentials, or the saved personal login.

When the relay starts inside the matching application checkout, it can expose policy-controlled source tools. Declared files are not automatically writable: the edit policy and local Git authorship still decide what the agent may manage.

Local live canvas#

Start mockspace dev --project <dir>. Its terminal output includes an MCP command bound to the actual viewer URL. A direct form is:

mockspace mcp --connect http://localhost:4310 --project <dir>

Register it under a distinct local name, then restart the client so it refreshes the tool list. This connection shares the live canvas, so focus_frame, focus_flow, and workspace reloads affect the view being reviewed.

mockspace mcp --project <dir> provides standalone workspace context when no viewer is running. It does not connect to someone else's canvas.

Context and navigation tools#

The local tool set includes product context, flow and graph inspection, screens, states, components, source lookup, context search, affected-frame analysis, frame HTML, and canvas focus. It also includes workspace reload and explicit deck creation tools.

Common tools include:

• get_workspace, list_flows, get_flow, and get_graph for product and journey context.
• get_screen, list_states, and list_components for the evidence behind a frame.
• search_context and affected_frames for finding relevant design notes and consequences of source edits.
• get_frame_html for the rendered HTML of an exact frame.
• focus_frame, focus_flow, and add_track for the live canvas.
• reload_workspace after declaration edits.
• get_edit_policy, check_manageable_files, and get_manageable_source for the local ownership boundary when available.
• get_deck_authoring_guide and create_deck for an explicit named publish boundary.

Published tools are read-oriented. MCP does not itself edit source files; a coding agent uses its ordinary file tools after the policy preflight.

Frame identifiers#

Copy canonical frame IDs from get_screen or list_states. A frame includes its flow placement, screen, and state, such as t1:workbench:default. The same screen may have more than one frame when it appears in several rows.

Prefer canonical frame and flow arguments. Legacy screen, state, and track locators remain for compatibility, but combining a canonical argument with its aliases is invalid.

Publishing boundary#

Focusing and reloading are live operations. Creating a static version is separate and must be explicitly requested. Deck names should describe the product area and review intent; authors are accountable people or established teams, not the model or machine that ran the command.

Read Authentication for OAuth, personal logins, and machine tokens.