appium-mcp-auth

Authentication & authorization for appium-mcp when hosted over SSE / HTTP Stream — built entirely on the appium-mcp Plugin API (no core changes).

When you expose appium-mcp over SSE, anyone who can reach the port gets a full Appium session and can drive real devices. appium-mcp-auth adds a security layer as a drop-in plugin:

• 🔑 Bearer API keys (ak_<id>_<secret>) — hashed at rest, constant-time compared. For machines / CI.
• 🪪 OAuth JWT access tokens — validated against the issuer JWKS (iss/aud/exp). For humans / IDE clients.
• 🎫 Session tokens — exchange an API key for a short-lived token via auth_login.
• 🛂 Scope-based authorization — per-tool required scopes, admin-role bypass.
• 🧑‍🤝‍🧑 Per-caller session ownership — callers only see/drive the Appium sessions they created (multi-tenant isolation).
• 🚦 Rate limiting & session quotas — per subject.

How it works (read this first)

A plugin runs inside appium-mcp's beforeCall / afterCall hooks and cannot read HTTP headers — so the credential is passed as a tool argument (default authToken). Authentication and authorization both happen in beforeCall; a denied call is short-circuited before the tool runs.

tool call ──► beforeCall(ctx)
                1. authenticate ctx.args.authToken → Identity   (apiKey | sessionToken | oauth)
                2. rate-limit per subject
                3. authorize tool vs Identity.scopes  (admin role bypasses)
                4. ownership: any sessionId arg must be owned by the caller
                5. session-creating tool? enforce per-subject session quota
              allow → tool runs   |   deny → error result (tool never runs)
            ──► afterCall: bind new sessions to caller, release deleted ones

Implications (by design):

