Agent-driven setup

This page is written for an AI agent. A user has said something like "set up webmcp.fast for my filesystem server". Here is exactly how to proceed.

When to use webmcp.fast

Use it when the user wants a cloud agent (Claude, ChatGPT, Grok, or any remote-MCP client) to use an MCP server that runs on their own machine, and they do not want to open a port, run a tunnel or host the server somewhere. Do not use it to host a server in the cloud, to aggregate several servers behind one URL, or to reach a machine the user does not control.

If you have a shell on the user's machine

Install the daemon. curl -fsSL https://webmcp.fast/install.sh | sh (coming with the first public release). Coming with the first public release: the install script is not published yet. macOS (Apple silicon and Intel) comes first, brew install webmcp later. Until then the daemon is built from source. The daemon is open source.
Run webmcp up. It generates a device key on the machine and prints one link, https://webmcp.fast/activate?code=XXXX-XXXX. Show that link to the human and wait; webmcp up returns when they have approved. It also offers any MCP servers it finds in existing Claude, Cursor and Codex configs.
The human opens the link in their own browser. They sign in with the 6-digit code emailed to them (this creates the account if they have none), pick a handle, and approve the device. The code is never given to the agent: do not ask for it, and do not offer to type it.
Attach the server. webmcp attach <alias> -- <command> [args...] for a stdio server, or webmcp attach <alias> --http <local url> for one already listening on localhost. The alias is 1 to 32 characters of a-z, 0-9 and -.
Keep it online. webmcp service install registers a launchd service so the daemon starts at login and reconnects by itself.
Hand over the connector URL. Print https://<handle>.webmcp.fast/<device>/<server>/mcp with the real handle, device and alias. The human pastes it into Claude, ChatGPT or Grok as a custom connector, signs in, and clicks Allow.

Useful checks: webmcp status shows the pairing and the attached servers, and webmcp service status shows whether the background service is running.

The two human acts

Two steps are deliberately left to the human, and no agent can do them:

Proving they own the email address. The 6-digit code goes to their inbox and is typed into their own browser. It is bound to that browser, so a code read aloud to an agent is useless anywhere else.
Approving each cloud agent. Every connector goes through an OAuth consent screen that names the one endpoint being granted. The human clicks Allow, once per agent per server.

Tell the user up front that these two moments are coming, so that the email and the consent screen are expected.

If you are a cloud agent with no shell

Connect to the management MCP server at https://webmcp.fast/mcp (Streamable HTTP). Its card is at https://webmcp.fast/.well-known/mcp/server-card.json.

check_handle (anonymous): Check whether a handle (the <handle> in https://<handle>.webmcp.fast) is valid and still available to claim.
start_setup (anonymous): Begin setting up webmcp.fast for a user from an agent that has no shell. Returns the exact commands the user runs on their machine and what to expect at each step. The user still signs in and approves the device in their own browser.
setup_status (anonymous): Report how far a setup started with start_setup has got: waiting for the human to approve, device paired, server attached, device online.
list_devices (OAuth scope manage): List the signed-in user's handles, their devices, whether each device is online, and the MCP servers each one offers.
connect_url (OAuth scope manage): Return the connector URL, https://<handle>.webmcp.fast/<device>/<server>/mcp, for one server on one of the signed-in user's devices, with the steps to add it to Claude, ChatGPT or Grok.

Call check_handle if the user has a handle in mind, then start_setup. It returns the one command for the user to run in a terminal on their machine. From there the flow is the same: they open the link, sign in, approve. Poll setup_status to follow along, then give them the connector URL to add to your own harness.

Seeing the user's devices without a sign-in window

list_devices and connect_url need scope manage. If your harness can open a browser for the user, OAuth does that. If it cannot, register yourself: POST https://webmcp.fast/agent/identity with {"type": "anonymous"}, then POST https://webmcp.fast/agent/identity/claim with your claim_token and the user's email. Give the user the link and the 6-digit code it returns; they sign in and type your code into the page (never ask them for the code webmcp.fast emails them). Poll the token endpoint until they approve, and the access token you get works on list_devices and connect_url for that account, read-only. It can never reach one of their MCP servers. The full recipe, with every error, is auth.md.

Free tier

Setup is self-serve and free: 1 handle, 1 device, 1 server, 1 connector, no credit card. If the user already uses their one server slot, webmcp attach reports that the new server is held back. Say so rather than retrying. A paid tier is not yet available.

Rules for agents

Never ask the user for the emailed code, a connector token or a session cookie.
Never claim the setup is complete before webmcp up has returned and the server shows as ready.
Attach only the server the user asked for. Each attached server is reachable by whichever agent the user approves for it.
Print the final connector URL exactly. Do not invent a handle or device name.

Machine-readable versions

llms.txt, agent instructions, SKILL.md, OpenAPI, auth.md.