@nativapi/mcp-app

An MCP App server that renders Nativ's live Steel browser session — and an in-chat 2FA input — inside MCP-Apps hosts like Claude.

How this differs from @nativapi/mcp

| | @nativapi/mcp | @nativapi/mcp-app | |---|---|---| | Transport | stdio (local process) | HTTP / StreamableHTTP | | UI | headless — text only | interactive panel in the host chat | | Intended use | local AI agents, Claude Desktop | deployed service added as a custom connector | | Setup | config block in .mcp.json | deploy → Settings → Connectors |

@nativapi/mcp is for headless local agents. This package is the HTTP server variant: deploy it, point Claude (or any MCP-Apps host) at the public URL, and your agent calls run_tool — a live Steel browser session streams straight into the chat panel.

Tools

The server registers 3 tools:

| Tool | Description | |------|-------------| | run_tool | Run a tool on a connected account and watch the live browser session in the panel. Provide either connectionId, or connectedAccountId + integrationId. Returns the interaction; if status is awaiting_mfa, a 2FA input appears in the panel. | | get_interaction | Poll the current status and output/error of an interaction by id. | | submit_mfa | Submit a 2FA code for an interaction that is awaiting_mfa. Returns the updated interaction. |

connect_account is not registered — accounts are connected via the CLI (nativ connect) or dashboard before the agent runs. Raw credentials never pass through the agent.

Run locally

Prerequisites: Node 20+, pnpm (via corepack).

# 1. Build (tsc + vite singlefile)
NATIV_API_KEY=isk_… corepack pnpm -C packages/mcp-app build

# 2. Serve
NATIV_API_KEY=isk_… corepack pnpm -C packages/mcp-app serve

The server listens on http://localhost:3002/mcp by default.

| Env var | Required | Default | |---------|----------|---------| | NATIV_API_KEY | Yes | — | | NATIV_BASE_URL | No | https://api.nativapi.dev | | PORT | No | 3002 |

The MCP endpoint is at <base>/mcp (POST, StreamableHTTP).

Test with the official MCP-Apps basic-host

git clone https://github.com/modelcontextprotocol/ext-apps
cd ext-apps/examples/basic-host
npm install
SERVERS='["http://localhost:3002/mcp"]' npm start

Open the host in your browser, call run_tool, and watch the live Steel session render in the panel. When the interaction reaches awaiting_mfa the panel shows a 2FA input; submitting it calls submit_mfa automatically.

Deploy to Railway

1. Push the repo (or just the packages/mcp-app folder) to a Railway service.
2. Set the environment variables:
   • NATIV_API_KEY — your Nativ API key (required)
   • NATIV_BASE_URL — override only if you use a non-production Nativ environment (optional)
3. Railway exposes a public HTTPS URL — the MCP endpoint is <your-railway-url>/mcp.

The service is a plain HTTP server (express); no special Railway config is needed beyond the env vars.

Add to Claude as a custom connector

Requires a paid Claude plan (custom connectors are not available on the free tier).

1. Deploy the service (see above) and note the public HTTPS URL.
2. In Claude → Settings → Connectors → Add custom connector.
3. Enter <your-railway-url>/mcp as the connector URL.
4. Claude connects and the run_tool, get_interaction, and submit_mfa tools become available in your chats.

The UX

When the agent calls run_tool, a panel renders in the chat showing:

• Live Steel browser session — an iframe pointing at the sessionViewerUrl returned by the Nativ API, so you can watch the automation in real time.
• Status indicator — polls the interaction and updates as it moves through running → completed (or failed).
• 2FA input — if the interaction reaches awaiting_mfa, the panel shows the MFA prompt and a code input. Submitting the code calls submit_mfa on your behalf; the panel then polls for the final result.

The UI is a single self-contained HTML file (dist/run.html) bundled by Vite and served inline via the MCP resource protocol. It runs inside the host's sandboxed iframe.

Security

• connect_account is excluded — the agent only acts on already-connected accounts; it never handles raw credentials.
• v1 uses a single shared NATIV_API_KEY set in the server environment. Per-user OAuth is out of scope for v1.
• The live-session iframe is allowed to frame https://api.steel.dev and connect to it; all other origins are blocked by CSP.
• The UI runs in the MCP-Apps host's sandboxed iframe environment.

License

MIT