• Terminate TLS in front of the server — the credential travels in the request body.
• No OAuth .well-known discovery endpoints (a plugin can't serve them); front with a gateway if your MCP client needs auto-negotiation. This package still validates JWTs.
• Calls that omit sessionId hit Appium's global active session — in multi-tenant mode, require an owned sessionId on every call.

Install

npm install @appclaw/appium-mcp-auth

That's it — appium-mcp (which brings fastmcp and zod) and jose for JWT validation come along automatically as regular dependencies. The plugin resolves the exact fastmcp/zod copies that appium-mcp uses at runtime, so there is no peer-dependency juggling.

Requires Node.js ≥ 20.

Implement it in your project

There are two ways to use it. Pick one.

Option 1 — Turnkey CLI (fastest)

Run this package's binary instead of appium-mcp's. It is the full appium-mcp SSE server with the auth plugin composed in — one process, same /sse endpoint.

# 1. Configure at least one credential (see "Configuration" below)
export APPIUM_MCP_AUTH_API_KEYS='[{"id":"ci","secret":"CHANGE-ME","subject":"ci-bot","scopes":["appium:use"]}]'

# 2. Start the auth-protected SSE server
npx @appclaw/appium-mcp-auth --httpStream --port=8080 --endpoint=/sse
# → SSE listening on http://localhost:8080/sse

Option 2 — Compose the plugin into your own server (most control)

If you already build a custom appium-mcp server, just add the plugin. No core changes required — createAppiumMcpServer already accepts plugins.

import { createAppiumMcpServer } from 'appium-mcp/core';
import { createAuthPluginFromEnv } from '@appclaw/appium-mcp-auth';

const server = await createAppiumMcpServer({
  plugins: [createAuthPluginFromEnv()], // reads APPIUM_MCP_AUTH_* env vars
});

await server.start({
  transportType: 'httpStream',
  httpStream: { endpoint: '/sse', port: 8080 },
});

Prefer explicit config over environment variables? Build the config yourself:

import { createAppiumMcpServer } from 'appium-mcp/core';
import { createAuthPlugin, sha256Hex, type AuthConfig } from '@appclaw/appium-mcp-auth';

const config: AuthConfig = {
  credentialArg: 'authToken',
  publicTools: ['auth_login'],
  apiKeys: [
    {
      id: 'ci',
      hash: sha256Hex('CHANGE-ME'),   // store the hash, not the secret
      subject: 'ci-bot',
      kind: 'service',
      scopes: ['appium:use'],
    },
  ],
  toolScopes: { mobile_clear_app: ['appium:admin'] },
  defaultScopes: ['appium:use'],
  adminRole: 'admin',
  sessionTokenTtlMs: 3_600_000,
  rateLimit: { limit: 120, windowMs: 60_000 },
  maxSessionsPerSubject: 3,
  enforceOwnership: true,
  sessionIdArgs: ['sessionId'],
  sessionCreatingTools: ['appium_session_management'],
  audit: true,
};

const server = await createAppiumMcpServer({
  plugins: [createAuthPlugin(config)],
});

How clients authenticate

Whatever the MCP client, the credential is supplied as the authToken argument on tool calls.

1. Exchange an API key for a session token (the auth_login tool is public):

   { "tool": "auth_login", "arguments": { "apiKey": "ak_ci_CHANGE-ME" } }
   → { "sessionToken": "st_…", "expiresAt": "…" }

2. Pass the token (or the API key, or an OAuth JWT) as authToken on every subsequent call:

   { "tool": "appium_session_management", "arguments": { "action": "create", "authToken": "st_…" } }
   { "tool": "appium_gesture", "arguments": { "sessionId": "…", "authToken": "st_…" } }

3. auth_whoami echoes the caller identity; auth_logout revokes a session token.

Will my MCP client work?

| Client behavior | Works? | How | |---|---|---| | Sends an Authorization: Bearer header (Cursor, Claude Desktop, most SSE clients) | ✅ | Run gateway mode (below) — it reads the header and injects the credential. No per-call argument needed. | | Forwards agent-chosen tool arguments verbatim (e.g. AppClaw) | ✅ | Pass the token as the authToken argument (shown above). | | Injects a fixed argument on every tool call | ✅ | Set authToken deterministically instead of relying on the LLM. |

Tip: for LLM-driven clients, prefer a session token (auth_login) over the raw API key so the long-lived secret isn't repeated in every prompt/trace.

Header auth for Cursor / Claude Desktop (gateway mode)

A plugin can't read HTTP headers, so header-based clients are served by a built-in credential-injecting reverse proxy. It reads the Authorization header, rewrites each tools/call to add the authToken argument, and forwards to the appium-mcp server on loopback. Nothing in appium-mcp core changes.

Cursor ──(Authorization: Bearer ak_…)──►  gateway (public :8080)  ──►  appium-mcp + plugin (127.0.0.1:8790)
                                            reads header,               beforeCall sees authToken,
                                            injects authToken arg        authorizes exactly as normal

Start it:

export APPIUM_MCP_AUTH_API_KEYS='[{"id":"dev","secret":"CHANGE-ME","subject":"dev","kind":"user","roles":["admin"],"scopes":["appium:use","appium:admin"]}]'
npx @appclaw/appium-mcp-auth --gateway --port=8080 --endpoint=/sse
# gateway (header auth) on http://localhost:8080/sse
# upstream on http://127.0.0.1:8790/sse (loopback — firewall this port)

Point Cursor at it — .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "appium-auth": {
      "url": "http://localhost:8080/sse",
      "headers": {
        "Authorization": "Bearer ak_dev_CHANGE-ME"
      }
    }
  }
}

Claude Desktop connects via the mcp-remote bridge:

{
  "mcpServers": {
    "appium-auth": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "http://localhost:8080/sse",
        "--header", "Authorization: Bearer ak_dev_CHANGE-ME"
      ]
    }
  }
}

The Bearer value is any accepted credential: an API key (ak_…), a session token from auth_login (st_…), or an OAuth JWT. Requests with no/invalid credential get 401. GET /health is always allowed for probes.

Gateway options: --port (public), --upstream-port (loopback inner server), --endpoint; APPIUM_MCP_AUTH_GATEWAY_HEADER changes which header is read (default authorization).

Security: put TLS in front (the token is in a header) and firewall the upstream port — the inner server trusts the injected authToken, so it must only be reachable through the gateway.

Configuration

All settings are environment variables (used by createAuthPluginFromEnv and the CLI). Full examples in .env.example.

