Give your agent a real phone.

01 / OVERVIEW

How Thumb works

Each Thumb account gets a real Android phone of its own. Your agent reaches it through one URL, https://api.thumb.run/mcp, with an API key. The same 13 tools work from any MCP client, and the REST API exposes them as plain HTTP for your own code.

1. Your agentClaude Code, Cursor, an SDK or your code
2. api.thumb.runChecks your key and passes each call to your phone, in order
3. Your phoneA physical Android phone, dedicated to you

• Look, then act. Your agent takes a screenshot, decides where to tap, and acts. Coordinates are pixels in the latest screenshot, so what the model sees is what it touches.
• One finger. Calls to a phone run one at a time, in the order they arrive, so parallel tool calls from your client never collide on the screen.
• Nothing but the tools. Your agent gets the 13 tools and nothing else. Thumb opens no way into your phone from the internet and gives no one shell or file access to it over the internet.
• You can step in. Pause your agent from the dashboard to sign in, pass a 2FA check or solve a CAPTCHA yourself, then hand control back.

Private beta. Access is by invitation and things will change. The changelog lists what changed and when. Questions or ideas: hello@thumb.run.

02 / QUICKSTART

Quickstart

1. Sign in

   Go to thumb.run/signin and enter your email. We send a sign-in link that works once, for 15 minutes. There is no password.

2. Get approved

   During the private beta every account is reviewed by a person. We email you when you're in. If you haven't told us what you want your agent to do, the dashboard asks.

3. Get a phone

   In the dashboard, choose Get a phone. We prepare one for you and email you when it's ready.

4. Create an API key

   Under API keys, create a key and copy it. Keys start with thumb_sk_. You see a key once; Thumb only keeps a hash of it.

5. Connect your agent and say hello

   Add Thumb to your agent. For Claude Code:

   claude mcp add --transport http --scope user thumb https://api.thumb.run/mcp --header "Authorization: Bearer YOUR_API_KEY"

   Then ask: “Take a screenshot of my phone and tell me what you see.” The dashboard's Recent activity shows Your agent is connected ✓ after the first call. Other clients are in Connect your agent.

Tip. Pass screenshot: true to any action (tap, swipe, type…) and the result includes the screen about 0.4 seconds later, so your agent sees what happened without a second call.

03 / CONNECT YOUR AGENT

Connect your agent

Thumb is a remote MCP server. Every client needs two things: the URL https://api.thumb.run/mcp and the header Authorization: Bearer <your key>.

Tested

We've connected it to a real phone through api.thumb.run ourselves: it lists all 13 tools and shows screenshots as images. We add this badge one client at a time, as each one passes.

Config checked against the vendor's docs

The snippet matches the client's current documentation (checked 2026-09-25), but we haven't run it end to end yet. Tell us how it goes at hello@thumb.run.

Keep keys out of your repo. Where a client can read environment variables or prompt for secrets, these snippets do that, so project files stay safe to commit. Set the variable once in your shell profile: export THUMB_API_KEY=thumb_sk_…. Snippets that contain a literal key belong in files in your home directory only.

claude mcp add --transport http --scope user thumb https://api.thumb.run/mcp --header "Authorization: Bearer YOUR_API_KEY"

{
  "mcpServers": {
    "thumb": {
      "type": "http",
      "url": "https://api.thumb.run/mcp",
      "headers": { "Authorization": "Bearer ${THUMB_API_KEY}" }
    }
  }
}

{
  "mcpServers": {
    "thumb": {
      "url": "https://api.thumb.run/mcp",
      "headers": { "Authorization": "Bearer ${env:THUMB_API_KEY}" }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "thumb-key",
      "description": "Thumb API key",
      "password": true
    }
  ],
  "servers": {
    "thumb": {
      "type": "http",
      "url": "https://api.thumb.run/mcp",
      "headers": { "Authorization": "Bearer ${input:thumb-key}" }
    }
  }
}

