androiduse-mcp-secret

name	AndroidUse MCP Secret
description	This skill should be used when the user asks to connect Codex to the AndroidUse Android MCP server, retrieve the AndroidUse MCP secret from an adb-connected device, refresh the secret with action.sh, configure ANDROIDUSE_MCP_SECRET, or set up adb forward for the androiduse MCP server.
version	0.1.0

AndroidUse MCP Secret

Use this skill to connect Codex to the AndroidUse module MCP server running on a rooted Android device.

The AndroidUse MCP server is a streamable HTTP server exposed at:

http://127.0.0.1:8765/mcp

The server requires bearer-token authentication. Codex is configured with the MCP server name androiduse and reads the bearer token from:

ANDROIDUSE_MCP_SECRET

Never write the secret into Codex config, repo files, logs, commits, issue text, or final answers unless the user explicitly asks to display it.

Standard Workflow

1. Confirm an adb device is connected:

adb devices
adb shell 'su -c "id"'

Accept root only when the output shows uid=0(root).

2. Locate the active module directory.

Before reboot after install, KernelSU usually keeps the updated module at:

/data/adb/modules_update/AndroidUse

After reboot, the normal runtime path is:

/data/adb/modules/AndroidUse

Prefer modules_update when it exists and contains cli; otherwise use modules.

3. Refresh the secret when the user asks for a new credential:

adb shell 'su -c "/data/adb/modules_update/AndroidUse/action.sh"'

or after reboot:

adb shell 'su -c "/data/adb/modules/AndroidUse/action.sh"'

action.sh creates or replaces:

.secret/mcp_secret

The directory and file must both be mode 700.

4. Read the secret into the local shell environment:

export ANDROIDUSE_MCP_SECRET="$(adb shell 'su -c "cat /data/adb/modules_update/AndroidUse/.secret/mcp_secret"' | tr -d '\r')"

Use the rebooted path when appropriate:

export ANDROIDUSE_MCP_SECRET="$(adb shell 'su -c "cat /data/adb/modules/AndroidUse/.secret/mcp_secret"' | tr -d '\r')"

5. Start the AndroidUse MCP server on the device if it is not already running:

adb shell 'su -c "/data/adb/modules_update/AndroidUse/cli mcp serve"'

The default listener is 127.0.0.1:8765. For normal development, keep this loopback-only and access it through adb forwarding.

The listener can be customized from the module env file:

/data/adb/modules_update/AndroidUse/.config/androiduse/mcp.env

or after reboot:

/data/adb/modules/AndroidUse/.config/androiduse/mcp.env

Supported keys:

ANDROIDUSE_MCP_HOST=127.0.0.1
ANDROIDUSE_MCP_PORT=8765

Use 0.0.0.0 or a LAN address only on trusted networks. Restart the MCP process after changing this file.

6. Forward the device port to the workstation:

adb forward tcp:8765 tcp:8765

7. Verify the endpoint:

curl -sS -i -H "Authorization: Bearer $ANDROIDUSE_MCP_SECRET" http://127.0.0.1:8765/mcp

Expect:

HTTP/1.1 200 OK
ok

Without the bearer token, expect 401 Unauthorized.

Codex MCP Configuration

The project uses a Codex MCP server entry named:

androiduse

Add it with the Codex CLI, not by manually editing config:

codex mcp add androiduse --url http://127.0.0.1:8765/mcp --bearer-token-env-var ANDROIDUSE_MCP_SECRET

Check it with:

codex mcp get androiduse
codex mcp list

Expected properties:

transport: streamable_http
url: http://127.0.0.1:8765/mcp
bearer_token_env_var: ANDROIDUSE_MCP_SECRET

Tool Surface

The AndroidUse MCP tool for shell execution is named:

mksh

mksh uses an automatically managed persistent PTY shell session keyed by the MCP HTTP session. Do not make the user manually provide a session id. Use reset: true when a fresh shell is needed, or stateless: true for a one-shot /system/bin/sh -c command.

Do not call the old tool name terminal_exec; it should return unknown tool.

A direct JSON-RPC smoke test:

curl -sS \
  -H "Authorization: Bearer $ANDROIDUSE_MCP_SECRET" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mksh","arguments":{"command":"id; uname -m","timeout_secs":5}}}' \
  http://127.0.0.1:8765/mcp

Expect root context and device architecture, for example uid=0(root) and aarch64.

The screenshot tool is named:

screenshot

It returns JSON text with source, mime_type, bytes, and data_base64. On modern devices /dev/graphics/fb0 may be missing, so the tool falls back to screencap -p.

Secure-window screenshots require the user to install and enable CaptureSposed separately:

https://github.com/99keshav99/CaptureSposed

Without CaptureSposed, FLAG_SECURE windows are expected to be blocked or hidden by Android's screenshot path.

For rooted-device DRM streaming app testing, liboemcrypto-disabler is an optional companion module, not a hard AndroidUse dependency:

https://github.com/Anonym0usWork1221/liboemcrypto-disabler

Cleanup

Stop a manually started test server by finding the process on the device:

adb shell 'su -c "ss -lntp 2>/dev/null | grep 8765 || true"'
adb shell 'su -c "kill <pid>"'

Remove forwarding:

adb forward --remove tcp:8765

Do not kill a service-managed process unless the user asked to stop the MCP server or the current task started it manually.