For AI agents · Beta

FlowState Relay setup: instructions for AI agents

You are an AI agent helping your user reach their own FlowState (a local MCP server) from cloud AI apps through FlowState Relay. Follow the steps in order; each says how to check it. Plain text: https://flowstatemcp.com/setup/agents.md. For people: https://flowstatemcp.com/setup.

Rules

• Ask firstAsk the user before you install anything, change an app's config, start a long-running process, or create a scheduled or auto-start task. Say exactly what you will run.
• No secrets in chatNever ask the user to paste a secret into the chat: not the enroll code, the owner passphrase, a per-app key or token, or a device token. The user types those into their own terminal.
• Never print the device tokenIt is stored owner-only in the relay folder inside FlowState's data folder. Don't open, print, copy or log the files there. FS relay status says Device token: stored (not shown); that is all you need.
• Plain wordsIf a step fails, stop and tell the user what failed and what to do next. Don't work around it silently.
• Wrong packageDon't pip install flowstate from PyPI: that name belongs to an unrelated project. FlowState is installed from its GitHub repository; its setup script installs it into .venv in the FlowState folder.

Facts

• Addresshttps://<handle>.fsmcp.com/mcp, where <handle> is given at enroll.
• Limits1 device per account. An enroll code works once and is valid for 15 minutes. 5 codes per account per hour.
• Beta10 spots. When full, enroll puts the user on a waitlist, first come, first served; a spot that opens is held 48 hours for the first in line.
• AccountOnly the user can sign in: https://flowstatemcp.com/signin (Google, GitHub or a 6-digit email code). Enroll codes come from https://flowstatemcp.com/account.
• PriceFree for 6 months from signup; then beta members keep half price (Relay $3/mo, Hosted $6/mo). Billing is not live: never promise a checkout.
• PrivacyTLS passthrough: the TLS key is made on the user's computer and never leaves it; the relay sees only connection times, client addresses and byte counts.
• SecurityHow FlowState, the relay and the account site are secured, and their limits: https://flowstatemcp.com/security

1. Install or update FlowState

The relay agent is part of FlowState 2.2.0 and newer. New install: follow https://github.com/dialectforge/FlowState/blob/main/AGENTS.md. Short form (needs Python 3.11+ and git; PY is python3 on macOS/Linux, python or py -3 on Windows; ask the user which apps to pass to --clients):

git clone https://github.com/dialectforge/FlowState.git FlowState
cd FlowState
PY setup_flowstate.py --clients claude-desktop --schedule-backups --no-offsite --install-skill --dry-run
PY setup_flowstate.py --clients claude-desktop --schedule-backups --no-offsite --install-skill --verify

Already installed: ask the user, then update it in the FlowState folder, passing the same --clients the user chose before:

git pull
PY setup_flowstate.py --clients claude-desktop --schedule-backups --no-offsite --install-skill --verify

The database is kept. Check: --verify reports that start_here answered. From here on, FS means .venv\Scripts\python -m flowstate on Windows and .venv/bin/python -m flowstate on macOS/Linux, run in the FlowState folder.

2. Check for the relay agent

FS relay --help

If it lists enroll, run and status, the relay agent is installed. If it fails because relay is not a valid choice, this FlowState is older than 2.2.0: update it (step 1), then check again. Get it only from https://github.com/dialectforge/FlowState, nowhere else.

3. Account and enroll code (the user)

Ask the user to sign in at https://flowstatemcp.com/signin, open https://flowstatemcp.com/account and press Get an enroll code. Tell them it works once, for 15 minutes, and not to paste it to you.

4. Owner passphrase (the user, once)

The user runs this in their own terminal. It prompts for a passphrase (12+ characters); don't run it for them and don't pipe input to it.

FS remote passphrase

Check: FS remote status shows Owner passphrase: set.

5. Enroll (the user)

The user runs this in their own terminal, with their code:

FS relay enroll --code <code>

Success prints Enrolled. Your relay address: https://<handle>.fsmcp.com/mcp and then Certificate obtained for .... The address is not a secret: read it from FS relay status (the URL: line) or ask the user for it.

6. Run the relay agent

Ask before starting it. It keeps running and logs to its terminal.

