# echolot mcp (/ko/docs/cli/mcp)

`echolot mcp`는 MCP 서버를 두 방향으로 다룹니다. `check`와 `sign-in`은 [MCP 서버 페이지](/docs/mcp-servers)처럼 다른 사람의 서버와
통신합니다. `serve`와 `setup`은 사용자의 작업 공간을 MCP 서버로 만들어, Claude Code나 Cursor 같은 AI 에이전트가 요청을 나열하고, 보내고,
테스트할 수 있게 합니다. [에이전트](/docs/ai/agents)를 참조하십시오.

| 하위 명령 | 동작 |
| --- | --- |
| `echolot mcp check` | MCP 서버에 연결해 제공하는 기능을 나열합니다. `--quality`는 모델이 그 도구를 보는 방식을 보고합니다. |
| `echolot mcp sign-in` | OAuth를 요구하는 작업 공간의 MCP 서버에 로그인합니다. |
| `echolot mcp sign-out` | 이 Mac에서 그 로그인을 지웁니다. |
| `echolot mcp serve` | MCP를 통해 작업 공간을 에이전트에 제공합니다. |
| `echolot mcp setup` | MCP 클라이언트를 작업 공간에 연결하는 방법을 출력합니다. |

## echolot mcp check [#echolot-mcp-check]

```sh
echolot mcp check [--url <url>] [--header <header> ...] [--env <env> ...] [--verbose] [--timeout <seconds>] [--quality] [--strict] [--as <provider>] -- [<command> ...]
```

`--url`로 Streamable HTTP 엔드포인트를 지정하거나, `--` 뒤에 stdio 서버를 시작하는 명령을 지정합니다. Echolot은 서버가 상태 비저장
프로토콜(2026-07-28)을 쓰는지, 핸드셰이크가 있는 이전 프로토콜을 쓰는지 알아내고, 서버의 도구, 리소스, 프롬프트를 나열합니다.

```sh
echolot mcp check --url https://demo.echolot.dev/mcp
```

```text
alpenglow-mcp 1.5.0: MCP 2025-11-25 (session, initialize)
  connected in 263 ms, round trip 54 ms
  instructions: The Alpenglow demo shop from docs.echolot.dev. Read-only: search the catalog, look up products and orders.
3 tools
  search_catalog: Searches the Alpenglow catalog by text and returns matching products with price and stock.
  get_product: Returns one product by SKU, with its price, weight, rating and stock per warehouse.
  order_status: Returns an order's status, total and shipping estimate.
1 resource
  alpenglow://catalog/categories  categories
1 prompt
  pack_for_a_trip: Suggests gear for a trip.
```

stdio 서버:

```sh
echolot mcp check -- npx -y @modelcontextprotocol/server-everything
echolot mcp check -e API_KEY=demo -- uvx some-mcp-server --flag
```

### 모델이 도구를 보는 방식 [#how-a-model-sees-the-tools]

`--quality`는 모델이 서버에서 받게 되는 내용을 추가합니다. 도구 목록이 매 턴마다 각 제공업체의 컨텍스트에서 차지하는 비용(추정치),
비용이 가장 큰 도구, 스키마 문제나 불분명하거나 겹치는 설명처럼 모델이 혼동할 만한 부분입니다. 앱의 **모델이 이 서버를 보는 방식**과
같은 보고서입니다. [도구와 품질](/docs/mcp-servers/tools-and-quality)을 참조하십시오.

```sh
echolot mcp check --url https://demo.echolot.dev/mcp --quality
```

```text
How a model sees the tools (estimates)
  Anthropic      572 tokens a turn, 0.3% of a 200k context
  OpenAI         166 tokens a turn, 0.1% of a 200k context
  Google Gemini  225 tokens a turn, 0.1% of a 200k context
  largest: search_catalog 98, get_product 66, order_status 62
Nothing a model would stumble over.
```

`--strict`는 CI용으로, 문제(경고나 참고가 아닌)가 있으면 1로 종료합니다. `--as anthropic`, `--as openai`, `--as gemini`는 그
제공업체의 API가 받는 형태의 도구 목록만 출력합니다.

