# 외부 에이전트 (/ko/docs/ai/agents)

Echolot에는 자체 MCP 서버가 있습니다. Claude Code, Claude Desktop, Cursor, VS Code, Codex 같은 AI 클라이언트는 이 서버를 통해
저장된 요청을 나열하고, 요청을 보내고, 응답을 읽고, 검사를 추가하고, 폴더를 실행할 수 있습니다. 앱이 쓰는 도구와 같은 도구입니다.
작업 공간이 Echolot에서 열려 있는 동안 클라이언트의 호출은 앱 안에서 실행됩니다. 데이터를 변경할 수 있는 작업은 사용자가 승인하고,
모든 호출을 확인할 수 있으며, 비밀 값은 에이전트에 전달되지 않습니다.

## 작동 방식 [#how-it-works]

클라이언트는 작업 공간 경로와 함께 `echolot mcp serve`를 시작합니다. 이후의 동작은 앱의 상태에 따라 달라집니다.

- **작업 공간이 Echolot에서 열려 있고 에이전트가 켜져 있는 경우.** 명령이 앱에 연결되고 클라이언트의 호출은 작업 공간의 윈도우에서
  실행됩니다. 승인이 필요한 호출은 시트로 사용자에게 묻고, 모든 호출은 페이지 헤더의 **에이전트**에 표시됩니다.
