> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# Nora Local 의 MCP

> 자가 호스팅한 Nora 를 Claude Code, Codex CLI, Cursor 로 조작합니다. SaaS 와 동일한 도구 표면을 로컬 서버에 대고 씁니다.

Nora Local 은 형태와 무관하게 — 데스크톱, compose, Kubernetes, 에어갭 — SaaS 와 **동일한 MCP 서버** 를 `POST /api/v1/mcp` 로 노출합니다. 코딩 에이전트가 로컬 URL 을 가리키기만 하면 Flow CRUD, 블록 조작, 배선, 변수, 배포, 트레이스까지 SaaS 와 같은 도구 표면을 그대로 씁니다.

## URL

```text theme={null}
http://localhost:${NORA_HOST_PORT:-8090}/api/v1/mcp
```

* **데스크톱 앱** 과 **compose** 경로는 기본이 `http://localhost:8090/api/v1/mcp` 입니다. 포트가 겹치면 `.env.onprem` 의 `NORA_HOST_PORT` 를 바꾸세요. MCP URL 도 함께 이동합니다.
* **Kubernetes** 경로는 Helm 차트의 `publicUrl` 에 설정한 호스트네임을 씁니다 (예: `https://nora.example.internal/api/v1/mcp`). [Kubernetes (Helm)](/ko/local-app/deploy/kubernetes) 을 참고하세요.

## 연결하기

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http --scope user nora-local \
      http://localhost:8090/api/v1/mcp
    ```

    * `nora-local` 은 Claude Code 툴 목록에 보일 별칭입니다. 이미 등록된 SaaS `nora` 와 구분되도록 이름을 지어 주세요.
    * `--scope user` 는 `~/.claude.json` 에 씁니다. 이 노트북의 모든 프로젝트에서 로컬 서버가 보입니다. 플래그를 빼면 현재 프로젝트에만 등록됩니다.
    * 첫 툴 호출에서 브라우저가 **로컬 서버 자체** 로 OAuth 로그인 창을 엽니다. Nora Local 계정으로 로그인해 `read` · `build` · `run` 에 동의합니다.

    확인:

    ```bash theme={null}
    claude mcp list          # nora-local 이 목록에 있는지 확인
    claude mcp get nora-local
    ```
  </Tab>

  <Tab title="Codex CLI">
    ```bash theme={null}
    codex mcp add --transport http nora-local \
      http://localhost:8090/api/v1/mcp
    ```

    첫 툴 호출에서 브라우저 OAuth 창이 뜹니다. `codex mcp list` 로 확인.
  </Tab>

  <Tab title="Cursor · 기타 호스트">
    호스트의 MCP 설정에 항목을 추가합니다.

    ```json theme={null}
    {
      "mcpServers": {
        "nora-local": {
          "type": "http",
          "url": "http://localhost:8090/api/v1/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## OAuth 는 NORA\_PUBLIC\_URL 이 맞아야 동작합니다

OAuth 흐름은 서버가 광고하는 콜백 URL 로 브라우저를 되돌립니다. 이 URL 은 `NORA_PUBLIC_URL` (과 `NORA_OAUTH_REDIRECT_BASE`) 이 결정하므로, 브라우저가 실제로 접속하는 URL 과 정확히 같아야 합니다.

* **로컬호스트 기본값** — 데스크톱 앱과 단일 호스트 compose 는 기본 `http://localhost:${NORA_HOST_PORT:-8090}` 로 그대로 됩니다.
* **리버스 프록시 · 인그레스 뒤** — `NORA_PUBLIC_URL=https://nora.example.internal` (또는 Helm 의 `publicUrl`) 을 실제 공개 URL 로 세팅합니다. 안 그러면 OAuth 콜백이 `http://localhost:8090` 으로 돌아가고 브라우저가 그 주소에 못 닿아 로그인이 멈춥니다.

## SaaS 와 함께 등록하기

별칭을 다르게 지으면 툴 이름이 겹치지 않습니다.

```bash theme={null}
# 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
```

Claude Code 는 툴 이름 앞에 서버 별칭을 붙이므로 `nora_list_flows` 와 `nora-local_list_flows` 가 깔끔하게 분리됩니다.

## 노출되는 도구

도구 표면은 SaaS 와 동일합니다. 전체 목록은 [MCP 도구 표면](/ko/cli/mcp#mcp가-제공하는-도구) 을 참고하세요. 권한도 Nora Local 의 역할을 그대로 따릅니다. Guest 는 읽기만 가능하고, 승인이 필요한 액션은 MCP 로 실행해도 승인 절차를 그대로 거칩니다.

## 에어갭 노트

MCP 는 인터넷 접근이 필요 없습니다. OAuth 로그인과 툴 호출을 포함한 전체 흐름이 로컬 호스트 안에서 끝납니다.

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

## 문제 해결

* **`claude mcp add` 에서 `connection refused`.** 스택이 꺼져 있는 상태입니다. `docker ps` 또는 데스크톱 앱 트레이로 확인하세요. URL 에는 스킴 (`http://`) 이 반드시 포함되어야 합니다.
* **OAuth 로그인 페이지가 404 · 무한 로딩.** `NORA_PUBLIC_URL` 이 브라우저 접속 URL 과 일치하지 않는 경우입니다. 스킴 · 호스트 · 포트가 실제와 정확히 같은 값으로 지정하고 스택을 재시작하세요.
* **로그인 후 툴 목록이 비어 있음.** 로그인한 계정이 이 서버의 워크스페이스에 접근 권한이 없는 경우입니다. SPA 의 `Settings → Members` 에서 권한을 확인한 뒤 재연결합니다.
* **`nora-local` 과 `nora` 가 부딪히는 것처럼 보임.** 실제로는 안 부딪힙니다. Claude Code 는 서버별로 툴 이름 앞에 별칭을 붙입니다. 픽커에 중복이 보이면 호스트를 재시작해 툴 목록을 새로고침하세요.

## 관련

<CardGroup cols={2}>
  <Card title="MCP (SaaS)" icon="plug" href="/ko/cli/mcp">
    호스팅된 `platform.nora.my` 서버에 대한 같은 페이지.
  </Card>

  <Card title="Settings — 호스트 포트" icon="sliders" href="/ko/local-app/desktop/settings">
    기본 8090 이 겹칠 때 `NORA_HOST_PORT` 를 바꿉니다.
  </Card>

  <Card title="Kubernetes (Helm)" icon="dharmachakra" href="/ko/local-app/deploy/kubernetes">
    Helm `publicUrl` 값과 인그레스 세팅.
  </Card>
</CardGroup>