| 옵션 | 의미 |
| --- | --- |
| `--url <url>` | Streamable HTTP 엔드포인트. 예: `http://127.0.0.1:3000/mcp`. |
| `-H`, `--header <header>` | `--url`용 HTTP 헤더, `'Name: value'` 형식. 반복할 수 있습니다. |
| `-e`, `--env <NAME=value>` | stdio 서버용 환경 변수. 반복할 수 있습니다. |
| `-v`, `--verbose` | 주고받은 모든 메시지를 표준 오류에 출력합니다. |
| `--timeout <seconds>` | 각 응답을 기다리는 시간(초). 기본값은 30입니다. |
| `--quality` | 모델이 도구를 보는 방식을 보고합니다. 제공업체별 비용, 스키마와 설명의 문제. |
| `--strict` | `--quality`와 함께: 문제가 있으면 1로 종료합니다. |
| `--as <provider>` | 제공업체의 API가 받는 형태의 도구 목록만 출력합니다: `anthropic`, `openai`, `gemini`. |

## echolot mcp sign-in과 sign-out [#echolot-mcp-sign-in-and-sign-out]

```sh
echolot mcp sign-in <server> [--workspace <workspace>] [--env <env>] [--force] [--print] [--verbose]
echolot mcp sign-out <server> [--workspace <workspace>]
```

`<server>`는 작업 공간의 `mcp-servers` 폴더에 있는, `.toml`을 뺀 서버의 파일 이름입니다. 로그인하면 브라우저가 열리고 127.0.0.1에서
리디렉션을 기다립니다.

```sh
echolot mcp sign-in alpenglow-mcp -w Alpenglow.echolot
```

- Mac에서는 로그인 정보가 앱과 공유되는 키체인에 저장됩니다. 이 Mac의 앱과 `echolot run`이 그것을 사용합니다.
- 다른 환경이거나 `--print`를 쓰면 Echolot이 `ECHOLOT_SECRET_…='…'` 줄로 출력합니다. 그 값을 CI 비밀 값으로 보관하고 Echolot이
  실행되는 곳에 변수를 설정하십시오. 갱신 토큰이 들어 있으므로 암호처럼 다루십시오.
- `ECHOLOT_BROWSER`는 로그인 페이지를 열 다른 명령을 지정합니다.

| 옵션 | 의미 |
| --- | --- |
| `-w`, `--workspace <folder>` | 작업 공간 폴더. 기본값은 현재 폴더입니다. |
| `--env <env>` | 서버 설정을 해석하는 변수가 있는 환경. |
| `--force` | 작동하는 로그인이 있어도 다시 로그인합니다. |
| `--print` | CI용으로 로그인 정보를 `ECHOLOT_SECRET_` 변수로 출력합니다. |
| `-v`, `--verbose` | 로그인의 각 단계를 표준 오류에 출력합니다. |

`sign-out`은 키체인에서 로그인 정보를 제거합니다. 키체인이 없으면 지울 것이 없으므로 대신 변수를 제거하십시오.

## echolot mcp serve [#echolot-mcp-serve]

```sh
echolot mcp serve [<workspace>] [--env <env>] [--policy <policy>] [--toolsets <toolsets>] [--http <port>] [--verbose] [--headless] [--trust-workspace-policy]
```

MCP를 통해 작업 공간을 에이전트에 제공합니다. 에이전트는 앱과 같은 도구로 요청을 나열, 읽기, 보내기, 실행하고, 핸들로 응답을 조회하고,
요청을 만들거나 변경할 수 있습니다. 명령이 다음과 같은 stdio 서버로 클라이언트에 추가합니다.

```sh
echolot mcp serve /path/to/Alpenglow.echolot
```

