Skip to main content
PhoneUse speaks MCP over two transports. Both publish the same tool surface, so the config block is the only thing that differs.
  • HTTP talks to a control plane over the network, at POST /mcp. Your cloud phones are at https://mcp.phoneuse.com/mcp.
  • stdio is for a client that can only spawn a process. The PhoneUse CLI gives it your cloud phones by relaying to the hosted endpoint.
Pick HTTP unless your client can only spawn processes. See Transports for the behavioural differences that follow from this choice. There is no separate MCP package to install. The stdio option below runs the PhoneUse CLI, @phoneuse/cli, with npx.

Your cloud phones over HTTP

The hosted control plane lives at https://mcp.phoneuse.com/mcp. Sign up at console.phoneuse.com/sign-up and mint a key yourself at console.phoneuse.com/keys. See Getting a key.
Most clients cannot expand an environment variable inside a config file, so paste the key value itself. With Claude Code, one command does it:
The endpoint’s protected resource metadata names the configured Clerk issuer as its authorization server. That server offers no dynamic client registration, so a client that tries to register itself and open a browser sign in has nothing to register with, and a browser flow from a generic MCP client has not been verified end to end. Use an API key. See Authentication. Keep the client entry named phoneuse. This site’s docs MCP server is a different server with a different name, and you want to be able to tell them apart in a client list. See For agents.

Your cloud phones over stdio

For a client that can only spawn a process (Claude Desktop, Cursor and others), run the PhoneUse CLI as a stdio server. It relays to https://mcp.phoneuse.com/mcp, so your client sees the same cloud phones and the same tools as over HTTP. First sign in once on that machine, which stores a key for the CLI:
Then give your client this block:
The relay uses the key in PHONEUSE_API_KEY if it is set, and otherwise the key phoneuse login stored. With neither, it stops and tells you to sign in. See CLI installation.

HTTP against a local control plane

Start the control plane first. It listens on loopback and reads its device rows from the PHONEBASE_DEVICE_ROWS environment variable, a JSON array of rows.
Then give your client the endpoint:
PHONEBASE_DEV_TOKEN is the local development credential. Set it, and the endpoint requires that exact value as a bearer token. Leave it unset, and the endpoint accepts unauthenticated requests, which is safe only because local mode refuses to bind anywhere but loopback.
Local mode grants every scope. It is a single operator on a single machine, not a permission model. Do not expose that port.

Checking the connection

The MCP Inspector talks to the endpoint without a client in the way:
Call list_devices first. It needs no lease, so it answers immediately, and what it returns tells you whether the control plane can see your hardware. If the tool list looks shorter than you expect, that is authentication rather than a fault: a tool your credential is not scoped for is never registered, so it does not appear at all.

Two things clients get wrong

Host and origin are checked. The HTTP transport refuses requests carrying a browser Origin header, and accepts only the host it was configured for. Without those checks any web page could rebind its own hostname to loopback and drive your device. A client that sets a browser style origin will be refused. GET and DELETE on /mcp return 405. The endpoint is stateless: there is no stream to resume and no session to tear down. Post your requests.