aura-mcp-connect

A zero-config WebRTC bridge for AURA's on-device MCP server.

Lets any MCP-capable client — Claude Desktop, VS Code (Copilot MCP), Cursor, Cline, Windsurf, Zed — talk to AURA completely wirelessly from anywhere in the world, securely, without fighting firewalls or configuring IP addresses.

Architecture & Security Model

This bridge implements a true production-grade WebRTC edge stack for connecting IDEs to mobile devices:

1. Persistent Device Pairing: The phone generates a random 6-digit PIN. The PC proxy uses this PIN once to exchange a secure clientToken and a permanent deviceId over Firebase. The PC saves this token to ~/.aura/webrtc.json.
2. Device Approval: On the first connection, the phone intercepts the connection and prompts the user via an Android UI popup (Approve PC Client?). If approved, the phone saves the PC as a Trusted Client.
3. Seamless Reconnects: On all future IDE restarts, the connection happens instantly and silently in the background without any new PINs or UI popups.
4. NAT Traversal (STUN + TURN): Both devices use Google's STUN to punch through local NATs/routers. If STUN fails (e.g. strict corporate firewalls), it seamlessly falls back to a public TURN relay.
5. End-to-End Encryption (DTLS/SCTP): Once the peer-to-peer connection is established, the actual MCP JSON-RPC data flows directly between your PC and your phone. The data is always encrypted end-to-end via WebRTC's mandatory DTLS encryption.

Installation

For a production setup, install the bridge globally on your PC:

npm install -g aura-mcp-connect

Usage

Open the Aura UI app on your phone, tap Start WebRTC, and note the 6-digit PIN.

Configure your MCP client (e.g. Cursor, Claude Desktop) with the following JSON. You only need to provide the PIN once for the initial pairing:

{
  "mcpServers": {
    "aura-android": {
      "command": "aura-mcp",
      "args": [
        "--pin=123456"
      ]
    }
  }
}

Whenever the session ends or you restart your IDE, it will connect automatically. You do not need to generate a new PIN — drop the --pin arg entirely and the saved pairing in ~/.aura/webrtc.json is reused:

{
  "mcpServers": {
    "aura-android": { "command": "aura-mcp", "args": [] }
  }
}

Arguments

| Argument | Description | |---|---| | --pin | The 6-digit PIN generated by the Aura app. Required for the first pairing; omit it afterwards to reuse the saved pairing. |

Failure modes & limitations

| What happens | What you see | |---|---| | Incorrect PIN or phone offline | WebRTC signaling timed out waiting for answer from phone | | Strict Corporate Firewall blocks UDP | WebRTC fails to establish ICE connection (STUN blocked) | | First-time pairing not approved quickly | The free public TURN relay drops an unapproved idle channel after ~20–30 s, so the connection closes before you tap Approve. Approve promptly on the first pairing. After that, the saved trusted token auto-approves with no dialog, so this never applies to reconnects. For production, point both ends at a dedicated TURN server with a longer idle timeout. |

Security model

Signalling flows through Firebase Realtime Database, but the actual MCP traffic is end-to-end encrypted over WebRTC DTLS and never touches Firebase. Access control is known-key: the RTDB rules (database.rules.json at the repo root) block listing of the pins/devices collections, so an attacker cannot enumerate active PINs or device IDs — they can only reach a node whose exact 6-digit PIN (short-lived, consumed on use) or 122-bit device UUID they already hold. Deploy those rules before exposing the project; for stronger guarantees, enable Firebase Anonymous Auth and require auth != null.

All log output goes to stderr, never stdout — stdout is reserved strictly for MCP JSON-RPC frames.

License

MIT. See LICENSE.