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. npm i -g @proticom/webmcp, or skip the install and run npx @proticom/webmcp up in the next step. npm works on macOS, Linux and Windows and needs no compiler: the package carries prebuilt binaries. On Linux the GitHub release tarballs also work: curl -fsSL https://github.com/proticom/webmcp/releases/latest/download/install.sh | sh. The macOS tarballs are unsigned, so use npm on a Mac. 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, Codex and VS Code 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 keeps the daemon running in the background: a launchd agent on macOS, a systemd user unit on Linux (run loginctl enable-linger $USER so it survives logout). Windows has no service; run webmcp connect under your own supervisor there.
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, not whether the device is connected. webmcp servers lists the servers in the local config, not whether they are ready. 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 whether a handle has been claimed, which is the first sign that a setup started with start_setup is under way. Whether a device is paired or online, and which servers it offers, is private: use list_devices with scope manage.
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. setup_status only says whether the handle has been claimed. To see the device and its servers come online, use list_devices, which needs scope manage (below). 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. webmcp attach does not check the plan limit. If the user already uses their one server slot, the dashboard shows the new server as waiting and webmcp connect logs server_limit. 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 dashboard or list_devices shows the server as ready. webmcp servers only lists the local config.
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.