| Variable | Purpose | Default | |---|---|---| | APPIUM_MCP_AUTH_API_KEYS | JSON array of API-key records (id, hash or secret, subject, kind, scopes, roles?, expiresAt?) | — | | APPIUM_MCP_AUTH_OAUTH | JSON OAuth JWT validation config (issuer, audience, jwksUri?, scopeClaim?, rolesClaim?) | — | | APPIUM_MCP_AUTH_ARG | Tool-argument name carrying the credential | authToken | | APPIUM_MCP_AUTH_PUBLIC_TOOLS | Comma list of tools that skip auth | auth_login | | APPIUM_MCP_AUTH_TOOL_SCOPES | JSON map tool → scope | scope[] | {} | | APPIUM_MCP_AUTH_DEFAULT_SCOPES | Scopes required for unlisted tools | appium:use | | APPIUM_MCP_AUTH_ADMIN_ROLE | Role that bypasses scope checks | admin | | APPIUM_MCP_AUTH_SESSION_TTL_MS | Session-token lifetime | 3600000 | | APPIUM_MCP_AUTH_RATE_LIMIT | "<limit>/<windowMs>" per subject | disabled | | APPIUM_MCP_AUTH_MAX_SESSIONS | Per-subject Appium session cap (0 = off) | 0 | | APPIUM_MCP_AUTH_ENFORCE_OWNERSHIP | Enforce session ownership | true | | APPIUM_MCP_AUTH_SESSION_ID_ARGS | Arg names carrying a session id | sessionId | | APPIUM_MCP_AUTH_SESSION_TOOLS | Tools that create sessions | appium_session_management | | APPIUM_MCP_AUTH_AUDIT | Emit JSON audit lines to stderr | true |

If neither API keys nor OAuth are configured, every protected call is denied and the server logs a warning at startup.

Create an API key (built-in command)

Use the keygen command — it prints the client bearer token and the server config record (which stores the hash, never the secret):

npx @appclaw/appium-mcp-auth keygen --id=ci --subject=ci-bot --scopes=appium:use

Give this to the CLIENT (Authorization header) — shown once, store it securely:
  Authorization: Bearer ak_ci_Tgaz5NSbOTqgz3A4s_CdPeV7FePHLExS

Add this record to APPIUM_MCP_AUTH_API_KEYS on the SERVER (stores the hash, not the secret):
  {"id":"ci","hash":"c65c…","subject":"ci-bot","kind":"service","scopes":["appium:use"]}

Flags: --id --subject [--scopes=a,b] [--kind=service|user] [--roles=admin] [--name="…"] [--expires-in=30d] [--secret=…] [--json].

The three strings are linked: the client presents ak_<id>_<secret>; the server stores hash = SHA256(secret); on each call it checks SHA256(presented secret) === stored hash (constant-time). The plaintext secret never leaves the client, and the --json form is handy for scripting/rotation.

Authorization model

• Scopes — each tool requires a scope set (APPIUM_MCP_AUTH_TOOL_SCOPES), falling back to APPIUM_MCP_AUTH_DEFAULT_SCOPES. A caller needs all of them.
• Admin role — a caller with the admin role bypasses scope checks.
• Ownership — sessions a caller creates are bound to its subject; a call referencing someone else's tracked sessionId is denied (not_session_owner). Untracked ids (pre-existing / attach flows) pass through.
• Quota / rate limit — per subject, via MAX_SESSIONS and RATE_LIMIT.

Public API

import {
  AppiumAuthPlugin,          // the plugin class
  createAuthPlugin,          // build from an AuthConfig
  createAuthPluginFromEnv,   // build from environment
  buildAuthenticatedServer,  // full server (used by the CLI)
  loadConfig, sha256Hex,     // config helpers
  // building blocks: Authenticator, Authorizer, KeyStore, OAuthValidator,
  // OwnershipRegistry, RateLimiter, AuditLog
} from '@appclaw/appium-mcp-auth';

Security notes

• Store API-key hashes, never plaintext secrets, in committed config.
• Give services and humans distinct scopes so a leaked CI key can't act as a human.
• Pin OAuth issuer and audience so tokens minted for other apps are rejected.
• Rate limiter and ownership map are process-local — front with a shared store (e.g. Redis) if you run multiple SSE replicas.
• Credentials are never written to audit logs.

Development

npm install
npm run typecheck   # tsc --noEmit
npm test            # node:test via tsx (35 tests)
npm run build       # emit dist/

License

Apache-2.0