{
  "mcpServers": {
    "thumb": {
      "serverUrl": "https://api.thumb.run/mcp",
      "headers": { "Authorization": "Bearer ${env:THUMB_API_KEY}" }
    }
  }
}

gemini mcp add --scope user --transport http --header "Authorization: Bearer YOUR_API_KEY" thumb https://api.thumb.run/mcp

{
  "mcpServers": {
    "thumb": {
      "httpUrl": "https://api.thumb.run/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

codex mcp add thumb --url https://api.thumb.run/mcp --bearer-token-env-var THUMB_API_KEY

[mcp_servers.thumb]
url = "https://api.thumb.run/mcp"
bearer_token_env_var = "THUMB_API_KEY"
tool_timeout_sec = 70

{
  "mcpServers": {
    "thumb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.thumb.run/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}

import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp


async def main():
    async with MCPServerStreamableHttp(
        name="thumb",
        params={
            "url": "https://api.thumb.run/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['THUMB_API_KEY']}"},
        },
        client_session_timeout_seconds=70,
        cache_tools_list=True,
    ) as thumb:
        agent = Agent(
            name="Phone agent",
            instructions="You control a real Android phone. Look before you act.",
            mcp_servers=[thumb],
        )
        result = await Runner.run(
            agent, "Open Settings and tell me the Android version.", max_turns=50
        )
        print(result.final_output)


asyncio.run(main())

import os

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-6-astra",
    tools=[
        {
            "type": "mcp",
            "server_label": "thumb",
            "server_url": "https://api.thumb.run/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['THUMB_API_KEY']}"},
            "require_approval": "never",
        }
    ],
    input="Use the phone to find out its Android version.",
)
print(response.output_text)

{ "never": { "tool_names": ["screenshot", "list_elements", "list_apps", "device_info"] } }

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 4096,
    "messages": [{"role": "user", "content": "Take a screenshot of the phone and describe it."}],
    "mcp_servers": [{
      "type": "url",
      "url": "https://api.thumb.run/mcp",
      "name": "thumb",
      "authorization_token": "'"$THUMB_API_KEY"'"
    }],
    "tools": [{"type": "mcp_toolset", "mcp_server_name": "thumb"}]
  }'

curl https://api.thumb.run/mcp \
  -H "Authorization: Bearer $THUMB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"device_info","arguments":{}}}'

04 / TOOLS

Tools reference

Thirteen tools, the same over MCP and REST. Four only look (clients can run them without asking); the others act on the phone.

• Coordinates are pixels in the latest screenshot, counted from the top-left corner.
• screenshot: true on any action returns the screen about 0.4 seconds after acting, in the same result, followed by Screen is WxH pixels. Screens that take longer to load need another look.
• Actions are not idempotent. Tapping Send twice sends twice. See Errors for how to tell whether an action happened.

05 / SCREENSHOTS & COORDINATES

Screenshots & coordinates

Screenshots are PNG, scaled so the longest edge is 1280 pixels by default. On a Galaxy A54 that's 591×1280. Every tool that takes coordinates reads them in the same pixels, so your agent taps exactly what it saw. Capture takes about half a second at any size; size changes how much context and money each look costs, not speed.

Choose another size with max_edge (480–1568): on MCP as part of the URL, https://api.thumb.run/mcp?max_edge=1024, and on REST as GET /v1/phones/{id}/screenshot?max_edge=1024. Coordinates follow the size of the connection they were sent on.

Claude counts an image as ⌈width ÷ 28⌉ × ⌈height ÷ 28⌉ visual tokens (Claude vision docs). Its standard-tier models shrink images whose long edge is over 1568 pixels, which would move every tap, so Thumb stops there. Other models count differently. A 1280 screenshot of a home screen is about 120 KB.

Reading small text? list_elements returns on-screen text with tap coordinates. It takes about 3 seconds, and costs no image tokens.

06 / REST API

REST API

The same tools over plain HTTP, for your own code. Base URL https://api.thumb.run. Send your key as Authorization: Bearer thumb_sk_…; errors come back as JSON { "error": "…" }. CORS is off, so call the API from a server or script, never from a web page.

export THUMB_API_KEY=thumb_sk_...   # from the dashboard
export PHONE_ID=ph_...              # from GET /v1/phones or the dashboard

curl https://api.thumb.run/v1/tools

curl https://api.thumb.run/v1/phones -H "Authorization: Bearer $THUMB_API_KEY"

{
  "phones": [
    {
      "id": "ph_4k2m9x7q1z",
      "label": "Galaxy A54",
      "model": "SM-A546E",
      "android": "16",
      "status": "assigned",
      "online": true,
      "agentPaused": false,
      "frozen": false,
      "lastSeenAt": "2026-09-25T14:02:11.000Z"
    }
  ]
}

curl --fail-with-body -o screen.png --dump-header - https://api.thumb.run/v1/phones/$PHONE_ID/screenshot -H "Authorization: Bearer $THUMB_API_KEY"

curl https://api.thumb.run/v1/phones/$PHONE_ID/tap \
  -H "Authorization: Bearer $THUMB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x": 295, "y": 1100}'

