MCP on Nora Local

The URL

http://localhost:8090/api/v1/mcp

• If you changed the port, replace 8090 with the Host port from the app’s Settings. On a compose install it is NORA_HOST_PORT in .env.onprem.
• 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).

Authenticating

Path A — Desktop app OAuth (macOS)

claude mcp add --transport http --scope user nora-local \
  http://localhost:8090/api/v1/mcp

Path B — Browser OAuth

claude mcp add --transport http --scope user nora-local \
  http://localhost:8090/api/v1/mcp

Path C — Personal Access Token

nora auth login --host http://localhost:8090

claude mcp add --transport http --scope user nora-local \
  --header "Authorization: Bearer nora_pat_..." \
  http://localhost:8090/api/v1/mcp

codex mcp add --transport http nora-local \
  --header "Authorization: Bearer nora_pat_..." \
  http://localhost:8090/api/v1/mcp

{
  "mcpServers": {
    "nora-local": {
      "type": "http",
      "url": "http://localhost:8090/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer nora_pat_..."
      }
    }
  }
}

Alongside a SaaS entry

# SaaS
claude mcp add --transport http --scope user nora \
  https://platform.nora.my/api/v1/mcp

# Your local server
claude mcp add --transport http --scope user nora-local \
  http://localhost:8090/api/v1/mcp

What’s exposed

Air-gap notes

• If NORA_AIRGAP=1 is on, the server still serves MCP normally. The boot probe only checks that 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 OAuth callbacks land somewhere reachable. PAT (Path C) also avoids the browser step entirely.

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://), and the port must match what NORA_HOST_PORT was set to when the stack booted.
• OAuth /oauth/desktop page doesn’t offer the “Open Nora” link. Either the server is running with NORA_DEPLOY_FLAVOR=saas (the compose default is onprem — check your .env.onprem), or the issuer isn’t loopback (you’re hitting a public hostname via reverse proxy). Use browser OAuth (Path B) or PAT (Path C) instead.
• OAuth login page 404s or hangs after consent. 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.
• Nothing happens on the first tool call (OAuth path). OAuth doesn’t auto-launch. In Claude Code, run /mcp → select nora-local → [Authenticate].
• 401 loop with a PAT header. The token was revoked, expired, or has a typo. Confirm on Settings → Personal Access Tokens in the SPA, then re-run claude mcp remove nora-local and add it again with a fresh token.
• 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.

Related