Recess Get a live link

Recess docs

Show your AI Recess. Get the live link back.

Start with one plain ask. Recess handles login, opens the WordPress idea as a playable Yard, returns the clean link first, and keeps a saved copy ready for the next edit.

Say this Use Recess for this WordPress idea. When Recess opens, I will log in. Bring back the live Yard link first.
Show your AI where to go See the link flow
Start with the plain ask

Use this when your AI understands normal instructions. It keeps the useful answer short: live link first, details only when helpful.

Use Recess for this WordPress idea. When Recess opens, I will log in. Bring back the live Yard link first.
Simple ask
When it asks for a link

Some AI apps ask where Recess lives. Give them this link, log in through Recess, and let the Yard come back ready to send.

https://mcp.recess.host/mcp
Recess link
Try it 200 OK 
{
  "prompt": "Open my tiny portfolio as a Yard.",
  "title": "First Yard"
}
Use request
One plain ask Normal login Live Yard Clean link first
What your AI should do No setup maze

Ask for Recess, log in when asked, then send the link Recess returns. That is the happy path.

Say “use Recess for this.” Log in through Recess. Send the clean live link.
Cursor Claude ChatGPT Other AI tools

Simple start

Point your AI at Recess. Log in once. Done.

For normal use, tell your AI to use Recess and log in when Recess asks. That is the whole magic trick. The Recess link is here only when something asks where to go.

Use this Recess link https://mcp.recess.host/mcp

Quickstart

Start with the plain ask: use Recess, log in when Recess opens, and bring back the live Yard link first. If an app asks for a link, use the Recess link. If you are wiring a product or script, the exact calls and response shapes are below.

1 Point your AI

Give it the Recess link and let Recess open the login screen.

2 Open the Yard

Recess turns the WordPress idea into something people can click around.

3 Send the link

Return the clean Recess link first, with details only when asked.

Recess linkbash
export RECESS_MCP_URL="https://mcp.recess.host/mcp"

In normal AI tools, Recess handles login automatically. The manual examples below are only for people testing requests by hand.

Connected-app smokebash
RECESS_WORKSPACE_KEY="..." \
RECESS_LOGIN_EMAIL="you@example.com" \
npm run smoke:mcp-oauth

The smoke command behaves like an app using Recess, calls resources/list and tools/list, and never prints the issued access token.

Set the raw curl auth headerbash
export RECESS_AUTH_HEADER="Authorization: Bearer $RECESS_OAUTH_ACCESS_TOKEN"
Status checkbash
curl "$RECESS_MCP_URL" \
  -H "$RECESS_AUTH_HEADER"
Initializebash
curl -X POST "$RECESS_MCP_URL" \
  -H "$RECESS_AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }'
List toolsbash
curl -X POST "$RECESS_MCP_URL" \
  -H "$RECESS_AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Where Recess Lives

These are the public Recess surfaces. Normal users only need the Recess link; the other URLs are for builders checking app, launch, and runtime behavior.

Recess linkhttps://mcp.recess.host/mcp
APIhttps://api.recess.host
Launch originhttps://try.recess.host
Runtime hosthttps://run.recess.host/

Log In

For normal use, tell your AI to use Recess and let Recess open the login screen. Approved apps keep the selected account through the whole Yard flow.

Recess login linktext
URL: https://mcp.recess.host/mcp
Scopes: yards:read yards:write
Internal/dev bearer fallbackhttp
Authorization: Bearer YOUR_TOKEN
Browser apps

The Recess app Worker proxies browser requests server-side. Browser JavaScript should call the app's same-origin /api/agent/yards, not carry a shared API bearer token.

When Your App Asks

Most modern AI apps can use the Recess link directly and log in through Recess. Older local setups can use a bridge that forwards the same requests.

Recess linkjson
{
  "mcpServers": {
    "recess": {
      "url": "https://mcp.recess.host/mcp"
    }
  }
}
Stdio bridgejson
{
  "mcpServers": {
    "recess": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.recess.host/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Bearer headers are only for internal or development deployments. Normal users should log in through Recess instead.

Update Without Losing The Saved Recipe

Use update_playset for title, summary, or prompt notes without disturbing the stored recipe. Send a replacement blueprint only when the user explicitly wants the Yard recipe changed.

Answer Shape

Builder detail: Recess calls return text content. Parse the text as JSON before reading ids, manifests, or URLs.

Tool responsejson
{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"playset\": {}\n}"
      }
    ]
  }
}
Parse ruletext
JSON.parse(response.result.content[0].text)

Core workflow

IdeaSaved copyLive YardClean linkExport on request

