Nora Local 의 MCP

URL

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

• 포트를 바꿨다면 앱 설정 의 호스트 포트 값으로 8090 을 바꿔 넣습니다. compose 로 띄웠다면 .env.onprem 의 NORA_HOST_PORT 값입니다.
• Kubernetes 경로는 Helm 차트의 publicUrl 에 설정한 호스트네임을 씁니다 (예: https://nora.example.internal/api/v1/mcp). Kubernetes (Helm) 을 참고하세요.

인증하기

경로 A — 데스크톱 앱 OAuth (macOS)

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

경로 B — 브라우저 OAuth

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

경로 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_..."
      }
    }
  }
}

SaaS 와 함께 등록하기

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

# 로컬 서버
claude mcp add --transport http --scope user nora-local \
  http://localhost:8090/api/v1/mcp

노출되는 도구

에어갭 노트

• NORA_AIRGAP=1 이 켜져 있어도 서버는 MCP 를 그대로 서빙합니다. 부팅 프로브는 서버가 공용 인터넷 에 못 닿는지만 확인하고, 로컬 브라우저 · CLI 의 인바운드 트래픽은 제한하지 않습니다.
• 타겟 호스트에 브라우저가 없는 헤드리스 서버 설치라면, LAN 으로 서버에 닿을 수 있는 노트북에서 코딩 에이전트를 실행하고 NORA_PUBLIC_URL 을 LAN 호스트네임 (예: http://nora.internal:8090) 으로 설정해 콜백이 도달 가능한 곳으로 돌아가게 합니다. PAT (경로 C) 는 브라우저 단계 자체를 생략하는 대안입니다.

문제 해결

• claude mcp add 에서 connection refused. 스택이 꺼져 있는 상태입니다. docker ps 또는 데스크톱 앱 트레이로 확인하세요. URL 에는 스킴 (http://) 이 반드시 포함되어야 하고, 포트는 스택 부팅 시점의 NORA_HOST_PORT 값과 일치해야 합니다.
• OAuth /oauth/desktop 페이지에 “Open Nora” 링크가 안 보임. 서버가 NORA_DEPLOY_FLAVOR=saas 로 돌고 있거나 (compose 기본은 onprem — .env.onprem 확인) issuer 가 로컬호스트가 아닌 경우입니다 (리버스 프록시로 공개 호스트명에 접근 중). 브라우저 OAuth (경로 B) 또는 PAT (경로 C) 를 사용하세요.
• OAuth 로그인 페이지가 404 · 무한 로딩. NORA_PUBLIC_URL 이 브라우저 접속 URL 과 일치하지 않는 경우입니다. 스킴 · 호스트 · 포트가 실제와 정확히 같은 값으로 지정하고 스택을 재시작하세요.
• OAuth 경로인데 첫 툴 호출에 아무 일도 안 일어남. OAuth 는 자동 트리거가 아닙니다. Claude Code 세션에서 /mcp → nora-local 선택 → [Authenticate] 를 눌러야 핸드셰이크가 시작됩니다.
• PAT 헤더 방식인데 401 반복. 토큰이 철회 · 만료되었거나 오타입니다. SPA 의 Settings → Personal Access Tokens 에서 확인한 뒤 claude mcp remove nora-local 로 지우고 새 토큰으로 다시 등록하세요.
• 로그인 후 툴 목록이 비어 있음. 로그인한 계정이 이 서버의 워크스페이스에 접근 권한이 없는 경우입니다. SPA 의 Settings → Members 에서 권한을 확인한 뒤 재연결합니다.

관련