MCP

Connect an agent to rect.sh and drive Apps and standalone Screens with structured tools.

The rect.sh MCP server is how agents speak the loop natively: discover templates, issue live instances, drive them, and read results back — as tools, with schemas, so any MCP-capable agent can use rect.sh without custom code.

Catalog metadata helps the agent choose a template. After choosing one, rect_get_spec returns its dedicated agent instructions from rect.agent.md; follow those for template-specific creation and update guidance, then use the schema and named actions as the executable contract.

Connect

The server speaks streamable HTTP at:

https://rect.sh/mcp

For Claude Code:

claude mcp add --transport http rectsh https://rect.sh/mcp

For Codex:

codex mcp add rectsh --url https://rect.sh/mcp

Any other MCP client configures the same URL as a remote HTTP server. The client will open Rect in a browser so you can sign in and approve the connection. Every request to the endpoint requires authentication; an unauthenticated GET returns the standard OAuth challenge used for automatic authorization-server discovery.

MCP operates published templates and live instances. It does not download or edit a template's source project and it does not publish source changes. For that workflow, use npm create rect for a new project or rect remix <ref> for an existing template, then run rect check before rect publish.

The agent loop

The tools are designed around one loop:

rect_list_templates            browse available templates
rect_get_spec                  what shape does this template want?
                               (agent instructions + example state + actions catalog)
rect_list_accounts             choose a workspace accountId
rect_list_members              load that workspace's people for the initial state
rect_issue                     create a live instance → show the human its URL
rect_list_instances            find previously issued instances (authentication required)
rect_dispatch / rect_patch     drive it while the human works
rect_get_result                read their edits back as JSON

This is the same loop the CLI speaks from a terminal and the HTTP API exposes to any program.

For an App, use the composed loop:

rect_list_apps                 browse Apps
rect_get_app                   inspect job instructions and pinned Screens
rect_launch_app                create a run and all ordered Screen instances
rect_get_app_run               read the job and ordered Screen handles
rect_attach_to_screen          make a run file available to a target Screen
rect_get_spec + rect_get_result
  + rect_dispatch              fetch and drive only the Screen you need
rect_select_app_screen         choose the Screen shown to the user

Rect actions never navigate the App. When another registered Screen should be shown, the agent calls rect_select_app_screen with the latest revision and Screen key. See Apps and Screens for the authoring format and runtime model.

The MCP connection is authenticated as the approving user. Each Rect still has independent readAccess and writeAccess scopes: anonymous, authenticated, workspace, or owner. Rects issued through MCP default both scopes to workspace; pass a different scope to rect_issue only when intended.

Tools

Discover & issue

Tool	What it does
`rect_list_templates`	List one page of compact template metadata. Pass a non-null `nextCursor` back as `cursor` to continue. Use `rect_get_spec` separately to inspect a template.
`rect_list_instances`	List one page of issued instances across authenticated accessible accounts. Optionally filter by `accountId`, `rectId`, or `status`, and sort by `issued` (default) or `updated`; pass a non-null `nextCursor` back as `cursor` with the same sort to continue.
`rect_list_accounts`	List the authenticated user's workspaces and their account IDs. Use the selected `accountId` to scope member, instance, and issue operations, or to narrow template listing to one workspace.
`rect_list_members`	List one explicitly selected workspace's members for shaping into a `rect_issue` view model. `accountId` is required; call `rect_list_accounts` first when unknown. Prefer workspace access when member emails are present.
`rect_get_spec`	A template's spec before issuing or updating: when to use it, its `rect.agent.md` instructions, example state, view-model schema, and named-actions catalog.
`rect_issue`	Issue a new live instance and return the URL to show the human. Takes an optional initial `viewModel` (defaults to the spec's `example`), a `name`, and independent `readAccess` / `writeAccess` scopes. Prefer clear names from the content over template names.

Omit accountId by default to list all visible public and workspace templates. Pass accountId to narrow the template list to one workspace.

Listing issued instances uses the connected user's access. Omit accountId to list all accessible accounts, or pass it to narrow the result to one workspace. Results are newest issued by default; set sort to updated for most recently updated.

Drive

Tool	What it does
`rect_dispatch`	Atomically run one or more of the view's named actions. Provide an `actions` array whose inputs match the catalog in `rect_get_spec`. Actions run in order; if one fails, none are saved. Preferred over `rect_patch` whenever actions exist.
`rect_patch`	Apply an RFC 7386 JSON Merge Patch to the view model. For free-form edits no action covers. Views with `patchPolicy: "actions-only"` refuse it and point you at the actions catalog.
`rect_get_result`	Read the latest view model and revision of an instance.

Attachments

Tool	What it does
`rect_create_attachment_upload`	Create a signed Storage upload ticket. Registers an `uploading` item in the reserved `$attachments` registry; upload the bytes to the returned ticket, then complete.
`rect_complete_attachment_upload`	Finish a signed upload: verifies the Storage object, marks the attachment `done`, updates `$attachments`.
`rect_upload_attachment`	Small-file convenience: base64 bytes in the tool call itself. Prefer the signed-upload pair for anything that isn't tiny.
`rect_attach_to_screen`	Make a ready file available to a target Screen. Copy `source` and the attachment id from its descriptor.

Attachment tools update $attachments themselves — dispatch afterwards only if the view needs domain linking. For App workflows, rect_get_app_run also returns ready attachment summaries. Call rect_attach_to_screen before dispatching a later Screen's file-import action.

Dispatch results & rejections

rect_dispatch accepts 1–32 actions and returns the updated snapshot on success. Failures come back as structured codes the agent can plan on, not prose:

Code	Meaning
`rejected`	The handler called `ctx.reject` — a business rejection. Carries the view's own `rejectCode` (e.g. `TODOS_OPEN`) and message. Re-plan and retry.
`invalid_input`	Input failed the action's `inputSchema`. Fix the input.
`unknown_action` / `no_actions`	Wrong action name / the view declares none. Check `rect_get_spec`.
`patch_policy`	A `rect_patch` hit an `actions-only` view. Use `rect_dispatch`.
`reserved_key`	The write touched a host-owned namespace like `$attachments`.
`conflict`	Concurrent writes kept winning — re-read and retry.
`runtime_error` / `timeout` / `too_large`	The handler crashed, overran its CPU deadline, or produced an oversized state.

Working with the human

rect_issue returns more than a URL:

url — show this to the human. Opening and editing it follow the instance's readAccess and writeAccess scopes.
revision — compare against later rect_get_result reads to see whether anything changed. If the view models an explicit end state (submitted, approved), read for that; otherwise ask the human to tell you when they're done.

While the human works, everything you dispatch or patch appears in their open view instantly — and authorized edits are in your very next read.

On this page