FS relay run

It runs FlowState's public listener on 127.0.0.1:8768 (--port to change), the tunnel, certificate renewal and a daily Certificate Transparency check. FlowState has no built-in auto-start: after a restart, FS relay run must be started again. Tell the user that. You may offer to make it start at sign-in with the OS's own tools (Windows Task Scheduler, a macOS launchd LaunchAgent, a Linux systemd user service) that run FS relay run in the FlowState folder; the human guide has each one (https://flowstatemcp.com/setup#run). Create it only after the user says yes, then stop any copy you started by hand, and tell them how to remove it.

7. Check it worked

FS relay status

Expect Relay: ON, URL: https://<handle>.fsmcp.com/mcp, Device token: stored (not shown), Certificate: valid until ... and Tunnel: connected .... Exit code 2 means a Certificate Transparency warning: show the user the warning lines exactly as printed.

Health check through the relay (no token needed; on Windows use curl.exe):

curl -s https://<handle>.fsmcp.com/health

Expect {"ok": true, "service": "flowstate"}.

MCP initialize without a token (macOS/Linux shell):

curl -si -X POST https://<handle>.fsmcp.com/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-check","version":"1"}}}'

Expect status 401 with a WWW-Authenticate: Bearer header that points to /.well-known/oauth-protected-resource. That is correct: the request reached FlowState through the relay, and FlowState asks for sign-in. A closed connection, a TLS error or a timeout means the device is not connected: FS relay run is not running, or the computer is asleep or offline.

8. Errors and what to tell the user

• waitlisted (429)From POST https://api.fsmcp.com/api/enroll: {"error": "waitlisted", "reason": "active" or "weekly", "retry_after": <unix time>, "position": <n>, "message": "..."} and a Retry-After header in seconds. The CLI prints "The FlowState Relay beta is full right now. You're on the waitlist (number N). ..." (or, for the weekly limit, "... try again after <time>") and "No token or key was saved on this computer." Tell the user: they are number N on the waitlist, the code was not used, and they can run the same enroll command again later; their account page shows their place.
• device_limit (409)When getting a code on the account page; the page says "Your account has 1 device, the most it can have." Enroll can also get 403 device_limit; the CLI prints Relay: relay answered 403 (device_limit). Tell the user: one device per account; use Replace this device on the account page (it removes the old device and gives a new code). The code was not used.
• code_limit (429)When getting a code: 5 codes per account per hour; the page says "You have asked for 5 codes in the last hour." Tell the user to wait, then get a new code.
• Expired or used code (400)invalid_code: the CLI prints Relay: relay answered 400 (invalid_code). The code was wrong, already used, or older than 15 minutes. Tell the user to get a new code.
• rate_limited (429)Too many enroll tries from this address. The CLI prints Relay: the relay is busy or you tried too often (429); wait a while and try again (rate_limited). Tell the user to wait an hour.
• Already enrolledThe CLI prints Already enrolled as <handle>.fsmcp.com. To start over: flowstate relay forget. Don't run forget without asking: it deletes the device token and keys, and the handle stays taken until the user removes the device on the account page.
• Tunnel: unauthorizedIn FS relay status: the device was removed or suspended on the account page. Ask the user to check it there.
• Owner passphrase: NOT setApps can't be approved. The user runs FS remote passphrase.

9. Connect the user's apps

Apps on the same computer use FlowState directly (step 1) and don't need the relay. For cloud apps, phones and other computers, give the user the address https://<handle>.fsmcp.com/mcp.

• claude.aiSettings, then Connectors, then Add custom connector; paste the address, Connect, then approve on the FlowState page with the owner passphrase.
• ChatGPTSettings, then Connectors (developer mode); add the address with OAuth, then approve.
• Fixed-key appsCursor, Claude Code on another computer, and others: the user runs FS remote add-client --name "<app>" in their own terminal and keeps the key in an environment variable. You must not see the key.
• GrokIn Grok, add a custom connector (a remote MCP server) with the address, then approve on the FlowState page.
• Cut an app offFS remote clients, then FS remote revoke --client <id>.

Help

hello@flowstatemcp.com. Human guide: https://flowstatemcp.com/setup