{ "content": [{ "type": "text", "text": "Tapped (295, 1100)." }], "isError": false }

curl https://api.thumb.run/v1/phones/$PHONE_ID/type_text \
  -H "Authorization: Bearer $THUMB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "hello from my agent", "screenshot": true}'

Status codes

Over MCP the same conditions arrive as tool results your agent can read (the rate limit says how long to wait), and only a bad key (401) or a foreign browser Origin (403) is an HTTP error.

07 / HUMAN TAKEOVER

Human takeover

Some moments need a person: signing in, a 2FA code, a CAPTCHA, a payment confirmation. The phone card in the dashboard has a live view you can drive yourself.

1. Pause the agent

   Choose Pause agent. From that moment agent calls are refused, including any already waiting in line, and your agent reads:

   The phone's owner has taken control (for example to sign in). Wait a moment and try again, or ask the user to hand control back at https://thumb.run/app. Nothing was done on the phone.

2. Use the phone

   Click the live view to tap, drag to swipe, type into the text box, and use Back, Home, Recent apps, Backspace and Enter. What you type goes to the phone and is never stored or logged; live-view frames aren't recorded. The view pauses when you switch tabs or stop interacting for a while; choose Resume to continue.

3. Hand back

   Choose Hand back to agent. Your agent's next call goes through.

Recent activity on the same card lists the last 50 calls on your phone (tool, outcome, agent or you, time, and for launch_app and open_url the app's package name or the link's domain name), so you can see what your agent did. It never shows typed text, full links or images.

Tell your agent to ask. Thumb's built-in instructions already tell agents to ask before sending messages, paying, installing apps or changing account and security settings. Add “when you reach a sign-in or a CAPTCHA, ask me to take over” to your prompt.

Returning a phone. Return this phone in the dashboard (or deleting your account) gives the phone back. It is factory reset before anyone else uses it, which erases the apps, accounts and data on it, including your app sign-ins.

08 / SECURITY & PRIVACY

Security & privacy

A phone signed in to your apps is sensitive, so here, in short, is what Thumb keeps, what only passes through, and who can reach what. The Privacy Policy, the Terms of Service and the Acceptable Use Policy have the full version.

Your API keys

• A key (thumb_sk_ plus 32 random characters) is shown once. Thumb stores only its SHA-256 hash and the first few characters, so you can tell keys apart.
• Keys work only in the Authorization header, never in a URL.
• Never commit a key. Use the environment-variable and prompt snippets in Connect your agent.
• If a key leaks, revoke it in the dashboard. It stops working on the next call, and calls with it that are still waiting are cancelled. Use one key per agent, so revoking one doesn't stop the others.
• One key per agent also keeps cancellations apart. Thumb keeps no sessions, so when a client cancels a call (Esc, or its own timeout) the call is found by its key, the phone in the URL and its request number, and only if exactly one call matches. Two agent windows sharing a key and a URL can't cancel each other's calls; they may just not be able to cancel their own.

