Skip to main content
Every Nora Local deployment — desktop, compose, Kubernetes, air-gap — exposes the same MCP server as SaaS at POST /api/v1/mcp on the on-prem host. Point your coding agent at the local URL and you get the identical tool surface (Flow CRUD, block ops, wiring, variables, publish, traces).

​
The URL

  • The desktop app and compose paths default to http://localhost:8090/api/v1/mcp. Change NORA_HOST_PORT in .env.onprem if that port is taken — the MCP URL moves with it.
  • The Kubernetes path uses whatever hostname you set for publicUrl in the Helm chart (for example https://nora.example.internal/api/v1/mcp). See Kubernetes (Helm).

​
Connecting

  • nora-local is just the alias Claude Code shows in its tool list — pick a name that distinguishes it from any SaaS nora entry you already have.
  • --scope user writes it to ~/.claude.json so every project on this laptop sees the local server. Drop the flag to register only in the current project.
  • The first tool call opens an OAuth login in your browser against your own local server. Sign in with a Nora Local account and grant read · build · run.
Verify:

​
OAuth requires NORA_PUBLIC_URL to match

The OAuth flow bounces the browser back to a callback URL the server advertises. That URL comes from NORA_PUBLIC_URL (and NORA_OAUTH_REDIRECT_BASE), so both need to match the URL your browser actually hits.
  • Localhost defaults — http://localhost:${NORA_HOST_PORT:-8090} works out of the box for the desktop app and single-host compose.
  • Reverse proxy or ingress — set NORA_PUBLIC_URL=https://nora.example.internal (or Helm’s publicUrl) to the public URL. Otherwise the OAuth callback lands on http://localhost:8090, the browser can’t reach it, and the login stalls.

​
Alongside a SaaS entry

Register both with different aliases so tool names stay unambiguous.
Claude Code prefixes each tool with the server alias, so nora_list_flows and nora-local_list_flows are cleanly separated.

​
What’s exposed

The tool surface is identical to SaaS — see MCP tool surface for the full list. Permissions mirror your Nora Local role: a Guest can only read; approval-gated actions still go through the approval flow when run over MCP.

​
Air-gap notes

Nothing about MCP requires internet access — the whole flow (OAuth login, tool calls) stays on your local host.
  • If NORA_AIRGAP=1 is on, the server still serves MCP normally. The boot probe only checks the server can’t reach the public internet; it doesn’t restrict inbound traffic from the local browser or CLI.
  • For headless server installs where the target host has no browser, run the coding agent on a laptop that can reach the server over the LAN, and set NORA_PUBLIC_URL to the LAN hostname (http://nora.internal:8090) so the OAuth callback lands somewhere your browser can hit.

​
Troubleshooting

  • connection refused on claude mcp add. The stack isn’t up. Check docker ps or the desktop app tray. The URL must include the scheme (http://, not just localhost:8090).
  • OAuth login page 404s or hangs. NORA_PUBLIC_URL doesn’t match the URL your browser is on. Set it to the exact base URL (scheme + host + port) you’re using and restart the stack.
  • Tool list is empty after login. The account you signed in with has no workspace access on this server. Check permissions on the SPA (Settings → Members), then reconnect.
  • nora-local and nora collide. They don’t — Claude Code prefixes tool names per server. If tools appear duplicated in the picker, restart the host so the tool list refreshes.

MCP (SaaS)

The same page for the hosted platform.nora.my server.

Settings — host port

Change NORA_HOST_PORT when the default 8090 is taken.

Kubernetes (Helm)

publicUrl chart value and ingress setup.