The canonical path is create_playset to create_yard to publish_pass. Send a full blueprint to create_playset when the user already has one; Recess stores it exactly. Return the clean Pass URL, not a raw playground.wordpress.net URL. Call export_blueprint only when the user asks for the portable recipe.

Action Reference

These are the current actions Recess exposes to connected assistants and builder integrations.

get_account

Inspect the signed-in account, included Recess address, billing, entitlement, limits, and auth scope.

Required
none
Optional
accountId

bootstrap_account

Create or repair the account record so Recess can start without app setup chores.

Required
none
Optional
accountName, accountSlug, userEmail, userName, role, accountId

get_billing

Read plans, billing setup, checkout pause state, current entitlement, and limits.

Required
none
Optional
accountId

create_billing_checkout

Create a hosted Checkout session when the user asks to upgrade and the plan is not paused.

Required
none
Optional
plan, interval, successUrl, cancelUrl, customerEmail, accountId

open_billing_portal

Open hosted billing management for payment, invoices, cancellation, or card fixes.

Required
none
Optional
returnUrl, accountId

list_domains

List branded domains and the included Recess address.

Required
none
Optional
accountId

create_domain

Connect a customer-owned subdomain and return DNS instructions.

Required
hostname
Optional
accountId

get_domain

Read verification, SSL, and DNS state for a customer domain.

Required
domainId
Optional
accountId

refresh_domain

Refresh customer-domain verification and SSL status.

Required
domainId
Optional
accountId

delete_domain

Remove a customer domain from the account.

Required
domainId
Optional
accountId

create_playset

Create a reusable Playset from an exact Blueprint, or from a fallback Blueprint-shaped prompt when no Blueprint exists.

Required
blueprint or prompt
Optional
title, summary, accountId

update_playset

Revise Playset metadata while preserving the stored Blueprint unless a replacement Blueprint is supplied.

Required
playsetId
Optional
prompt, title, summary, blueprint, accountId

create_yard

Create a playable draft Yard from a Playset.

Required
playsetId
Optional
title, accountId

publish_pass

Publish a Yard and create a clean Pass URL.

Required
yardId
Optional
origin, accountId, force, prebuildPolicy, slug, domainId, visibility, expiresAt, accessMode, password, passwordHint

update_pass

Update sharing controls for an existing clean Pass URL.

Required
slug
Optional
domainId, visibility, expiresAt, accessMode, password, passwordHint, accountId

revoke_pass

Revoke a clean Pass URL so it no longer launches.

Required
slug
Optional
domainId, accountId

disable_pass

Disable a clean Pass URL; useful when an AI user says turn this link off.

Required
slug
Optional
domainId, accountId

list_yards

List recent account Yards with safe version, screenshot, prebuild, and Pass-count summaries.

Required
none
Optional
limit, accountId

list_passes

List clean Pass URLs for a Yard.

Required
yardId
Optional
accountId

get_pass

Inspect one clean Pass URL and its sharing controls.

Required
slug
Optional
domainId, accountId

get_yard_status

Return the current Yard record.

Required
yardId
Optional
accountId

list_yard_versions

List version history for a Yard.

Required
yardId
Optional
accountId

get_yard_version

Read one Yard version; Blueprint and raw manifest require explicit include flags.

Required
yardId, versionSelector
Optional
includeBlueprint, includeManifest, accountId

revise_yard

Move an existing Pass slug to a revised Yard version while keeping the same share URL.

Required
yardId, passSlug
Optional
title, prompt, summary, blueprint, force, domainId, sharing controls, prebuildPolicy, banner, accountId

get_account_activity

Read account-level launch activity.

Required
none
Optional
days, from, to, limit, accountId

get_yard_activity

Read Yard-level launch activity.

Required
yardId
Optional
days, from, to, limit, accountId

get_pass_activity

Read Pass-level launch activity.

Required
slug
Optional
domainId, days, from, to, accountId

export_blueprint

Export the stored portable WordPress recipe.

Required
playsetId or yardId
Optional
accountId

upload_asset

Return HTTP upload instructions for a named asset; bytes upload through the API.

Required
filename
Optional
contentType, yardId

take_screenshot

Create a durable async screenshot job for a Yard Pass when available.

Required
yardId
Optional
passSlug, accountId

validate_blueprint

Validate a Blueprint before updating or publishing.

Required
blueprint
Optional
none

Create A Yard

This is the happy path most AI tools should run when a user asks for a WordPress Yard.