Who can reach what

• The phone is dedicated to you. Every call is checked against your account right before it reaches the phone, and nobody else's agent can use it.
• GETRYK, which operates Thumb. Your phone is a physical device in our custody. We don't watch your screen. We access a phone, and may see what's on it, only for maintenance and repair, to investigate a security incident or suspected abuse, to comply with the law, or to help you when you ask, and we keep a record of when and why.
• Service providers. OVH hosts Thumb's server; Resend sends Thumb's emails; Google and Namecheap handle our inbox and email forwarding. Your agent's model provider sees whatever your agent reads from the phone, under your agreement with them.
• A narrow path to the phone. Thumb runs only the 13 tools for your agent, plus its own checks of which phone it is connected to and which apps are installed, and turning off the network of a phone that is temporarily unavailable. Thumb opens no way into your phone from the internet and gives no one shell or file access to it over the internet.
• Wiped between customers. A returned phone is factory reset before anyone else gets it.

Keeping phones safe

• Metadata, not content. To prevent abuse we watch activity metadata: tool calls, the apps launched and installed, the domains opened and how many actions an account makes. Unusual activity alerts us, and a person reviews it. We don't watch your screen to do this.
• Blocked links. open_url refuses domains on Thumb's blocklist, and their subdomains, before anything happens on the phone. It's a basic safeguard, not a complete filter.
• Temporarily unavailable. To stop abuse, or while we look into a report, we can make a phone temporarily unavailable: every call to it, from your agent or from the dashboard, is refused, and we put it in airplane mode with Wi-Fi off until we lift it.
• Rules. The Acceptable Use Policy says what's not allowed. To report abuse of a Thumb phone, email abuse@thumb.run.

Screen content is untrusted

Anything on the screen, whether a web page, a message, a notification or an email, can contain text written to steer your agent (prompt injection). Thumb's tool descriptions and instructions tell agents to treat it as data, never instructions. You can add to that:

• Keep approval on for actions where your client supports it; the four read-only tools are marked so clients can let them run freely.
• Sign the phone in only to the accounts your agent needs, and prefer separate accounts for agent work.
• Ask your agent to confirm with you before sending, paying, installing or changing settings.

Found a security problem? Email hello@thumb.run; please don't include your API key. To report abuse of a Thumb phone, email abuse@thumb.run.

09 / LIMITS

Limits

10 / ERRORS & TROUBLESHOOTING

Errors & troubleshooting

Thumb's errors are written for your agent to read. Two phrases tell it what happened:

Why it matters: phone actions are not idempotent. Tap Send twice and the message goes twice. So Thumb never retries an action for you, never delivers a call twice, and cancels calls that waited too long instead of running them late. When unsure, your agent should look, not repeat.

Messages

<tool>, <id> and <n> are filled in. The phone itself can also refuse an action before doing it, for example a tap outside the screen (x must be 0-590 and y 0-1279: pixels in the latest screenshot (591x1280). If the screen rotated, take a new screenshot. Nothing was done on the phone.) or text that isn't ASCII. Raw system errors never reach your agent; it always gets one of the messages above.

Troubleshooting

11 / CHANGELOG

Changelog

1. 2026-09-25

   Private beta

   • Remote MCP at https://api.thumb.run/mcp, protocol revisions 2025-03-26 to 2026-07-28.
   • REST API v1: phones, screenshots and every tool.
   • 13 phone tools with titles and read-only hints; screenshot: true on every action.
   • max_edge to choose screenshot size.
   • Human takeover with a live view, and recent activity in the dashboard.