OpenAI agents on real phones.
Attach the mobilerun MCP server to an agent built with the OpenAI Agents SDK, in Python or TypeScript. It gets 33 tools to run tasks on real Android and iOS phones.
via MCPNo extra package: the SDK's MCPServerStreamableHttp connects to the hosted server directly.
Before you start
- A mobilerun API key from cloud.mobilerun.ai. It starts with
dr_sk_. - Python 3.10 or newer, or Node.js for the TypeScript SDK.
- An OpenAI API key for the model that drives your agent.
- A phone in your mobilerun account to run tasks on. Connecting and listing tools works without one.
Install and set your keys
pip install openai-agents export MOBILERUN_CLOUD_API_KEY=dr_sk_YOUR_API_KEY export OPENAI_API_KEY=YOUR_OPENAI_API_KEY
Connect and build the agent
MCPServerStreamableHttp connects with your key as a Bearer token. The agent lists and calls the tools on its own.
import asyncio
import os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp
API_KEY = os.environ["MOBILERUN_CLOUD_API_KEY"]
async def main():
async with MCPServerStreamableHttp(
name="mobilerun",
params={
"url": "https://api.mobilerun.ai/v1/mcp",
"headers": {"Authorization": f"Bearer {API_KEY}"},
"timeout": 30,
},
cache_tools_list=True,
) as mobilerun:
tools = await mobilerun.list_tools()
print(f"{len(tools)} tools:", ", ".join(t.name for t in tools))
agent = Agent(
name="Phone operator",
instructions="Run tasks on real phones with the mobilerun tools.",
mcp_servers=[mobilerun],
)
# Uses your OPENAI_API_KEY and the SDK's default model.
question = "List my mobilerun devices and say which are ready."
result = await Runner.run(agent, question)
print(result.final_output)
asyncio.run(main()) Run python agent.py. Runner.run uses the SDK's default model; pass model= to the Agent to pick another.
Give it only the tools it needs
Some tools change a phone: reset it, remove apps, or start tasks that use credits. For a first agent, pass a short list: tasks, screenshots and device lookups. Add a tool_filter, then use async with mobilerun: as in step 2.
from agents.mcp import MCPServerStreamableHttp, create_static_tool_filter
mobilerun = MCPServerStreamableHttp(
name="mobilerun",
params={
"url": "https://api.mobilerun.ai/v1/mcp",
"headers": {"Authorization": f"Bearer {API_KEY}"},
"timeout": 30,
},
tool_filter=create_static_tool_filter(
allowed_tool_names=[
"list_devices", "get_device", "get_device_screenshot", "run_task",
"get_task", "list_tasks", "stop_task", "get_task_media",
]
),
) Or use TypeScript
The TypeScript SDK has the same class. The headers go in requestInit.
npm install @openai/agents zod
import { Agent, MCPServerStreamableHttp, run } from "@openai/agents";
const mobilerun = new MCPServerStreamableHttp({
name: "mobilerun",
url: "https://api.mobilerun.ai/v1/mcp",
requestInit: {
headers: { Authorization: `Bearer ${process.env.MOBILERUN_CLOUD_API_KEY}` },
},
});
await mobilerun.connect();
try {
const tools = await mobilerun.listTools();
console.log(`${tools.length} tools:`, tools.map((t) => t.name).join(", "));
const agent = new Agent({
name: "Phone operator",
instructions: "Run tasks on real phones with the mobilerun tools.",
mcpServers: [mobilerun],
});
// Uses your OPENAI_API_KEY and the SDK's default model.
const question = "List my mobilerun devices and say which are ready.";
const result = await run(agent, question);
console.log(result.finalOutput);
} finally {
await mobilerun.close();
} Tested 25 Sep 2026 against the live server with Python 3.12 and openai-agents 0.22.3, and with @openai/agents 0.18.0 on Node.js 20: connected, listed 33 tools, built the agent.
What your agent can do.
33 tools on the hosted server. Your model decides which tool to call. Tasks it starts run on mobilerun's own mobile agent and use credits and device minutes from your plan.
Run agent tasks
Start a task in plain language on a phone, follow its status and steps, send it a message while it runs, or stop it. mobilerun's mobile agent does the tapping and typing.
- run_task
- get_task
- list_tasks
- send_task_message
- stop_task
- get_task_media
See and drive the screen
Take a screenshot, read the on-screen UI as structured text, and tap, swipe or type yourself when you want exact control.
- get_device_screenshot
- get_device_ui_state
- device_action
Manage phones
List your phones, wait until one is ready, reboot or reset it, set its language, timezone and location, and apply saved profiles.
- list_devices
- get_device
- manage_device
- configure_device
- profiles
Apps and files
Install, start, stop and remove apps, upload your own APKs, and move files on and off the phone.
- list_apps_on_device
- manage_device_apps
- apps
- manage_device_files
Logins
Keep app logins in the credentials vault and let tasks use them. Stored values are never sent back to the agent.
- list_credentials
- list_credential_packages
- manage_credentials
Network and eSIM
Route a phone through mobilerun Connect residential IPs or your own SOCKS5 or WireGuard proxy, and manage eSIM profiles.
- connect
- proxies
- manage_esim
Workflows and webhooks
Turn a task into a workflow with a schedule or event trigger, send results to your own webhook endpoints, and look up timezones and app events.
- create_flow
- create_trigger
- create_action
- manage_flow
- list_workflow_resources
- get_workflow_resource
- workflow_events
- webhooks
- platform_catalog
Same server as the MCP setup for Claude Code, Cursor and VS Code.
Good to know.
Which transport does the server use?+
https://api.mobilerun.ai/v1/mcp. The server is stateless and answers POST requests only, so a client set to SSE gets a 405. Choose streamable HTTP in your client.Where does the API key go?+
Authorization: Bearer dr_sk_... header. Read it from an environment variable on your server, and keep it out of code you commit or ship to a browser.What does it cost?+
Can I sign in with OAuth instead of a key?+
Get a key.
Give it a phone.
Create an API key, paste it into the snippet above, and run your first task on a real phone.