**앱이 열려 있을 때.** Echolot 앱에서 작업 공간이 열려 있고 에이전트를 허용하면(**설정 › 에이전트**) 클라이언트는 앱으로 연결됩니다.
그러면 앱이 승인이 필요한 작업에 대해 사용자에게 묻고, 에이전트가 하는 일을 볼 수 있습니다. `--headless`는 그래도 단독으로 제공합니다.

**단독 실행.** 앱이 없으면 물어볼 사람이 없으므로 정책상 묻게 되어 있는 작업은 거부됩니다.

| 정책 | 실행되는 것 |
| --- | --- |
| `standard`(기본값) | 읽기와 안전한 전송(`GET` 등). 기타 전송, 작업 공간이 모르는 호스트, 작업 공간 변경은 거부됩니다. |
| `readonly` | 읽기만. |
| `permissive` | 전송과 작업 공간 변경. 삭제는 거부되며, 작업 공간이 모르는 호스트와 보호된 환경으로의 전송도 거부됩니다. |

비밀 값은 `ECHOLOT_SECRET_` 변수와 이 Mac의 키체인에서 가져오며 에이전트에는 전달되지 않습니다. 헤드리스에서는 서버가 시작될 때
작업 공간에 있던 스크립트만 실행합니다.

**작업 공간 자체의 규칙.** `workspace.toml`의 `[agents]` 섹션은 작업 공간에서 에이전트를 끄거나, 작업 종류별로 정책을 더 엄격하게 할 수
있습니다. 정책을 느슨하게 하는 규칙은 `--trust-workspace-policy`를 쓸 때만 적용되며, 쓰지 않으면 Echolot이 무시한 규칙을 알려 줍니다.
새로운 호스트와 보호된 환경은 무조건 허용되는 일이 없습니다. 키는 [작업 공간 파일](/docs/reference/workspace-files#agents)에 있습니다.

**도구 모음.** `requests`는 항상 제공됩니다. `--toolsets`는 그룹을 쉼표로 구분해서 추가하며, `all`도 쓸 수 있습니다.

| 도구 모음 | 도구의 대상 |
| --- | --- |
| `requests` | 요청 나열, 읽기, 만들기, 보내기. 응답, 기록, GraphQL, 실행 중인 모의 서버. 항상 켜져 있습니다. |
| `flows` | 에이전트에게 제공된 플로를 실행하고, 플로가 묻는 말에 답하기. 기본적으로 켜져 있습니다. |
| `workspace` | 폴더와 요청 만들기, 이름 변경, 이동, 복제, 삭제. 폴더의 인증, 작업 공간 변수. 수집한 데이터를 파일로 저장. |
| `environments` | 환경 만들기, 변경, 삭제. |
| `specs` | OpenAPI 명세 읽기, 쓰기, 린트. 폴더를 명세에 연결하고 변경 사항 적용. |
| `mocks` | 모의 서버와 그 경로를 가짜 데이터와 함께 만들기, 변경, 삭제. 경로에서 요청 만들기. 응답을 예시로 저장. |
| `mcp-servers` | MCP 서버 추가, 변경, 확인, 삭제. |
| `history` | 지난 교환 열기, 비교, 삭제. |
| `flow-editing` | 플로 읽기, 그리기, 삭제. `try_flow`는 사용자가 승인한 뒤 플로를 한 번 실행합니다(헤드리스에서는 승인할 사람이 없으므로 거부됩니다). |

에이전트 정책, 프록시, 인증서, 인증 설정, 스크립트는 어떤 도구 모음에서도 에이전트에게 제공되지 않습니다.

**HTTP로.** `--http <port>`는 stdio 대신 127.0.0.1에서 Streamable HTTP를 제공합니다(`0`이면 빈 포트를 고릅니다). 이 Mac의 무엇이든
루프백 포트에 접근할 수 있으므로 클라이언트는 Echolot이 출력하는 Bearer 토큰을 보내야 합니다.

```sh
echolot mcp serve Alpenglow.echolot --http 0 --policy readonly
```

```text
Echolot MCP server for Alpenglow at http://127.0.0.1:52817/mcp (policy readonly)
Clients send the header  Authorization: Bearer 6f1c…
```

토큰을 직접 정하려면 `ECHOLOT_MCP_TOKEN`을 설정합니다.

| 옵션 | 의미 |
| --- | --- |
| `--env <env>` | 호출이 환경을 지정하지 않을 때 쓸 환경. |
| `--policy <policy>` | `standard`, `readonly`, `permissive`. 기본값은 `standard`입니다. |
| `--toolsets <list>` | 제공할 도구 그룹. 쉼표로 구분하며 `all`도 가능합니다. 기본값은 `requests,flows`입니다. |
| `--http <port>` | stdio 대신 127.0.0.1의 이 포트에서 Streamable HTTP를 제공합니다(`0`이면 포트를 고릅니다). |
| `-v`, `--verbose` | 모든 메시지를 표준 오류에 출력합니다. |
| `--headless` | Echolot 앱에서 이 작업 공간이 열려 있어도 단독으로 제공합니다. |
| `--trust-workspace-policy` | 작업 공간의 `[agents]` 규칙이 정책을 엄격하게 할 뿐 아니라 느슨하게도 하게 합니다. |

## echolot mcp setup [#echolot-mcp-setup]

```sh
echolot mcp setup <client> [--workspace <workspace>] [--name <name>] [--version <version>]
```

클라이언트가 작업 공간용 `echolot mcp serve`를 시작하는 데 필요한 내용을 출력합니다. 아무것도 변경하지 않으므로, 출력을 클라이언트가
읽는 위치에 복사하십시오. 출력의 명령은 실행한 `echolot`의 경로입니다.

| 클라이언트 | 출력 내용 |
| --- | --- |
| `claude-code` | 실행할 `claude mcp add --scope user …` 명령. |
| `claude-desktop` | Claude Desktop 설정용 `mcpServers` 항목. |
| `cursor` | Cursor의 `mcp.json`용 `mcpServers` 항목. |
| `vscode` | VS Code의 `mcp.json`용 `servers` 항목. |
| `codex` | Codex의 `config.toml`용 `[mcp_servers.…]` 테이블. |
| `mcpb` | `server/echolot`이 이 바이너리인 Claude Desktop 확장의 `manifest.json`. `--workspace`가 없으면 확장을 설치할 때 작업 공간을 묻습니다. |

```sh
echolot mcp setup claude-code -w Alpenglow.echolot
```

```text
claude mcp add --scope user echolot-alpenglow -- /usr/local/bin/echolot mcp serve /Users/you/Alpenglow.echolot
```

```sh
echolot mcp setup cursor -w Alpenglow.echolot
```

```json
{
  "mcpServers" : {
    "echolot-alpenglow" : {
      "args" : ["mcp", "serve", "/Users/you/Alpenglow.echolot"],
      "command" : "/usr/local/bin/echolot"
    }
  }
}
```

| 옵션 | 의미 |
| --- | --- |
| `-w`, `--workspace <folder>` | 작업 공간 폴더. 생략하면 MCPB가 묻습니다. |
| `--name <name>` | 클라이언트에서의 서버 이름. 기본값은 `echolot-<workspace>`입니다. |
| `--version <version>` | MCPB 매니페스트에 쓸 버전. 기본값은 이 도구의 버전입니다. |

앱의 **설정 › 에이전트**가 같은 클라이언트를 대신 설정해 줍니다. [에이전트](/docs/ai/agents)를 참조하십시오.

## 종료 코드 [#exit-codes]

| 코드 | 조건 |
| --- | --- |
| `0` | 연결했거나, 로그인했거나, 중지될 때까지 제공했거나, 출력했습니다. |
| `1` | `check`가 연결하지 못했거나 검사가 실패했습니다. `--quality --strict`가 문제를 발견했습니다. 또는 `sign-in`이 실패했거나 서버가 OAuth를 요구하지 않았습니다. |
| `64` | 잘못된 옵션, 알 수 없는 정책이나 클라이언트, 알 수 없는 환경, 또는 `[agents]` 섹션이 에이전트를 끈 작업 공간. |