Nightjar Docs
Alpha

Quickstart — a cloud browser in two calls

Who this is for. You want the fastest possible path from “I have an agent” to “my agent is driving a real browser.” No install, no daemon, no local anything — just a token and an MCP endpoint. For the full picture (all hosts, local reach, the mental model), read Getting started.

You need an org invite first — or this 403s. Alpha access is gated by org membership: a GitHub login with no org sees an empty console, can’t mint a token, and a token without the right scopes is refused one call in (session_start → 403). If you don’t have an invite yet, that’s the thing to get — nothing below works without it.

Step 1 — Get a token (Today)

Log in to console.nightjar.cloud with GitHub, land in your org, and mint an API key (njk_…) with at least the sessions:write and sessions:drive scopes — create the session, then drive it. Hosts that support remote-MCP OAuth (Claude Code, Codex, Gemini) can skip the copy-paste entirely and log in via OAuth — see Getting started for that path.

Step 2 — Point your host at the MCP endpoint (Today)

The hosted endpoint is https://api.nightjar.cloud/mcp — streamable-HTTP MCP. Log in once and let the CLI attach authorization for you:

nightjar auth login

That stores the credential per-user and serves it through nightjar mcp serve, a stdio-to-HTTPS proxy that attaches authorization at request time — so a rotated key takes effect on the next request, with no restarts.

Every other host (Claude Desktop, Codex, Gemini, a custom SDK client) reaches the same endpoint — exact recipes in Getting started.

Deprecated: passing the key yourself via Authorization: Bearer ${VAR}. The pattern below still works and is not being removed, but it is no longer the recommended path:

export NIGHTJAR_API_KEY="njk_your_token_here"
claude mcp add --scope user --transport http nightjar https://api.nightjar.cloud/mcp 
  --header "Authorization: Bearer $NIGHTJAR_API_KEY"

An environment variable’s value resolves through a process tree — OS → editor → extension host → harness — and is frozen at each process’s launch, so a rotated key propagates only via full restarts. That cost a freshly-minted key three harness restarts and ~5 hours to reach its binding (prism#2197), despite correct installation within minutes. nightjar auth login has no such path.

⚠ This deprecates carrying the credential in an env var / header template — not remote-MCP OAuth, which stays fully supported (see Step 1).

Step 3 — The two-call delight (Today)

Ask your agent:

Use the nightjar tools to open https://example.com and tell me what the page says. Then take a screenshot.

Under the hood that is the whole loop: session_start → navigate → perceive (a structured, agent-readable view of the page) → screenshot → session_end. No browser installed on your machine, nothing to clean up — the browser ran in Nightjar’s cloud and the session ends when your agent says so.

That’s the product. Everything else — logged-in identities, credential fills that never expose the secret, reaching your own localhost, artifacts and clipboards — is layered on top of this loop. Skim the glossary to see the shape of it.

If it fails one call in

  • session_start → 403 naming a missing scope. Your token is scope-thinner than the tool needs (a clamped OAuth token, or a key minted without sessions:write / sessions:drive). Mint a fuller key in the console and update your MCP config — the error names the scope it wants.
  • Connected but 0 tools. Usually a stale client connection or a bad key — the troubleshooting guide walks the diagnosis.
  • The console is empty after login. You’re not in an org yet — that’s the invite gate above, not a bug.

Where next

  • Getting started — every host, plus Part 2: reaching your own localhost (the co-location rule lives there).
  • Local reach — what’s Today vs Target for driving the app on your own machine.
  • Troubleshooting — what you see → why → what to do.