mobilerun-mcp

Public, curated MCP server for the Mobilerun platform, integrated. See ROADMAP.md for the design (architecture, current state, and what's planned next).

Layout

• packages/tools (@mobilerun/mcp-tools) — auth-agnostic tool core. No hono, no SDK dependency, only zod + MCP SDK types. Exports buildMcpServer(ctx, opts?), the Backend interface, and all 34 tools.

• packages/server (@mobilerun/mcp-server) — public composition: Bearer auth → @mobilerun/sdk client → SdkBackend → ToolCtx → buildMcpServer. Ships both an HTTP (Streamable HTTP, stateless) and a stdio transport.

Related MCP server: MCP Iconik

Setup

pnpm install
pnpm run typecheck
bun test

Runtime is Bun (bun run, bun test) — pnpm is only the installer.

Running

HTTP (Streamable HTTP, stateless)

cd packages/server
PORT=8080 bun run src/index.ts

• GET /health — liveness, not auth-gated.

• POST /mcp — MCP Streamable HTTP endpoint, stateless JSON mode only. Every request opens a fresh McpServer + transport (no session state, no key caching across requests) and builds a fresh @mobilerun/sdk client from the request's bearer key.

• GET /mcp, DELETE /mcp — 405. A fresh-server-per-request design has no session/stream state for a GET (SSE) or DELETE (session-terminate) request to act on, so both are explicit 405s rather than silently accepted.

Baseline limits (every request, before the request reaches handleMcp)

• Request body over MCP_BODY_LIMIT_BYTES (default 1 MiB) → 413.

• No response within MCP_REQUEST_TIMEOUT_MS (default 60s) → 504.

• Per-request-IP and per-API-key-hash token-bucket rate limits (MCP_RATE_LIMIT_PER_IP_PER_MIN / MCP_RATE_LIMIT_PER_KEY_PER_MIN, defaults 120/60 req/min, burst = the limit itself) → 429 + Retry-After: <seconds>. In-process only (per replica, not distributed) — see packages/server/src/rate-limit.ts's file header for why. A distributed, weighted limiter (cost per tool, concurrency, org budgets) is a deployment-layer concern this floor doesn't replace.

stdio (local use)

cd packages/server
MOBILERUN_CLOUD_API_KEY=<key> bun run src/stdio.ts

Auth

Two ways to present the API key on the HTTP transport, and they must be disjoint — presenting both is a 400, not "Authorization wins":

• Authorization: Bearer <key> (standard MCP client convention)

• x-mobilerun-cloud-api-key: <key> (matches @mobilerun/sdk's own env var name, for clients that can't set arbitrary Authorization headers)

Bearer channel separation: a dr_sk_-prefixed credential is treated as a Mobilerun API key. Any other bearer value is rejected with 400 — this server does not yet validate OAuth 2.1 bearer tokens (see ROADMAP.md for the plan).

Error taxonomy (packages/server/src/auth.ts):

This server does not yet implement full RFC 9728/OAuth 2.1 validation (.well-known/oauth-protected-resource itself isn't served yet either) — only the error shapes the spec requires, ahead of full OAuth support.

The stdio transport takes the key from MOBILERUN_CLOUD_API_KEY in the process environment (no per-call header, since stdio has no request/response HTTP envelope) — local-only fallback, not used by the HTTP transport.

Environment (packages/server)

Validated with zod + safeParse at startup (env.ts) — an invalid config fails fast (process.exit(1)) rather than serving with a bad default.

Tools (34 total)

See inline file-header comments in packages/tools/src/tools/*.ts for the per-tool design notes, and packages/server/src/sdk-backend/workflows.ts for the two open SDK-mapping gaps (list_credential_packages has no direct SDK endpoint; create_trigger's scheduleRule.jitter isn't in the public SDK's typed params). See ROADMAP.md for the consolidated list of tools that are awaiting SDK support (recordings, deeplink, browser execute-script, app permissions, eSIM APN/roaming/connectivity, kiosk, location reset, app_store, apps storage-usage, list_app_events — none of these are exposed as tools; no SDK support exists for them yet).

Policy / allowlisting (fail-closed at registration)

ToolCtx.policy is required (not optional) and has two levels, both enforced by packages/tools/src/register.ts's enforcePolicy before any tool handler ever runs:

• Tool-level — policy.toolAllowlist: ReadonlySet<string>. A tool name outside the set is never usably registered: it's absent from tools/list and a direct tools/call for it fails with the MCP SDK's own "Tool X not found" error, not a custom "denied" result — there's no handler to run. An empty toolAllowlist therefore registers nothing at all. There is no implicit "everything" default; a host that wants full access calls fullAccessPolicy() explicitly.

• Operation-level — policy.operationAllowlist?: ReadonlyMap<string, ReadonlySet<string>>, for the bundle tools (webhooks, list_workflow_resources, get_workflow_resource). An entry for a tool name restricts which operation/resource values are dispatchable; a value outside the set is rejected with a typed error result before the backend is called. The tool's description also lists the allowed subset when narrowed — the zod input schema itself intentionally stays the full enum (see the comment in tools/webhooks.ts / tools/workflows.ts): a policy-narrowed schema would make an out-of-policy value fail generic zod/MCP input validation before reaching the dispatch-time gate, which is where the actual enforcement (and its audit event) lives.

Policy profiles

The HTTP and stdio servers build their Policy via policyForProfile(env.MCP_POLICY_PROFILE) (packages/tools/src/policies.ts), one of three profiles:

Set MCP_POLICY_PROFILE=readonly|no-commerce|full to choose; both the HTTP and stdio transports read the same env var, so they stay in lockstep.

buildMcpServer's opts.wrapRegisterTool hook is the composition point for a host's own registerTool wrapper (e.g. plugging in metrics or its own tier gate) — see ROADMAP.md for the composition model.

Auth context

ToolCtx.auth: AuthContext is also required — { kind: 'api_key' | 'oauth' | 'machine', subject, ownerId?, clientId?, scopes?, tokenId?, expiresAt? }. Build it via createAuthContext(...), which enforces that ownerId is present for kind: 'oauth' | 'machine' (those credentials are always org-scoped) — optional for kind: 'api_key', where the public API enforces tenancy itself via key scoping and this resource server never learns the org. The HTTP/stdio server builds { kind: 'api_key', subject: 'api-key' }.

Typed backend ports & errors

packages/tools/src/backend/{devices,workflows,webhooks,credentials}.ts (barrel: backend/index.ts) define the Backend ports as minimal DTOs, not a mirror of @mobilerun/sdk's full response types — only the fields the tools actually surface. packages/server/src/sdk-backend/ mirrors the same per-domain split for the SdkBackend implementation over @mobilerun/sdk, wrapped in withBackendErrors (sdk-backend/errors.ts) so a thrown SDK error becomes a typed BackendError (code: 'not_found' | 'forbidden' | 'rate_limited' | 'upstream_error' | 'invalid_input') before it reaches the tool layer. asErrorResult (text-result.ts) renders any BackendError uniformly as [code] message, regardless of which backend produced it. This per-domain split is deliberate: a new domain adds one backend/<domain>.ts + one sdk-backend/<domain>.ts + a one-line barrel registration in each index.ts, keeping the conflict surface for parallel domain work small.

Audit telemetry

BuildMcpServerOpts.onToolCall?: (event: ToolCallEvent) => void fires once per tool call with { toolName, operation?, outcome: 'ok'|'error'|'denied', durationMs, requestId?, auth: {kind, subject, ownerId?, clientId?} } — never token, call arguments, or secrets. The HTTP/stdio server wires this to a structured JSON line on stderr (audit-log.ts) — deliberately never stdout, since the stdio transport reserves stdout exclusively for JSON-RPC framing (a stray stdout line there corrupts the protocol stream); this package's log() helper (log.ts) follows the same rule for every log level, not just warn/error. A host with its own observability stack can swap the audit sink for a real exporter without touching the core.

Contract & versioning

See packages/tools/CONTRACT.md for the semver rules (tool rename/removal = major, new tool/optional field/enum value = minor, description-only = patch) and the deprecation policy. packages/tools/src/__tests__/schema-snapshot.test.ts snapshots the full-access tool surface (names + input schemas) so an unintended shape change fails CI as a snapshot diff.