- **그 밖의 경우**(앱이 닫혀 있거나, 작업 공간이 열려 있지 않거나, 에이전트가 꺼져 있는 경우) 명령이 작업 공간을 단독으로 제공합니다.
  물어볼 사람이 없으므로 승인이 필요한 작업은 거부됩니다. [단독 실행](#on-its-own)을 참조하십시오.

열려 있는 각 윈도우는 자신의 작업 공간을 `127.0.0.1`에서만, 시스템이 고른 포트로, 그 세션을 위해 만든 임의의 토큰을 제시하는
호출자에게만 제공합니다. 명령은 Echolot의 Application Support 폴더에 있는 비공개 파일로 윈도우를 찾습니다.
네트워크에서는 아무것도 수신 대기하지 않습니다.

## 에이전트 켜기 [#turn-agents-on]

<Steps>
<Step>
**설정 › 에이전트**를 열고 **에이전트가 열린 작업 공간을 사용하도록 허용**을 켭니다. 켜기 전에는 꺼져 있습니다. 같은 스위치가
작업 공간 윈도우의 페이지 헤더에 있는 **에이전트** 팝오버에도 있습니다.
</Step>
<Step>
Echolot에서 작업 공간을 엽니다. 윈도우가 작업 공간을 제공하는 동안 페이지 헤더의 **에이전트** 옆에 있는 점이 녹색으로 바뀝니다.
클라이언트가 연결되어 있으면 그 수가 표시됩니다.
</Step>
<Step>
아래 설명대로 클라이언트를 연결합니다. 작업 공간과 클라이언트마다 한 번만 하면 됩니다.
</Step>
</Steps>

작업 공간 스스로 에이전트를 끌 수도 있습니다. **작업 공간 설정 › 에이전트 › 에이전트의 이 작업 공간 사용 허용**을 끄면 앱을 통하든
단독으로 실행하든 클라이언트는 이 작업 공간에서 아무것도 얻지 못합니다.

## 클라이언트 연결 [#connect-a-client]

페이지 헤더에서 **에이전트**를 클릭합니다. **클라이언트 연결** 아래에 클라이언트마다 버튼이 있습니다.

<Shot id="ai-agents-popover" alt="페이지 헤더의 에이전트 팝오버. 에이전트를 허용하는 스위치, 연결된 클라이언트, 최근 호출, 클라이언트 연결 버튼이 보입니다" />

| 클라이언트 | 버튼 | 동작 |
| --- | --- | --- |
| **Claude Desktop** | **Claude에 추가** | 이 작업 공간용 Claude Desktop 확장을 만들어 Claude Desktop에서 엽니다. Claude Desktop이 확인을 요청합니다. 직접 다운로드 버전에서만 사용할 수 있습니다. |
| **Claude Code** | **명령어 복사** | `claude mcp add` 명령어를 복사합니다. 터미널에 붙여넣습니다. |
| **Cursor** | **Cursor에 추가** | MCP 서버를 설치하는 Cursor의 안내를 엽니다. |
| **VS Code** | **VS Code에 추가** | MCP 서버를 설치하는 VS Code의 안내를 엽니다. |
| **Codex** | **config.toml 항목 복사** | Codex의 `config.toml`에 붙여넣을 항목을 복사합니다. |
| **기타** | **JSON 복사** | 대부분의 MCP 클라이언트가 읽는 형식인 `mcpServers` 항목을 복사합니다. |

그 아래에는 명령 자체와 **복사**가 있어, 명령과 인수를 요구하는 어떤 클라이언트에도 쓸 수 있습니다.

클라이언트에서 서버 이름은 `echolot-`에 작업 공간 이름을 붙인 것입니다. Alpenglow 작업 공간의 Claude Code 명령은 다음과 같습니다
(`echolot`의 경로는 앱 안에 있는 도구입니다).

```sh
claude mcp add --scope user echolot-alpenglow -- /Applications/Echolot.app/Contents/Helpers/echolot mcp serve ~/Alpenglow.echolot
```

Codex 항목은 다음과 같습니다.

```toml
[mcp_servers.echolot-alpenglow]
command = "/Applications/Echolot.app/Contents/Helpers/echolot"
args = ["mcp", "serve", "/Users/you/Alpenglow.echolot"]
```

터미널에서 `echolot mcp setup <client> -w <workspace>`를 실행하면 `claude-code`, `claude-desktop`, `cursor`, `vscode`,
`codex`에 대해 같은 설정을 출력합니다. [`echolot mcp`](/docs/cli/mcp)를 참조하십시오.

<Edition only="appstore">
  App Store 버전에는 앱 안에 명령줄 도구가 없고 Claude Desktop 확장도 없습니다. 명령줄 도구는 따로 설치합니다(설정 › 에이전트와
  에이전트 팝오버의 **명령줄 도구 받기**에서 다운로드로 이동합니다). 클라이언트가 이 도구를 실행하며, 작업 공간이 Echolot에서 열려 있는
  동안에는 클라이언트의 호출이 여전히 앱 안에서 실행됩니다. 버튼은 명령이나 스니펫을 복사하거나 클라이언트의 설치 안내를 열 뿐,
  다른 앱의 폴더에는 아무것도 쓰지 않습니다.
</Edition>

### 한 번의 클릭으로 Claude Desktop 연결 [#claude-desktop-in-one-click]

<Edition only="direct">
  Claude Desktop 확장(`.mcpb`)에는 명령줄 도구가 들어 있으므로 직접 다운로드 버전에서만 사용할 수 있습니다.
</Edition>

**설정 › 에이전트 › Claude Desktop**에 최근 작업 공간이 나열됩니다. 작업 공간 옆의 **Claude에 추가**를 누르면 에이전트를 켜고,
그 작업 공간용 확장을 만들어 Claude Desktop에 전달하며, Claude Desktop이 확인을 요청합니다. Claude Desktop이 확장을 받으면 행에
**추가됨**이라고 표시됩니다. 나중에 확장을 업데이트하려면 Control 키를 누른 채 **추가됨**을 클릭하고 **다시 추가**를 선택합니다.

Claude Desktop이 설치되어 있지 않으면 이 섹션에 **Claude Desktop 받기** 링크와 함께 그 사실이 표시되고, **Claude에 추가**는 확장을
Finder에서 보여 줍니다.

## 도구 모음 [#toolsets]

에이전트에게 보이는 도구는 모두 그 컨텍스트의 공간을 차지하므로 Echolot은 도구를 그룹으로 나누어 제공합니다. **설정 › 에이전트 ›
에이전트용 도구**에서 선택합니다. **요청**은 항상 켜져 있으며, **요청**과 **플로**는 바꾸기 전까지 켜져 있습니다. 이 체크 상자는
에이전트에게 보이는 도구를 정할 뿐, 묻지 않고 할 수 있는 일을 정하지 않습니다. 모든 도구는 데이터를 변경하거나 새로운 호스트에
접근하기 전에 여전히 묻습니다. 내장 어시스턴트가 무엇을 묻는지는 **설정 › 어시스턴트 › 사전 확인**에서 정합니다.

| 도구 모음 | 에이전트가 할 수 있는 일 |
| --- | --- |
| **요청** | 요청 나열, 읽기, 만들기, 보내기. 응답, 기록, GraphQL, 실행 중인 모의 서버 |
| **플로** | 에이전트에게 제공된 플로를 실행하고, 플로가 묻는 말에 답하기 |
| **작업 공간** | 폴더와 요청 만들기, 이름 변경, 이동, 복제, 삭제. 폴더의 인증, 작업 공간 변수. 수집한 데이터를 파일로 저장 |
| **환경** | 환경 만들기, 변경, 삭제 |
| **명세** | OpenAPI 명세 읽기, 쓰기, 린트. 폴더를 명세에 연결하고 변경 사항 적용 |
| **모의 서버** | 모의 서버와 그 경로를 가짜 데이터와 함께 만들기, 변경, 삭제. 경로에서 요청 만들기. 응답을 예시로 저장 |
| **MCP 서버** | MCP 서버 추가, 변경, 확인, 삭제 |
| **기록** | 지난 교환 열기, 비교, 삭제 |
| **플로 편집** | 플로 읽기, 그리기, 삭제. 사용자가 승인하면 플로를 한 번 시험 실행 |

기본 도구 모음에서 에이전트는 요청을 나열, 읽기, 만들기, 업데이트, 보내기, 검사와 함께 폴더 실행하기, 응답을 조각별로 읽기, 기록 보기,
GraphQL 쿼리 확인, 요청을 cURL이나 코드로 복사, 가져오기, 명세 린트, 모의 서버 시작과 중지, 에이전트에게 제공된 플로 실행 같은 도구를
받습니다. 프롬프트도 `debug_request`와 `write_tests` 두 개를 받습니다.

도구 모음을 바꾸면 열려 있는 윈도우는 새 구성으로 다시 제공을 시작합니다. 새 구성을 적용하려면 클라이언트를 다시 연결하십시오.

**제공되지 않는 것**은 어떤 도구 모음에서도 제공되지 않습니다. 에이전트 규칙, 프록시, 인증서, 작업 공간의 인증, 인증을 넘어선
폴더 설정, 스크립트(요청, 폴더, 모의 서버 스크립트), 비밀 값으로 가져오거나 서명하는 인증(OAuth 2.0, AWS, JWT 등)의 변경입니다.
이 항목은 사용자만 다룰 수 있습니다.

에이전트는 요청과 폴더에 **bearer**, **basic**, **API 키** 인증을 지정할 수 있고, 요청이 응답의 값을 보관하게 할 수도 있습니다
(로그인의 토큰을 그 뒤의 요청에서 쓰는 경우). `create_request`와 `update_request`는 `auth`와 `captures`를 받고,
`save_folder_auth`는 폴더의 요청이 상속하는 인증을 설정합니다. 자격 증명은 `{{variables}}`여야 합니다. 에이전트가 비밀번호나 토큰을
직접 쓰면 거부되므로 자격 증명이 파일에 남지 않습니다. 이름이 자격 증명처럼 보이는(token, password, key…) 캡처 값은 비밀 값으로
보관됩니다.

에이전트는 자신에게 제공된 플로(플로 목록에서 반짝이 표시가 붙은 것)를 전용 도구로 시작하며, 플로의 현재 상태에 대한 사용자의 승인을
거칩니다. [플로 실행](/docs/flows/running-and-triggers)을 참조하십시오. **플로 편집**을 켜면 `try_flow`가 에이전트가 그리고 있는
플로를 포함해 다른 플로를 한 번 실행합니다. 이때 플로가 보내고, 저장하고, 실행하는 내용을 볼 수 있으며, 규칙과 관계없이 그 실행을
매번 승인하게 됩니다. **이 세션 동안 허용**은 플로의 그 버전에만 적용됩니다.

## 에이전트가 하는 일 보기 [#see-what-agents-do]

윈도우가 작업 공간을 제공하는 동안, 페이지 헤더의 **에이전트** 팝오버에는 다음이 표시됩니다.

- 호출한 각 클라이언트와 그 호출 횟수, 실패 횟수, 마지막으로 확인된 시각. 클라이언트의 스위치를 끄면 이후 그 클라이언트의 호출과
  대기 중인 승인이 거부됩니다.
- **최근 호출**: 최근 호출의 도구, 클라이언트, 시각, 소요 시간, 오류.

클라이언트가 호출하기 전에는 <strong>아직 이 작업 공간을 사용한 에이전트가 없습니다.</strong>라고 표시됩니다. 에이전트가 꺼져 있으면 클라이언트가
사용자의 승인 없이 단독으로 계속 작동한다고 안내합니다.

에이전트가 보내는 모든 요청은 클라이언트 이름과 함께 작업 공간의 [기록](/docs/workspaces/history)에도 남습니다.

## 승인 [#approvals]

클라이언트가 규칙상 묻게 되어 있는 작업을 하려고 하면 작업 공간의 윈도우에 시트가 나타납니다. ***클라이언트*에서 *데이터를 변경할 수
있는 요청을 보내려고 합니다***라는 문구와 함께, 비밀 값을 가린 상태로 실제 전송될 요청이 표시됩니다. **한 번 허용**, **이 세션 동안
허용**(윈도우가 닫힐 때까지 같은 호출을 묻지 않고 실행), **거부** 중에서 선택합니다. 5분 안에 답하지 않은 질문은 거부됩니다.
이 시트는 [어시스턴트](/docs/ai/assistant#approve-what-changes)가 쓰는 시트와 같습니다.

작업 공간 규칙이 없을 때 묻는 항목은 다음과 같습니다.

| 작업 | 기본값 |
| --- | --- |
| **요청 및 환경 읽기** | 허용 |
| **안전한 전송(GET, GraphQL 쿼리, MCP 읽기)** | 허용 |
| **기타 전송** | 묻기 |
| **보호된 환경으로 전송** | 묻기(항상) |
| **새로운 호스트로 전송** | 묻기(항상) |
| **작업 공간 변경** | 묻기 |
| **삭제** | 묻기 |

새로운 호스트는 윈도우가 제공을 시작할 때 작업 공간의 어떤 요청이나 환경도 사용하지 않던 호스트입니다. 에이전트가 읽은 데이터가
그 호스트로 나갈 수 있으므로 항상 묻습니다. [보호된 환경](/docs/workspaces/protected-environments)으로 보내는 경우도 마찬가지입니다.

## 작업 공간 규칙 [#workspace-rules]

**작업 공간 설정 › 에이전트**(사이드바 아래쪽의 작업 공간 메뉴에서 **작업 공간 설정…**)에서 이 작업 공간의 규칙을 정합니다.
규칙은 `workspace.toml`에 저장되므로 Git을 통해 작업 공간과 함께 이동하며, 외부 에이전트와 어시스턴트 모두에 적용됩니다.

<Shot id="ai-agents-workspace-rules" alt="작업 공간 설정의 에이전트 탭. 에이전트 스위치, 작업별 규칙, 호스트 및 제한 필드가 보입니다" />

- **에이전트의 이 작업 공간 사용 허용**: 끄면 에이전트는 이 작업 공간에서 아무것도 얻지 못합니다.
- **에이전트가 할 수 있는 작업**: 위 표의 작업마다 규칙 하나를 정합니다. **기본값**(기본값이 무엇인지 함께 표시), **허용**, **묻기**,
  **거부** 중에서 고릅니다. 보호된 환경과 새로운 호스트로의 전송은 **묻기**나 **거부**만 선택할 수 있습니다.
- **호스트 및 제한**:
  - **허용된 호스트**: 에이전트가 보낼 수 있는 호스트. 쉼표나 공백으로 구분합니다.
  - **세션당 전송 횟수**: 에이전트가 한 세션에서 보낼 수 있는 최대 전송 횟수. 비워 두면 제한이 없습니다.
  - **분당 전송 횟수**: 에이전트가 1분 동안 보낼 수 있는 최대 전송 횟수. 비워 두면 제한이 없습니다.

더 엄격한 규칙은 항상 적용됩니다. 파일과 함께 들어온(Git으로 팀원에게서 받은) 더 느슨한 규칙은 사용자가 신뢰하기 전까지 사용자의 Mac에서
적용되지 않습니다. 그때까지 에이전트 팝오버에는 작업 공간의 규칙이 묻지 않고 허용하게 될 작업이 표시되고, 에이전트는 계속 묻습니다.
**이 규칙 신뢰**를 선택하면 규칙을 받아들입니다. 작업 공간 설정에서 직접 정한 규칙은 신뢰된 것으로 취급합니다.

## 에이전트가 절대 얻지 못하는 것 [#what-agents-never-get]

- **비밀 값.** Echolot은 에이전트가 받는 모든 내용(오류 포함)에서 모든 비밀 값을 일반 텍스트, JSON, URL 인코딩, Base64 형태로
  치환합니다. 에이전트는 비밀 변수를 이름으로만 볼 수 있습니다.
- **기록의 자격 증명.** 지난 교환은 자격 증명 헤더를 가리고 통신 캡처를 제외한 채 에이전트에 전달됩니다.
- **다른 호스트에서의 비밀 값.** 에이전트가 보낸 요청이 작업 공간에서 사용하지 않는 호스트로 리디렉션되면, 그 과정에서 자격 증명
  헤더가 제거됩니다.

## 단독 실행 [#on-its-own]

앱에서 작업 공간이 열려 있지 않거나 `--headless`를 쓰면 `echolot mcp serve`가 작업 공간을 직접 제공하고 정책이 단독으로
결정합니다.

| `--policy` | 실행되는 것 | 거부되는 것 |
| --- | --- | --- |
| `standard`(기본값) | 읽기와 안전한 전송 | 기타 전송, 변경, 삭제, 보호된 환경, 새로운 호스트 |
| `readonly` | 읽기 | 모든 전송, 변경, 삭제 |
| `permissive` | 읽기, 모든 전송, 변경 | 삭제, 보호된 환경, 새로운 호스트 |

비밀 값은 이 Mac의 키체인과 `ECHOLOT_SECRET_…` 변수에서 가져오며 에이전트에는 전달되지 않습니다. `--toolsets`는 그룹을 고르고
(`all`은 모든 그룹), `--env`는 호출이 환경을 지정하지 않을 때 쓸 환경을 고르며, `--http 0`은 표준 입출력 대신 토큰을 사용하는
Streamable HTTP를 `127.0.0.1`에서 제공합니다. 작업 공간 자체의 규칙은 정책을 더 엄격하게 하며, `--trust-workspace-policy`를
쓰면 정책을 느슨하게도 할 수 있습니다. [`echolot mcp`](/docs/cli/mcp)를 참조하십시오.

```sh
echolot mcp serve ~/Alpenglow.echolot --policy readonly --toolsets requests,history
```

## 문제 해결 [#troubleshooting]

- **클라이언트가 연결되지만 아무것도 묻지 않고 변경이 거부됩니다.** 명령이 단독으로 제공 중입니다. Echolot에서 작업 공간을 열고
  **설정 › 에이전트 › 에이전트가 열린 작업 공간을 사용하도록 허용**을 켠 다음 클라이언트를 다시 연결하십시오.
- **클라이언트가 도구를 전혀 받지 못합니다.** 작업 공간 설정 › 에이전트에서 **에이전트의 이 작업 공간 사용 허용**이 꺼져 있거나,
  에이전트 팝오버에서 클라이언트의 스위치를 껐기 때문입니다.
- **에이전트에 필요한 도구가 없습니다.** **설정 › 에이전트 › 에이전트용 도구**에서 해당 도구 모음을 켜고 클라이언트를 다시
  연결하십시오.
- **Claude에 추가가 흐리게 표시됩니다.** 이 빌드에는 앱 안에 명령줄 도구가 없습니다. echolot.dev의 릴리스에는 들어 있습니다.