1. create_playsetjson
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "create_playset",
    "arguments": {
      "title": "First Yard",
      "blueprint": {
        "$schema": "https://playground.wordpress.net/blueprint-schema.json",
        "meta": {
          "title": "First Yard",
          "description": "AI-made WordPress ideas ready for a Recess Yard.",
          "author": "Recess",
          "categories": ["recess"]
        },
        "landingPage": "/wp-admin/",
        "preferredVersions": { "php": "8.4", "wp": "latest" },
        "features": { "networking": false },
        "steps": [{ "step": "login", "username": "admin" }]
      }
    }
  }
}
2. create_yardjson
{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "create_yard",
    "arguments": {
      "playsetId": "playset_..."
    }
  }
}
3. publish_passjson
{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "publish_pass",
    "arguments": {
      "yardId": "yard_..."
    }
  }
}
Expected result{"shareUrl":"https://try.recess.host/odd"}
Export only when asked

The clean Pass URL is the default handoff. Use export_blueprint when the user asks for the portable WordPress recipe or wants to move the idea elsewhere.

Optional export_blueprintjson
{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "export_blueprint",
    "arguments": {
      "yardId": "yard_..."
    }
  }
}

Same-Pass Review Loop

Paid-value handoffs usually need another round. Keep the same clean Pass URL, update the Yard behind it, and return the shareUrl first so people do not chase a fresh link every time the page improves.

Control the door

Use update_pass for visibility, expiry, and password access on the existing Pass. Send password only when setting or replacing it.

Revise the Yard

Use revise_yard to update the Yard behind an existing Pass while keeping the same clean shareUrl.

Prove the round

Use take_screenshot for async proof and prebuildPolicy only as launch-prep evidence, never as a public speed claim by itself.

Lock the Pass for reviewjson
{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "update_pass",
    "arguments": {
      "slug": "odd",
      "visibility": "unlisted",
      "accessMode": "password",
      "passwordHint": "Ask the launch lead"
    }
  }
}
Move the same Pass to the next versionjson
{
  "jsonrpc": "2.0",
  "id": 16,
  "method": "tools/call",
  "params": {
    "name": "revise_yard",
    "arguments": {
      "yardId": "yard_...",
      "passSlug": "odd",
      "summary": "Updated review round after feedback.",
      "blueprint": {
        "$schema": "https://playground.wordpress.net/blueprint-schema.json",
        "meta": { "title": "Next Review Round" },
        "landingPage": "/",
        "preferredVersions": { "php": "8.4", "wp": "latest" },
        "features": { "networking": false },
        "steps": []
      }
    }
  }
}
Queue screenshot proofjson
{
  "jsonrpc": "2.0",
  "id": 16,
  "method": "tools/call",
  "params": {
    "name": "take_screenshot",
    "arguments": {
      "yardId": "yard_...",
      "passSlug": "odd"
    }
  }
}
NeedUse
Normal publishprebuildPolicy: "auto"; this is the default.
Proof or paid prepprebuildPolicy: "force" when waiting for prebuild evidence is acceptable.
Immediate linkprebuildPolicy: "off" when the clean Pass matters more than queueing prep work.
Human answerReturn Yard published: {shareUrl} first, then add controls, screenshot status, or exported Blueprint only when asked.

HTTP API Quickstart

Use the HTTP API when you do not need MCP and want direct app-style integration. These examples are production-copyable for trusted server-side environments, CLIs, or MCP clients. Browser code should use the app Worker proxy instead of sending a shared API token.

Machine-readable routes

Agents and server-side tools can fetch the OpenAPI document at /.well-known/openapi.json or /openapi.json. Logged-in AI tools still use only https://mcp.recess.host/mcp.

OpenAPI discoverybash
curl https://recess.host/.well-known/openapi.json
Set API authbash
export RECESS_API_TOKEN="..."
export RECESS_ACCOUNT_ID="acct_..."
One-request Yard creationbash
curl -X POST https://api.recess.host/api/agent/yards \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RECESS_API_TOKEN" \
  -H "X-Recess-Account: $RECESS_ACCOUNT_ID" \
  -d '{
    "prompt": "Publish my AI-made WordPress idea for a tiny launch page as a Yard.",
    "title": "First Yard",
    "visibility": "public",
    "slug": "odd",
    "expiresAt": null,
    "accessMode": "open"
  }'
FieldMeaning
playsetStored reusable prompt, summary, and Blueprint source record.
yardPublished Yard record.
passClean Pass record with a slug.
shareUrlClean Pass URL to return to the user.
blueprintPortable WordPress recipe.
manifestLaunch manifest with Blueprint, preview, runtime, speed profile, and prebuild status.
validationBlueprint validation result.
summaryHuman-readable Playset summary.
followUpQuestionsOptional publishing follow-ups.

Validate A Blueprint

Recess validates the publishing shape before a Pass is created. Blueprints need the Playground schema URL, a title, a relative landing page, PHP and WordPress versions, and an array of steps.

