MCP

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.

Template discovery descriptions answer when to use a Rect. 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/api/mcp/rectsh

For Claude Code:

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

For Codex:

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

Any other MCP client configures the same URL as a remote HTTP server. A plain GET on the endpoint (without an event-stream Accept header) returns a JSON info document listing the tools and the HTTP fallback endpoints — useful as a health check.

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_search_templates          what best fits the task?
rect_list_templates            fallback: browse the available catalog
rect_get_spec                  what shape does this template want?
                               (agent instructions + example state + actions catalog)
rect_issue                     create a live instance → show the human its URL
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.

Tools

Discover & issue

Tool	What it does
`rect_search_templates`	Run keyword-based search across template names, descriptions, actions, and state fields. Call `rect_get_spec` for the selected `rectId`; fall back to `rect_list_templates` when search is unavailable or unhelpful.
`rect_list_templates`	List the templates that can be issued as live instances.
`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`) and a `name` — prefer clear identifiers from the content (person, company, project) over template names.

Keyword-based search matches words and phrases across curated template fields. It returns 10 compact candidates by default (maximum 20). Without an Authorization bearer token, search and list include public templates only; authentication also includes the caller's workspace templates. Passing accountId narrows discovery to a workspace the caller belongs to.

Drive

Tool	What it does
`rect_dispatch`	Run one of the view's named actions. The view defines the business logic server-side; you pick the action and provide input matching its `inputSchema`. Preferred over `rect_patch` whenever actions exist — the handler validates business rules and can reject with a structured code.
`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.

Attachment tools update $attachments themselves — dispatch afterwards only if the view needs domain linking.

Dispatch results & rejections

rect_dispatch 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:

viewUrl — show this to the human; it's their whole login.
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 their edits are in your very next read.

MCP

On this page