Reference

For setup instructions, see Connect.

Endpoint

Reforma does not expose an SSE endpoint and does not use API keys.

Clients should connect using the MCP server URL directly.

Authentication

Reforma MCP uses OAuth 2.1 with PKCE S256.

Access tokens are issued for the signed-in Reforma user, with:

aud=reforma-mcp

The token can access every workspace the user belongs to.

A Reforma application session cookie cannot be used to call the MCP endpoint.

Clients that support an HTTPS client_id metadata document can use it directly. Other clients can register dynamically through /oauth/register.

Requests with a missing, invalid, or wrong-audience Bearer token return 401 with a WWW-Authenticate header pointing to the protected resource metadata.

To revoke a client, open Profile → Security and login → Connected apps in Reforma.

Project lifecycle

Most tools operate on a project sandbox.

A typical session is:

1. Call list_projects.
2. Call open_project with a project id.
3. Use that project_id for subsequent project tools.

open_project provisions or reuses the project's dev sandbox.

The Reforma editor and MCP share the same sandbox and worktree.

If the sandbox has been idle for one hour, it is stopped automatically. Call open_project again to resume.

There is no close_project tool.

Resources

These are MCP resources provided by Reforma. They are not files in the project sandbox.

Tools

Unless noted otherwise, project tools require a positive integer project_id and an active sandbox created by open_project.

create_upload and complete_upload require a project_id, but do not require the sandbox to be running.

The worktree lives in Reforma's cloud sandbox, not on the client machine.

Do not start or stop the managed Next.js development server through bash.

Identity and projects

get_me

Returns the signed-in Reforma user.

Arguments: none.

{
  "id": 1,
  "email": "[email protected]",
  "name": "You"
}

list_projects

Returns projects available to the current user, grouped by workspace.

Arguments: none.

{
  "workspaces": [
    {
      "id": 1,
      "name": "Acme",
      "status": "active",
      "projects": [
        {
          "id": 10,
          "name": "Site",
          "status": "active",
          "workspaceId": 1
        }
      ]
    }
  ]
}

Pass a project id from this response to open_project.

open_project

Provisions or reuses the project's dev sandbox and returns its preview URL.

{
  "id": "…",
  "previewUrl": "https://…",
  "status": "active"
}

Files

File paths are relative to the project sandbox unless an absolute project path is supplied.

read

Reads UTF-8 text or PDF files.

Text is returned in windows of up to 200 lines by default. PDFs use pages instead of lines. The total field indicates whether more content remains.

write

Creates or overwrites a file.

edit

Replaces text in an existing file.

Read the file before editing it. Multiple replacements for the same file can be sent in one call.

list_directory

Lists files and directories.

sizeBytes is returned for files only.

glob

Finds paths matching one or more glob patterns. Results are ordered newest first.

grep

Runs ripgrep against the project worktree.

create_directory

Creates a directory.

move_file

Moves or renames a file or directory.

remove_file

Removes one or more paths.

Shell and dependencies

bash

Runs a command in the project sandbox.

Each invocation has its own working directory unless cwd is provided. Quote paths containing spaces and use shell operators such as && when commands must run sequentially.

Foreground commands default to a 120-second timeout and may run for up to 600 seconds.

Background commands return:

{
  "id": "…",
  "pid": 123,
  "log": "…"
}

Use the returned id to poll or stop the process. Do not use the OS pid.

A successful stop reports status: killed on the kill call.

install_deps

Installs project dependencies using Bun and restarts the managed development server.

Use this tool instead of running bun install through bash.

The response includes the executed command, Bun output, and whether the development server was restarted.

read_lints

Formats and validates changed files.

The tool runs:

biome check --write
tsc --noEmit

Because Biome runs with --write, this tool may modify files.

Prefer passing only the files or directories changed during the task.

Development server

The project's Next.js development server is managed by Reforma.

Do not start or stop it using bash.

dev_server_status

Returns the current development server state and recent logs.

dev_server_restart

Restarts the managed development server.

Assets

There are two ways to add an asset, depending on where the source file lives.

Use import_asset when the source is already reachable by Reforma:

• an http:// or https:// URL;
• a file under public/;
• a scratch file under /tmp/reforma.

Use create_upload → upload the bytes → complete_upload when the file exists on the client machine, such as a generated image, screenshot, or video.

Do not send file bytes through JSON-RPC or data URLs.

import_asset

Imports an existing asset into Reforma.

Scratch files can only be imported to the CDN.

create_upload

Creates a presigned PUT URL for a client-local file.

Maximum file size: 50 MB.

The PUT URL expires after 15 minutes.

{
  "asset_id": "…",
  "put_url": "https://…",
  "headers": {
    "Content-Type": "image/png"
  },
  "expires_in": 900
}

Upload the file bytes directly to put_url:

curl -T ./hero.png \
  -H "Content-Type: image/png" \
  "$PUT_URL"

complete_upload

Confirms that the uploaded object exists and adds it to Reforma's CDN.

Call this only after the PUT request succeeds.

{
  "ok": true,
  "destination": "cdn",
  "id": "…",
  "url": "https://cdn…/…",
  "filename": "hero.png",
  "mediaType": "image/png",
  "size": 12
}

If the object has not been uploaded yet, the call fails instead of creating an empty asset.

Versions and publishing

commit

Creates a version checkpoint.

Before creating the checkpoint, Reforma runs lint validation.

If validation fails, no version is created and the response returns reason=lint with diagnostics.

If there are no uncheckpointed changes, the call is a no-op with reason=clean. Autosave may already have created the latest checkpoint.

Use list_versions to inspect the current state.

list_versions

Returns the project's current, draft, and published versions.

This is the same version state shown in the Reforma version panel.

No arguments other than project_id.

publish

Publishes the project using the same pipeline as the Reforma Publish button.

The call waits until deployment succeeds or fails.

On success, it returns the live URL. On failure, it returns deployment logs.

No arguments other than project_id.

Runtime behavior