validate_blueprintjson
{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "validate_blueprint",
    "arguments": {
      "blueprint": {
        "$schema": "https://playground.wordpress.net/blueprint-schema.json",
        "meta": {
          "title": "Tiny Plugin Yard",
          "description": "A Recess Yard.",
          "author": "Recess",
          "categories": ["recess"]
        },
        "landingPage": "/wp-admin/",
        "preferredVersions": { "php": "8.4", "wp": "latest" },
        "features": { "networking": false },
        "steps": [{ "step": "login", "username": "admin" }]
      }
    }
  }
}
Recommended baseline

Include a login step so the Yard opens signed in. Keep features.networking false unless the Blueprint truly needs live downloads.

Launch Artifacts

publish_pass creates and caches the launch artifacts used by try.recess.host. Public launch traffic should use the first-party runtime host; call shell/runtime speed a shell/runtime win until click-to-usable proof clears the public claim bar.

ArtifactWhere it appears
shareUrlClean public Pass URL to open the Yard, like https://try.recess.host/odd.
manifest.blueprintUrlImmutable Blueprint JSON URL.
manifest.playgroundBaseUrlRuntime URL. Production should normalize to https://run.recess.host/.
manifest.prebuildCurrent prebuild truth for the Yard version.
manifest.assetsVersion assets. Completed screenshots attach here.
Light Playsets

Usually return prebuild.status: "not_required" and launch from a small Blueprint.

Heavy Playsets

May return prebuild.status: "queued". Treat only "ready" plus a bundle as a ready prebuilt Yard.

Screenshots

take_screenshot is async. Jobs can become completed, skipped, or failed; it does not return an image synchronously.

Proof And Claim Boundaries

Recess publishes machine-readable proof surfaces so humans and AI teammates can say what the product has actually verified. Read these before writing speed, accessibility, uptime, paid-plan, or boundary copy that says Recess is not production WordPress hosting. Receipts are good. Invented trophies are not invited to recess.

Speed status

/.well-known/recess-speed-claim.json is the source for public speed language. The current proof supports exact-scope basic/front-page language only; broad speed-crown claims remain blocked.

Accessibility status

/.well-known/recess-accessibility.json reports the static route and contrast audit. It is not a WCAG certification, VPAT, or substitute for human assistive-technology testing.

Status manifest

/status.json reports public-path expectations. It is not an uptime promise or incident-history replacement until live checks back it.

Agent rule

Before summarizing Recess, fetch the proof URL for the claim you are making. If the proof is missing, blocked, not ready, or static-only, say that plainly and keep building the Yard.

Embed A Try Button

Put a clean Try in Recess button wherever you show an AI-made WordPress project. Use the Pass slug you already published; the script keeps raw Playground URLs out of your page.

Try in Recess buttonhtml
<div data-recess-pass="odd"></div>
<script async src="https://recess.host/embed/try-button.js"></script>
Custom labelhtml
<div data-recess-pass="odd" data-recess-label="Open the Yard"></div>
<script async src="https://recess.host/embed/try-button.js"></script>
Agent handoff

When an AI tool publishes a Pass, it can give the user both the clean shareUrl and this embed snippet. The only public link should still be the Recess Pass URL.

Errors And Troubleshooting

401

Complete Recess login or send a valid internal/dev bearer token.

404

Send JSON-RPC calls to POST /mcp.

415

Set Content-Type: application/json.

Blueprint failed

Call validate_blueprint, revise with update_playset, then publish again.

Not found

Check the id and accountId or X-Recess-Account.

Unsupported method

Use initialize, tools/list, tools/call, resources/list, or resources/read.

No share link

Call publish_pass; create_yard only creates a draft Yard.

Runtime host

Launch manifests should use https://run.recess.host/ for Playground runtime files.

WASM MIME

Runtime .wasm files must return application/wasm or Playground boot can fail before WordPress is usable.

CORS

Blueprint, preview, and asset URLs must be cross-origin readable when the runtime fetches them from the Yard shell.

Screenshot queued

Expected. Inspect job.status and job.output.reason until capture completes or skips.

Accessibility claim

Use the accessibility status JSON for static audit proof, but do not call Recess certified or VPAT-ready without human assistive-technology review.

Agent checklist Use Playset, Yard, Pass, Field Trip, and Blueprint. Return the clean shareUrl after publish_pass. Preserve ids exactly as returned. Do not call force: true without explicit approval. Do not present queued screenshots or prebuilds as complete. Do not make speed claims beyond measured evidence; separate first-party shell/runtime speed from public click-to-usable claims. Do not turn static accessibility checks into compliance claims.