MCP reference

Use this page to look up how an MCP client connects to Reflex and what it can do. To set up a tool, start with Work with AI.

Endpoint

https://<server>/mcp (Streamable HTTP). The server checks your project access and sends execution to the project’s agents. An administrator can turn the endpoint off with MCP_ENABLED=false.

Sign in

• OAuth (default). Your client opens a Reflex consent page that shows the client and the scopes it asks for. Grant only what you need. Revoke a client under Profile → API tokens.
• Bearer token (headless). Send Authorization: Bearer <token> with a personal access token (rfx_pat_…) or a service-account token (rfx_sat_…). Create one under Profile → API tokens.

A token never grants more than your project role allows.

Scopes

A client only sees tools that its scopes and your role allow. Management scopes are opt-in.

Scope	Allows
projects:read, files:read, access:read	See projects, files, members and roles.
runs:read, jobs:read, suites:read	Read runs, logs, digests, replays and health.
runs:execute, jobs:run, suites:run	Start runs, jobs and suites.
runs:debug	Attach the live debugger.
heals:read, heals:propose	Read the heal inbox; propose and verify heals.
heals:review	Accept or reject heals.
secrets:write	Ask for secret input links.
jobs:write, suites:write, jobs:enable, suites:enable	Change definitions; pause and resume schedules.
browser:remote, agents:manage, projects:write, files:write, members:write	Remote browsers, agents, project setup, files, membership.

Call whoami to see your user and scopes. list_projects shows which scopes work in each project.

Tools

Area	Tools do this
Discover	List projects and library documentation.
Scripts	Validate a script; start a run from a server file or from your working copy.
Runs	Read status, masked logs, events and failure digests; cancel a run.
Jobs and suites	List, trigger, and check health.
Debug	Attach, read state, send commands (wait, retry, continue), read patches.
Replay	Read actions, frames and the DOM; test a selector on a recorded page.
Heals	List, propose, verify, and (with heals:review) accept or reject.
Manage	Projects, members, roles, files, agents, remote browser sessions.

Run tools return an ID at once; poll for status and events. Each tool description names the scope it needs.

Enter a secret without the AI

Your assistant can ask you for a project or development secret but never receives the value.

1. The assistant calls prepare_project_secret (one value) or prepare_project_secrets (up to 20, as production or development values). It needs secrets:write.
2. Reflex returns a link. Open it yourself and sign in if asked.
3. Check the project, secret name and environment, then enter the value.
4. The assistant calls get_secret_input and sees only whether you finished.

The link works once and expires after 10 minutes. Development values need the project owner or an administrator.

The assistant must never open the form or take the value in chat.

In a terminal, run reflex secret set api_key --remote --project owner/project for a hidden prompt. Add --dev for a development value, or use --stdin or --from-file in a trusted pipeline. Scripts read the value with secret("api_key").

Caution

A script that receives a credential can send it elsewhere. Output masking helps, but it does not sandbox a script. Only run scripts you trust.