FAQ
Everything you need to know about how the CodeDroid MCP connects, runs long tasks and keeps you in control. If you’re just getting started, head to the overview or the example prompts first.
Be mindful of prompt injection: text on the screen, such as an email or web page, can try to trick your agent. Review what it does in apps where a mistake would cost you.
Connection and setup
What is the CodeDroid MCP?
A local MCP server that connects your coding agent to CodeDroid on your Android phone. Your agent reads the screen, taps, types, swipes, opens apps and takes screenshots in your real apps.
Which devices does it work on?
Devices running Android 11 or later that can run the CodeDroid app. It doesn’t work on iPhones.
Do my phone and computer need to be on the same network?
No. They connect through the CodeDroid server, so each one only needs internet access.
Do I need a USB cable or adb?
Not to use it. The phone tools and install_apk all work over CodeDroid’s connection. A cable and adb make setup fastest, and the adb tool, used for logs, rotation and instrumentation tests, needs them or wireless debugging.
What does installing a build need?
The first time, turn on Allow from this source for CodeDroid under Install unknown apps. The phone opens that page when it’s needed. After that, install_apk takes one .apk, not an App Bundle or split APKs, and the phone has to be unlocked. See installing builds.
Which clients does it work with?
setup finds Claude Code, Codex, Gemini CLI, Cursor, VS Code, Claude Desktop and Windsurf. Antigravity CLI and Zed are set up by hand, and any other MCP client can use the server configuration.
Can I use more than one install method?
Use one per client. A second one registers the tools twice.
Long tasks
Can my agent finish a long task across apps?
Yes. It uses the phone step by step and reads the result of every action, or hands a whole goal to CodeDroid’s agent with run_task and follows it with get_task. See the example prompts.
When should my agent use run_task?
For work in other apps around the app you’re testing, such as setting up data. Your agent should use the app under test itself, so it sees each screen. A task needs CodeDroid signed in and runs on your CodeDroid account. While it runs, the tools that act on the screen answer busy.
Can I use my phone while my agent works?
It’s best not to. Your agent uses the same screen you do, so your taps and app switches can interrupt it. Each phone handles one screen action at a time.
Does the phone need to stay unlocked?
Yes. A locked phone answers locked, and your agent asks you to unlock it.
What if the connection drops during a task?
The phone reconnects after a restart or network change. An interrupted call isn’t replayed, because the action may already have happened, so your agent reads the screen before trying again. install_apk resumes where it stopped.
Can it use several phones?
Yes. Pair each one, and your agent chooses with the device argument. Each phone has its own connection and queue, so calls to different phones run side by side. See several phones.
Does it work with games, web views and apps that block screenshots?
Usually. CodeDroid reads the screen through Android’s accessibility service. When the element list can’t show something, such as a game or a web view with no labels, your agent takes a screenshot and taps by coordinates. An app that blocks screenshots returns a black image, so your agent relies on the element list there.
Can it test my app offline?
No. Your agent reaches the phone over the internet, so it can’t run a test while the phone is offline.
Safety and privacy
Does CodeDroid sell my data?
No. CodeDroid does not sell your data, including your conversations and screen contents.
Is it safe to let my agent use my phone?
Your agent makes real taps and keystrokes, and there is no undo. CodeDroid’s MCP instructions tell it to ask you before sending, buying, posting or deleting anything, and to treat what’s on the screen as data, not instructions. Review what it does in apps where a mistake would cost you.
How do I stop it or remove access?
While a computer acts on the phone, CodeDroid shows its name and a Stop button. Stop disconnects it and blocks it for one minute. In Settings → Computers, Remove revokes a computer’s access, and Allow computers to connect turns access on or off.
What data leaves my computer?
Tool calls are relayed through the CodeDroid server over TLS: screen contents, screenshots, text you ask it to type, clipboard reads and writes, and task progress. Pairing sends the one time code, your computer’s name and its OS. Your agent’s AI provider also receives whatever the agent reads, under that client’s terms. The plugin collects no analytics.
What stays on my computer?
Pairing credentials, the daemon token and logs stay in ~/.codedroid. The local server listens on 127.0.0.1 only and requires a token that only your user account can read.
What can the adb tool do?
It runs adb commands on your computer, so it’s marked destructive and clients that honor that ask before running it. Some commands are refused, and file transfers stay in your project and temp directories. Turn it off with --no-adb or CODEDROID_MCP_ADB=0. See adb setup.
Troubleshooting
My agent can’t reach my phone.
Run npx -y @codedroid/mcp status, or ask your agent to call codedroid_status. Both say what to fix. Usually it’s one of these: open CodeDroid, check its internet connection and sign in, and turn on Allow computers to connect. See troubleshooting.
Setup is waiting for sign-in.
On your phone, tap send in CodeDroid, then sign in with Google.
The phone blocked installing over USB.
Turn on Install via USB in Developer options, then run setup again.
Several devices are on adb.
Set CODEDROID_SERIAL to the phone’s serial from adb devices, for example CODEDROID_SERIAL=<serial> npx -y @codedroid/mcp setup.
Setup says “This CodeDroid can’t pair over USB”.
Update CodeDroid on your phone, then run setup again. Or pair by hand in Settings → Computers → Pair a computer.
I removed this computer on my phone.
Plug the phone in and run npx -y @codedroid/mcp setup again. It pairs the computer again.
adb isn’t installed.
Install Android platform tools, then run setup again. Or pair by hand in Settings → Computers → Pair a computer.
I denied the connection, or stopped it by accident.
Wait one minute, run npx -y @codedroid/mcp connect, then tap Allow on your phone.
CodeDroid’s accessibility service turned off.
Force stopping com.codedroid.agent or running instrumentation against it turns the service off. Turn it back on in Android’s Accessibility settings. Clearing the app’s data also signs it out. UiAutomator tests and uiautomator dump only suspend the service while they run.