@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ko-KR/mcp-clients.md

@@ -0,0 +1,330 @@
+---
+title: "MCP 클라이언트"
+description: "에이전트 네이티브 앱을 로컬 MCP 서버(claude-in-chrome, 파일 시스템, 극작가 등)에 연결하면 에이전트가 도구를 얻을 수 있습니다."
+---
+
+# MCP 클라이언트
+
+**이 페이지: 상담원에게 더 많은 도구를 제공하세요.** MCP 서버(로컬 또는 원격)에 상담원 기본 앱을 지정하면 해당 도구가 상담원 채팅에 표시됩니다. 이는 _클라이언트_ 방향, 즉 [MCP Protocol](/docs/mcp-protocol)의 미러 이미지입니다(앱을 MCP *서버*로 만듭니다).
+
+| 원한다면...                                             | 읽기                                     |
+| ------------------------------------------------------- | ---------------------------------------- |
+| 외부 에이전트/호스트를 앱에 연결                        | [External Agents](/docs/external-agents) |
+| 에이전트에게 더 많은 도구 제공(다른 MCP 서버 사용)      | **이 페이지** — MCP 클라이언트           |
+| Claude/ChatGPT에서 렌더링되는 인라인 UI 빌드            | [MCP Apps](/docs/mcp-apps)               |
+| 하위 수준 MCP 서버 참조(인증, 도구, 사용자 정의 마운트) | [MCP Protocol](/docs/mcp-protocol)       |
+
+하나의 구성 파일을 사용하면 작업 영역의 모든 에이전트 기반 앱이 컴퓨터의 MCP 서버에서 제공하는 도구(브라우저 자동화용 `claude-in-chrome`, 파일 읽기용 `@modelcontextprotocol/server-filesystem`, 브라우저 테스트용 `@playwright/mcp` 및 MCP를 말하는 기타 모든 도구)에 액세스할 수 있습니다.
+
+구성 파일을 편집하지 않고도 개별 사용자 또는 전체 조직인 [connect remote (HTTP) MCP servers at runtime](#remote-via-ui)를 사용할 수도 있습니다.
+
+모든 소스는 하나의 런타임 **MCP 관리자**로 확인되며, 학습한 모든 도구는 `tool-search`를 통해 의도로 검색 가능한 충돌 방지 `mcp__<server-id>__<tool>` 접두사 아래 에이전트의 도구 레지스트리에 저장됩니다.
+
+```an-diagram title="Client direction: many sources, one tool registry" summary="Config files, env, and runtime UI all merge into the MCP manager; its tools appear prefixed and tool-searchable alongside your app's actions. This is the mirror of the server direction."
+{
+  "html": "<div class=\"mcp-merge\"><div class=\"diagram-col sources\"><div class=\"diagram-box\" data-rough>Workspace <code>mcp.config.json</code><br><small class=\"diagram-muted\">shared across apps</small></div><div class=\"diagram-box\" data-rough>App-root <code>mcp.config.json</code><br><small class=\"diagram-muted\">per-app override</small></div><div class=\"diagram-box\" data-rough><code>MCP_SERVERS</code> env<br><small class=\"diagram-muted\">CI / production</small></div><div class=\"diagram-box\" data-rough>Remote via settings UI<br><small class=\"diagram-muted\">personal &amp; org scope</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">MCP manager</span><small class=\"diagram-muted\">merge &middot; hot-reload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col out\"><div class=\"diagram-node\">Agent tool registry<br><small class=\"diagram-muted\"><code>mcp__&lt;server-id&gt;__&lt;tool&gt;</code></small></div><div class=\"diagram-node\"><code>tool-search</code><br><small class=\"diagram-muted\">discover by intent</small></div></div></div>",
+  "css": ".mcp-merge{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mcp-merge .diagram-col{display:flex;flex-direction:column;gap:8px}.mcp-merge .center{display:flex;flex-direction:column;align-items:center;gap:4px}.mcp-merge .diagram-arrow{font-size:22px;line-height:1}.mcp-merge code{font-size:.85em}"
+}
+```
+
+> _your_ 앱을 다른 호스트가 사용하는 MCP 서버로 만드는 반대 방향은 [MCP Protocol](/docs/mcp-protocol) 및 [External Agents](/docs/external-agents)에 있습니다.
+
+## 내장 브라우저 및 컴퓨터 사용 기능 {#built-in-capabilities}
+
+에이전트 네이티브에는 일반적인 stdio MCP 서버에 대한 로컬 개발 토글이 포함되어 있습니다.
+기본적으로 꺼져 있으며 사용자 또는 조직별로만 활성화할 수 있습니다.
+앱이 로컬에서 실행 중일 때. 프로덕션 및 호스팅된 서버리스 런타임 건너뛰기
+이전 설정 행이 존재하더라도 이러한 내장 기능과 작업 공간 리소스
+트리에는 기본 `mcp-servers/*.json` 리소스로 표시되지 않습니다.
+
+| 능력             | 서버 ID           | 명령                                                                    |
+| ---------------- | ----------------- | ----------------------------------------------------------------------- |
+| 크롬 개발자 도구 | `chrome-devtools` | `npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics` |
+| 극작가 브라우저  | `playwright`      | `npx -y @playwright/mcp@latest`                                         |
+| 컴퓨터 사용      | `computer-use`    | `npx -y computer-use-mcp@latest`                                        |
+
+한 범위에서는 한 번에 하나의 브라우저 기능만 활성화할 수 있습니다. Chrome DevTools를 활성화하면 동일한 사용자 또는 조직에 대해 Playwright가 비활성화되고, Playwright를 활성화하면 Chrome DevTools가 비활성화됩니다.
+
+컴퓨터 사용은 macOS에서만 가능합니다. 다른 플랫폼에서는 사용할 수 없는 것으로 나열되며 이전 설정 행에 포함되어 있어도 건너뜁니다.
+
+Chrome DevTools는 기본적으로 `--autoConnect`를 사용합니다. 이는 실행 중인 적격한 Chrome 인스턴스에 연결됩니다. 격리된 브라우저 프로필을 생성하거나 사용자의 일반 프로필에 로그인하지 않습니다. 원격 디버깅이 활성화된 Chrome 144 이상이 필요합니다. 나중에 배포에 특정 디버깅 엔드포인트가 필요할 때 수동 `browser-url` 구성을 추가할 수 있습니다.
+
+기본 제공은 개인 토글의 경우 `u:<email>:mcp-builtin-capabilities` 아래, 팀 토글의 경우 `o:<orgId>:mcp-builtin-capabilities` 아래 프레임워크의 `settings` 테이블에 유지됩니다. 활성화되면 원격 서버와 동일한 범위 지정 가시성 형식(예: `mcp__user_<emailhash>_playwright__*` 또는 `mcp__org_<orgId>_chrome-devtools__*`)을 사용하여 런타임 MCP 관리자에 병합됩니다.
+
+### 사용자 표시 설정 참고사항
+
+민감한 내장 기능에는 간결하고 명시적인 설정 사본을 사용하세요.
+
+- **Chrome DevTools**는 실행 중인 Chrome 디버깅 대상에 연결됩니다. 사용자에게 알리기
+  브라우저 테스트 및 로그인 확인을 위한 것이며
+  도구가 나타나기 전에 Chrome 원격 디버깅을 활성화해야 할 수도 있습니다.
+- **Playwright**는 격리된 브라우저를 시작합니다. 결정론적 용도로 권장
+  사용자의 실시간 Chrome 프로필이 필요하지 않은 경우 QA
+- **컴퓨터 사용**으로 로컬 앱을 작동할 수 있습니다. 기본적으로 사용 중지 상태로 유지하세요.
+  macOS 화면 녹화 및 접근성 프롬프트, 촬영 전 물어보기
+  구매, 금전적 변경, 계정 변경 등 민감한 actions
+
+### 내장 엔드포인트
+
+| 방법 | 경로                         | 목적                                                                                |
+| ---- | ---------------------------- | ----------------------------------------------------------------------------------- |
+| GET  | `/_agent-native/mcp/builtin` | 내장된 기능, 활성화된 범위, 병합된 ID 및 실시간 상태를 나열합니다.                  |
+| POST | `/_agent-native/mcp/builtin` | 범위를 업데이트합니다. 본문: `{ scope, enabledIds }` 또는 `{ scope, id, enabled }`. |
+
+## 로컬 MCP 서버 추가 {#adding-a-server}
+
+작업 공간 루트(또는 개별 앱 루트 - 둘 다 존재할 경우 작업 공간 루트가 우선)에서 `mcp.config.json`를 만듭니다.
+
+```jsonc
+{
+  "$schema": "https://agent-native.com/schema/mcp.config.json",
+  "servers": {
+    "claude-in-chrome": {
+      "command": "claude-in-chrome-mcp",
+      "args": [],
+      "env": { "LOG_LEVEL": "info" },
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem@latest",
+        "/Users/me/projects",
+      ],
+    },
+  },
+}
+```
+
+모양은 작습니다. 서버 ID로 키가 지정된 `servers` 맵입니다. 여기서 각 항목은 stdio 실행기(`command` + `args` + 선택적 `env`) 또는 원격 `{ "type": "http", "url", "headers" }` 항목입니다.
+
+```an-annotated-code title="mcp.config.json, annotated"
+{
+  "filename": "mcp.config.json",
+  "language": "jsonc",
+  "code": "{\n  \"$schema\": \"https://agent-native.com/schema/mcp.config.json\",\n  \"servers\": {\n    \"claude-in-chrome\": {\n      \"command\": \"claude-in-chrome-mcp\",\n      \"args\": [],\n      \"env\": { \"LOG_LEVEL\": \"info\" }\n    },\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem@latest\", \"/Users/me/projects\"]\n    }\n  }\n}",
+  "annotations": [
+    { "lines": "3", "label": "Server id", "note": "The key becomes the tool prefix: this server's tools surface as `mcp__claude-in-chrome__*` in the agent's registry, so they can't collide with your template's actions." },
+    { "lines": "4-6", "label": "stdio launcher", "note": "`command` + `args` spawn a local binary. Stdio servers are intended for **local development** — they are a no-op in edge runtimes." },
+    { "lines": "6", "label": "Process env", "note": "Optional `env` is passed to the spawned process. Keep secrets out of committed config; prefer `MCP_SERVERS` or the settings UI for tokens." }
+  ]
+}
+```
+
+다음에 앱을 시작하면 다음이 표시됩니다.
+
+```
+[mcp-client] loaded config from /path/to/mcp.config.json (3 server(s))
+[mcp-client] connected to claude-in-chrome: 12 tools
+[mcp-client] connected to playwright: 9 tools
+[mcp-client] connected to filesystem: 4 tools
+```
+
+도구는 접두사 `mcp__<server-id>__<tool-name>`를 사용하여 에이전트의 도구 레지스트리에 등록되므로 템플릿의 actions와 충돌할 수 없습니다. `tool-search`에도 포함되어 있으므로 에이전트는 정확한 접두사가 붙은 이름을 미리 입력할 필요 없이 새로 연결된 MCP 기능을 의도적으로 검색할 수 있습니다.
+
+## 구성 우선순위 {#precedence}
+
+MCP 구성은 다음 순서로 해결되며 첫 번째 일치 항목이 승리합니다.
+
+1. **작업공간 루트 `mcp.config.json`** — `package.json`의 `agent-native.workspaceCore`를 통해 감지됩니다. 작업 공간의 모든 앱에서 공유됩니다.
+2. **App-root `mcp.config.json`** — 모든 앱에서 MCP 서버를 사용하지 않으려는 경우 앱별 재정의
+3. **`MCP_SERVERS` env var** — 파일이 의미가 없는 CI/프로덕션의 경우 동일한 모양의 JSON 문자열입니다.
+
+## 프로덕션 배포: `MCP_SERVERS` {#mcp-servers-env}
+
+프로덕션 배포의 경우 원격 HTTP MCP 서버를 선호하고 전체 구성을 설정하세요.
+환경 변수로서의 모양(또는 내부 서버 맵):
+
+```bash
+MCP_SERVERS='{"servers":{"zapier":{"type":"http","url":"https://mcp.example.com/mcp","headers":{"Authorization":"Bearer paste-token-value-here"}}}}'
+```
+
+`MCP_SERVERS`는 JSON로 구문 분석되므로 `${...}` 자리 표시자는 확장되지 않습니다.
+문자열 내부. 토큰을 다른 보안 비밀에 저장하는 경우 먼저 확장하십시오.
+최종 JSON 값을 작성합니다.
+
+Stdio MCP 서버는 로컬 바이너리를 생성하며 로컬 개발을 위한 것입니다.
+MCP 도구는 노드 런타임(Cloudflare 작업자 및 기타 에지)에서만 활성화됩니다.
+대상은 자동으로 MCP를 건너뛰고 나머지 앱 작업을 계속합니다.
+보통.
+
+## 자동 감지: `claude-in-chrome` {#autodetect}
+
+`mcp.config.json`가 **아니요** 있고 `claude-in-chrome-mcp` 바이너리가 `PATH`(또는 잘 알려진 설치 위치 `~/.claude-in-chrome/bin/claude-in-chrome-mcp`)에 있는 경우 에이전트 네이티브는 이를 기본 MCP 서버로 자동 등록합니다. 선택 해제하려면 `AGENT_NATIVE_DISABLE_MCP_AUTODETECT=1`를 설정하세요.
+
+즉, clude-in-chrome 확장 프로그램을 설치한 사용자는 구성 변경 없이 자신이 여는 모든 에이전트 기반 앱에서 브라우저 제어권을 갖게 됩니다.
+
+## UI 설정을 통한 원격 MCP 서버 {#remote-via-ui}
+
+MCP(모델 컨텍스트 프로토콜) 서버는 에이전트에 Zapier, Cloudflare, Composio 또는 회사 내부 도구에 연결하는 것과 같은 새로운 기능을 제공합니다. 일단 연결되면 에이전트는 내장된 도구와 마찬가지로 해당 도구를 사용할 수 있습니다.
+
+### 원격 MCP 서버 연결 방법
+
+1. **서버 이름** — 참조용 짧은 라벨(예: "zapier", "slack-tools").
+2. **URL** — MCP 서버 공급자가 제공한 HTTPS 엔드포인트(예: `https://mcp.zapier.com/s/abc123/mcp`). 이는 일반적으로 제공업체의 대시보드 또는 통합 문서에서 찾을 수 있습니다.
+3. **설명** (선택 사항) — 이 서버의 기능에 대한 참고 사항
+4. **헤더** — 서버에서 요구하는 인증 자격 증명(한 줄에 하나씩). 대부분의 서버에는 `Authorization` 헤더가 필요합니다. 예: `Authorization: Bearer sk-your-key-here`. 여기에 무엇을 입력할지 제공업체의 문서를 참조하세요.
+
+**테스트**를 클릭하여 저장하기 전에 연결을 확인하세요. 성공하면 사용 가능한 도구 수가 표시됩니다. **연결**을 클릭하여 추가하세요.
+
+### 개인 및 조직 범위
+
+두 가지 범위가 지원됩니다:
+
+- **개인** — 로그인한 사용자만 도구를 얻을 수 있습니다. 사용자 범위 설정으로 저장됩니다.
+- **팀** — 활동 중인 조직의 모든 사람이 도구를 받습니다. 소유자와 관리자가 추가할 수 있습니다. 구성원은 목록을 읽기 전용으로 볼 수 있습니다. 조직 범위 설정으로 저장됩니다.
+
+실행 중인 MCP 관리자에 핫 리로드를 추가 및 제거합니다. 프로세스를 다시 시작하지 않고 서버를 다시 시작하지 않습니다. 새로운 `mcp__<scope>-<name>__*` 도구는 다음 메시지에서 상담원에게 나타나며 `tool-search`를 통해 검색할 수 있습니다.
+
+HTTPS URL는 모든 곳에서 허용됩니다. 일반 `http://`는 개발 중에 `localhost`에만 허용됩니다. 선택적 인증은 모든 요청에서 `Authorization: Bearer …`를 통해 전송되는 Bearer 토큰으로 들어갑니다.
+
+내부적으로 이러한 서버는 `u:<email>:mcp-servers-remote`(개인) 또는 `o:<orgId>:mcp-servers-remote`(팀) 키 아래 프레임워크의 `settings` 테이블에 유지되며 시작 시 `mcp.config.json`와 병합됩니다.
+
+### HTTP 엔드포인트
+
+| 방법   | 경로                                                  | 목적                                                                     |
+| ------ | ----------------------------------------------------- | ------------------------------------------------------------------------ |
+| GET    | `/_agent-native/mcp/servers`                          | 현재 사용자의 개인 + 조직 서버를 실시간 상태로 나열합니다.               |
+| POST   | `/_agent-native/mcp/servers`                          | 서버를 추가합니다. 본문: `{ scope, name, url, headers?, description? }`. |
+| DELETE | `/_agent-native/mcp/servers/:id?scope=user\|org`      | Remove a server and reconfigure the manager.                             |
+| POST   | `/_agent-native/mcp/servers/:id/test?scope=user\|org` | Dry-run the existing server's connect + list-tools.                      |
+| POST   | `/_agent-native/mcp/servers/test`                     | 지속하기 전에 임의의 URL를 시험 실행하세요. 본문: `{ url, headers? }`.   |
+
+Stdio 서버는 여전히 노드 런타임 외부에서는 작동하지 않지만 원격 HTTP MCP 서버는 데스크톱 프로덕션 빌드를 포함하여 `fetch`가 있는 모든 환경에서 작동합니다.
+
+## 허브를 통한 공유 MCP 서버 {#hub}
+
+작업 영역에서 여러 에이전트 기본 앱(예: 발송 + 메일 + 클립)을 실행하는 경우 **한 앱**을 허브로 구성하고 나머지 앱은 조직 범위 MCP 서버를 자동으로 가져오도록 할 수 있습니다. URL 및 전달자 토큰을 앱별로 복사하여 붙여넣을 수 없습니다. Dispatch 작업 공간 MCP 리소스를 사용하는 표준 접근 방식은 [Multi-App Workspace](/docs/multi-app-workspace)를 참조하세요.
+
+Dispatch는 기존의 허브로 이미 앱 전체를 조정하고 있습니다.
+
+```an-diagram title="Hub model: one app serves org-scope MCP servers" summary="Dispatch holds the org-scope MCP servers; consumer apps pull and merge them as mcp__hub_<orgId>_<name>__*. Only org-scope rows are shared — personal credentials stay put."
+{
+  "html": "<div class=\"mcp-hub\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Dispatch hub</span><small class=\"diagram-muted\">org-scope MCP servers</small><small class=\"diagram-muted\"><code>GET /mcp/hub/servers</code></small></div><div class=\"diagram-col arrows\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div></div><div class=\"diagram-col consumers\"><div class=\"diagram-box\" data-rough>Mail<br><small class=\"diagram-muted\"><code>mcp__hub_&lt;orgId&gt;_&lt;name&gt;__*</code></small></div><div class=\"diagram-box\" data-rough>Clips<br><small class=\"diagram-muted\">pull + merge each ~60s</small></div></div></div><p class=\"diagram-muted note\">Bearer-gated by <code>AGENT_NATIVE_MCP_HUB_TOKEN</code>. Personal (user-scope) servers are never re-exposed.</p>",
+  "css": ".mcp-hub{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mcp-hub .center{display:flex;flex-direction:column;align-items:center;gap:4px}.mcp-hub .diagram-col{display:flex;flex-direction:column;gap:10px}.mcp-hub .arrows .diagram-arrow{font-size:22px;line-height:1}.mcp-hub .note{margin:8px 0 0;font-size:.85em}.mcp-hub code{font-size:.85em}"
+}
+```
+
+새 작업 공간 설정의 경우 **작업 공간 MCP 리소스 발송**을 선호하세요
+작업 공간 skills에서 사용되는 동일한 모든 앱과 선택된 앱 부여 모델을 원합니다.
+지침 및 참조 자료. 다음을 사용하여 작업공간 리소스를 추가하세요:
+
+```json
+{
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
+  },
+  "description": "Shared MCP tools for workspace apps"
+}
+```
+
+`mcp-server` 종류를 사용하여 `mcp-servers/<name>.json` 아래에 저장합니다. 모든 앱
+리소스는 모든 작업 공간 앱에서 로드됩니다. 선택한 리소스는
+활성 파견 보조금이 있는 앱. 비밀 자리 표시자는 앱에서 해결됩니다.
+비밀 저장소이므로 원시 전달자 토큰을 Dispatch Vault에 넣고 참조
+리소스 본문에 저장하는 대신 `${keys.NAME}`를 사용하세요.
+
+앱은 병합된 MCP 구성을 약 1분에 한 번씩 새로 고치므로 중앙 리소스
+편집, 변경 부여, 제거는 배포 없이 적용됩니다. 설정
+백그라운드 새로 고침을 비활성화하려면 `AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0`
+간격을 조정하려면 최소 `5000` 밀리초의 값으로 설정하세요.
+
+아래의 이전 허브 모드는 대략적인 "모든 조직 범위 MCP 공유"에 여전히 유용합니다.
+Server from Dispatch” 설정 및 이미 MCP를 사용하는 배포용
+UI를 정보 소스로 설정합니다.
+
+### 1. 허브 앱에서 허브 서비스 활성화(디스패치)
+
+디스패치 배포 시 환경 변수 설정:
+
+```bash
+AGENT_NATIVE_MCP_HUB_TOKEN=<a-long-random-secret>
+```
+
+Dispatch는 이제 토큰으로 인증된 전체 URL + 헤더와 함께 `settings` 테이블에 저장된 모든 조직 범위 MCP 서버를 반환하는 `GET /_agent-native/mcp/hub/servers`를 마운트합니다.
+
+### 2. 허브에서 포인트를 소비하는 앱
+
+모든 소비자에게 설정(메일, 클립 등):
+
+```bash
+AGENT_NATIVE_MCP_HUB_URL=https://dispatch.acme.com
+AGENT_NATIVE_MCP_HUB_TOKEN=<the-same-secret>
+```
+
+시작 시 각 소비자는 허브의 서버 목록을 가져와 자체 MCP 관리자에 병합합니다. 도구는 에이전트에게 `mcp__hub_<orgId>_<name>__*`로 표시됩니다. 이는 소비자의 로컬 `mcp__org_…`와 구별되므로 충돌이 없습니다.
+
+### 3. 공유되는 내용
+
+**조직 범위** 서버만 공유됩니다. 사용자 범위(개인) 서버는 자신을 추가한 사용자와 함께 유지됩니다. 허브는 절대 앱 전체에 개인 자격 증명을 다시 노출하지 않습니다.
+
+허브 응답에는 전체 인증 헤더(Bearer 토큰 등)가 포함됩니다. 전송은 HTTPS이고 엔드포인트에는 공유 비밀이 필요하며 조직 범위 행만 반환합니다. 허브 URL + 토큰을 데이터베이스 자격 증명처럼 처리합니다.
+
+### 4. 핫 리로드와 재시작
+
+로컬 UI는 `McpClientManager.reconfigure()`를 통해 각 앱에 핫 리로드를 추가합니다. 다시 시작할 필요가 없습니다. 허브 소스 서버는 작업 영역 리소스 경로가 사용하는 것과 동일한 주기적인 백그라운드 새로 고침(약 60초, `AGENT_NATIVE_MCP_CONFIG_REFRESH_MS`를 통해 조정 가능 또는 비활성화 가능)에 의해 선택되므로 Dispatch에서 변경한 사항은 다시 시작하지 않고도 약 1분 내에 모든 소비자 앱에 전파됩니다. 또한 소비자 앱의 모든 로컬 변형은 해당 앱에 대한 재구성을 즉시 트리거합니다.
+
+### 엔드포인트 요약
+
+| 방법 | 경로                             | 목적                                                                                                                         |
+| ---- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| GET  | `/_agent-native/mcp/hub/servers` | 전체 자격 증명으로 모든 조직 범위 서버를 제공합니다(베어러 게이트, `AGENT_NATIVE_MCP_HUB_TOKEN`가 설정된 경우에만 마운트됨). |
+| GET  | `/_agent-native/mcp/hub/status`  | 설정 UI 카드에 대해 `{ serving, consuming, hubUrl }`를 반환합니다.                                                           |
+
+## 상태 경로 {#status-route}
+
+모든 앱은 툴링 및 온보딩을 위해 `GET /_agent-native/mcp/status`를 노출합니다.
+
+```an-api
+{
+  "method": "GET",
+  "path": "/_agent-native/mcp/status",
+  "summary": "MCP client status for tooling and onboarding",
+  "description": "Reports which configured servers connected, the total live tool count, the merged prefixed tool list, and any per-server connection errors. Use it to build \"detected — your agent can now drive X\" hints or to debug connection problems.",
+  "responses": [
+    {
+      "status": "200",
+      "description": "Configured vs connected servers, tool inventory, and per-server errors.",
+      "example": "{\n  \"configuredServers\": [\"claude-in-chrome\", \"playwright\"],\n  \"connectedServers\": [\"claude-in-chrome\", \"playwright\"],\n  \"totalTools\": 21,\n  \"tools\": [\n    {\n      \"source\": \"claude-in-chrome\",\n      \"name\": \"mcp__claude-in-chrome__navigate\",\n      \"description\": \"Navigate the browser to a URL\"\n    }\n  ],\n  \"errors\": {}\n}"
+    }
+  ]
+}
+```
+
+```json
+{
+  "configuredServers": ["claude-in-chrome", "playwright"],
+  "connectedServers": ["claude-in-chrome", "playwright"],
+  "totalTools": 21,
+  "tools": [
+    {
+      "source": "claude-in-chrome",
+      "name": "mcp__claude-in-chrome__navigate",
+      "description": "Navigate the browser to a URL"
+    }
+  ],
+  "errors": {}
+}
+```
+
+이를 사용하여 'claude-in-chrome 감지됨 - 이제 에이전트가 Chrome을 구동할 수 있음' 온보딩 힌트를 구축하거나 MCP 연결 문제를 디버그할 수 있습니다.
+
+## 실패 모드 {#failures}
+
+개별 MCP 서버 오류로 인해 에이전트가 중단되지는 않습니다.
+
+- 잘못 구성된 `command` → 서버를 건너뛰고 해당 오류가 `errors.<server-id>` 아래의 `/mcp/status`에 나타나고 다른 모든 서버는 계속 작동합니다.
+- MCP SDK는 `node_modules`에서 누락되었습니다. → 모든 MCP 기능은 경고와 함께 건너뛰었습니다. 에이전트 채팅은 MCP 도구 없이도 계속 작동합니다.
+- 에지 런타임에서 실행 → MCP 클라이언트는 작동하지 않습니다.
+
+에이전트 기본은 항상 부팅됩니다. 손상된 MCP 구성은 도구 수가 적다는 것을 의미합니다.
+
+## 보안 {#security}
+
+MCP 도구는 생성된 프로세스에 있는 모든 권한을 사용하여 컴퓨터에서 실행됩니다. `mcp.config.json`를 에이전트가 구동하도록 허용할 다른 실행 파일 목록처럼 취급하십시오. MCP 서버의 도구는 템플릿의 자체 actions와 마찬가지로 상담원의 도구 사용 루프에 표시되므로 구성하는 모든 서버를 신뢰할 수 있는지 확인하세요.

package/corpus/core/docs/content/locales/ko-KR/mcp-protocol.md

@@ -0,0 +1,279 @@
+---
+title: "MCP 프로토콜"
+description: "에이전트 네이티브 앱을 원격 MCP 서버로 노출하면 Claude, ChatGPT, Claude 코드, 커서 및 기타 AI 도구가 앱의 actions를 직접 호출할 수 있습니다."
+---
+
+# MCP 프로토콜
+
+**이 페이지: 하위 수준 MCP 서버 참조.** 모든 에이전트 기반 앱이 MCP를 통해 actions를 노출하는 방법 — 자동 탑재된 엔드포인트, 인증 모드, `tools/call` / `ask-agent` 표면 및 사용자 지정 탑재. 서버 내부가 필요할 때 찾아보세요. 호스트를 연결하려면 [External Agents](/docs/external-agents)로 시작하세요.
+
+| 원한다면...                                             | 읽기                                     |
+| ------------------------------------------------------- | ---------------------------------------- |
+| 외부 에이전트/호스트를 앱에 연결                        | [External Agents](/docs/external-agents) |
+| 에이전트에게 더 많은 도구 제공(다른 MCP 서버 사용)      | [MCP Clients](/docs/mcp-clients)         |
+| Claude/ChatGPT에서 렌더링되는 인라인 UI 빌드            | [MCP Apps](/docs/mcp-apps)               |
+| 하위 수준 MCP 서버 참조(인증, 도구, 사용자 정의 마운트) | **이 페이지** — MCP 프로토콜             |
+
+모든 에이전트 기반 앱은 원격 MCP(모델 컨텍스트 프로토콜) 서버를 자동으로 노출하므로 Claude, ChatGPT 사용자 정의 MCP 앱, Claude 코드, 커서, Codex 및 VS Code GitHub Copilot과 같은 외부 AI 도구는 추가 코드 없이 앱의 actions를 직접 검색하고 호출할 수 있습니다. 필요합니다. 목표가 해당 호스트 중 하나를 호스팅된 앱에 *연결*하는 것이라면 [External Agents](/docs/external-agents)는 권장되는 단일 디스패치 커넥터, 앱별 URL, OAuth, MCP 앱 인라인 UI 및 딥 링크를 포함합니다. 이 페이지에는 그 밑에 무엇이 있는지 기록되어 있습니다.
+
+## 개요 {#overview}
+
+MCP는 AI 도구를 외부 기능에 연결하기 위한 표준 프로토콜입니다. 에이전트 기반 앱을 배포하면 기존 A2A 엔드포인트와 함께 MCP 엔드포인트가 자동 탑재됩니다. 모든 MCP 호환 클라이언트는 앱 도구에 연결하여 사용할 수 있습니다.
+
+주요 개념:
+
+- **자동 마운트** — 모든 앱에 `/_agent-native/mcp`가 무료로 제공되며 설정이 필요하지 않습니다.
+- **스트리밍 가능한 HTTP** — 표준 HTTP(POST + SSE)를 통해 최신 MCP 전송을 사용합니다.
+- **동일 actions** — 상담원 채팅 및 A2A를 지원하는 동일한 작업 레지스트리
+- **`ask-agent` 도구** — 복잡한 작업을 위해 전체 에이전트 루프에 위임하는 메타 도구
+- **MCP 앱** — actions는 공식 `io.modelcontextprotocol/ui` 확장을 통해 대화형 UI 리소스를 광고할 수 있습니다.
+- **표준 원격 MCP OAuth** — OAuth 2.1 검색, 동적 클라이언트 등록, 인증 코드 + PKCE, 새로 고침 토큰 순환
+- **베어러 인증 대체** — OAuth를 실행할 수 없는 클라이언트에 대해 `ACCESS_TOKEN`, `ACCESS_TOKENS` 또는 연결 생성 JWT를 사용합니다.
+
+```an-diagram title="Your app as an MCP server" summary="External hosts connect over Streamable HTTP. Each action is one tool; ask-agent delegates to the full agent loop."
+{
+  "html": "<div class=\"diagram-mcp\"><div class=\"diagram-col\"><div class=\"diagram-node\">Claude</div><div class=\"diagram-node\">ChatGPT</div><div class=\"diagram-node\">Cursor · Codex</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill accent\">POST /_agent-native/mcp</span><small class=\"diagram-muted\">Streamable HTTP</small><small class=\"diagram-muted\">initialize &rarr; tools/list &rarr; tools/call</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\" data-rough>each action<br><small class=\"diagram-muted\">= one tool</small></div><div class=\"diagram-box\" data-rough>ask-agent<br><small class=\"diagram-muted\">&rarr; full agent loop</small></div></div></div>",
+  "css": ".diagram-mcp{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-mcp .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-mcp .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-mcp .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+## MCP 대 A2A {#mcp-vs-a2a}
+
+두 프로토콜 모두 자동으로 마운트됩니다. 귀하의 사용 사례에 맞는 것을 사용하십시오:
+
+|                 | MCP                                                                  | A2A                                            |
+| --------------- | -------------------------------------------------------------------- | ---------------------------------------------- |
+| **최적의 용도** | 앱을 호출하는 외부 도구                                              | 에이전트 간 통신                               |
+| **프로토콜**    | MCP 스트리밍 가능 HTTP                                               | JSON-RPC 2.0                                   |
+| **도구 검색**   | `tools/list`                                                         | `/.well-known/agent-card.json`의 에이전트 카드 |
+| **엔드포인트**  | `/_agent-native/mcp`                                                 | `/_agent-native/a2a`                           |
+| **지원자**      | Claude, ChatGPT, Claude 코드, 커서, Codex, Cowork 및 기타 MCP 호스트 | 기타 에이전트 기반 앱                          |
+| **실행**        | 직접 도구 호출(추가 LLM 없음)                                        | 전체 에이전트 루프(LLM 추론)                   |
+
+또한 `ask-agent` MCP 도구를 사용하여 두 가지 장점을 최대한 활용할 수도 있습니다. Claude 코드에서 호출하여 앱 에이전트가 복잡한 작업을 통해 추론하도록 할 수 있습니다.
+
+## 수동 MCP 클라이언트 구성 {#manual-config}
+
+권장되는 단일 명령 설정의 경우 [External Agents](/docs/external-agents)를 사용하십시오. OAuth 지원 클라이언트에 대한 MCP 구성을 직접 작성하는 경우 앱을 정적 헤더 없이 원격 MCP 서버로 추가하세요.
+
+```bash
+claude mcp add --transport http mail https://mail.example.com/_agent-native/mcp
+```
+
+또는 `.mcp.json`(프로젝트 범위) 또는 `~/.claude.json`(사용자 범위)에 항목을 직접 작성합니다.
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "mail": {
+      "type": "http",
+      "url": "https://mail.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+그런 다음 Claude 코드에서 `/mcp`를 실행하고 **인증**을 선택합니다. 원격 MCP OAuth를 수행할 수 없는 클라이언트의 경우 연결 페이지를 사용하거나 `headers.Authorization`와 함께 정적 베어러 토큰 항목을 사용하세요. 인증되면 앱 도구를 자연스럽게 사용할 수 있습니다.
+
+```
+> draft an email to John about the Q3 report
+
+Claude Code calls: draft-email(to: "john@example.com", subject: "Q3 Report", body: "...")
+```
+
+## 다른 MCP 클라이언트에서 연결 {#other-clients}
+
+스트리밍 가능한 HTTP 전송을 지원하는 모든 MCP 클라이언트가 연결할 수 있습니다. 끝점은 다음과 같습니다.
+
+```
+POST https://your-app.example.com/_agent-native/mcp
+```
+
+서버는 표준 MCP 핸드셰이크를 지원합니다: `initialize` → `initialized` → `tools/list` → `tools/call`.
+
+```an-api title="MCP endpoint" summary="The auto-mounted Streamable HTTP endpoint every agent-native app exposes."
+{
+  "method": "POST",
+  "path": "/_agent-native/mcp",
+  "summary": "MCP Streamable HTTP endpoint",
+  "description": "Auto-mounted on every app. Speaks the standard MCP handshake (`initialize` → `initialized` → `tools/list` → `tools/call`) plus `resources/list`, `resources/templates/list`, and `resources/read` when an action declares `mcpApp`. Each action maps to one tool; `ask-agent` delegates to the full agent loop.",
+  "auth": "Standard remote MCP OAuth (Bearer access token), connect-minted JWT, or static ACCESS_TOKEN/ACCESS_TOKENS",
+  "params": [
+    { "name": "Authorization", "in": "header", "type": "string", "required": false, "description": "Bearer access token. Required except for loopback local-dev probes." },
+    { "name": "method", "in": "body", "type": "string", "required": true, "description": "MCP method, e.g. initialize, tools/list, tools/call." }
+  ],
+  "request": {
+    "contentType": "application/json",
+    "example": "{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"ask-agent\",\n    \"arguments\": { \"message\": \"Summarize Q3 signups by source\" }\n  }\n}"
+  },
+  "responses": [
+    { "status": "200", "description": "MCP result (POST + SSE)." },
+    { "status": "401", "description": "Unauthenticated — responds with a WWW-Authenticate header pointing at OAuth discovery." }
+  ]
+}
+```
+
+작업에서 `mcpApp`를 선언하면 서버는 공식 MCP 앱 확장(`io.modelcontextprotocol/ui`)도 광고하고 앱 리소스에 대해 `resources/list`, `resources/templates/list` 및 `resources/read`를 지원합니다. MCP 앱을 렌더링하는 호스트는 UI 인라인을 표시할 수 있습니다. 그렇지 않은 호스트는 여전히 도구를 호출하고 딥 링크 대체를 사용할 수 있습니다. 제품 UI는 `embedApp()`를 사용해야 인라인 표면이 실제 React 앱 경로이거나 별도의 일반 HTML 구현이 아닌 분석 차트와 같은 공유 React 구성 요소를 렌더링하는 집중 경로가 됩니다. 서버는 표준 MCP 앱 메타데이터와 ChatGPT 앱 SDK 호환성 메타데이터를 모두 내보내므로 앱 가능 호스트가 동일한 `ui://` 리소스를 찾을 수 있습니다. 현재 공식 확장 매트릭스에는 Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT 및 Cursor가 포함됩니다. 호스트 지원은 버전과 계획에 따라 다르므로 사용자 안내를 위해 [External Agents MCP Apps notes](/docs/external-agents#mcp-apps-compatibility)를 사용하세요.
+
+### MCP 앱 삽입 브리지 {#mcp-app-embed-bridge}
+
+`embedApp()`는 하위 수준 URL 첫 번째 MCP 앱 도우미입니다. 서명된 앱을 실행합니다.
+이식(Claude), 제어 프레임(ChatGPT) 또는 직접을 통한 인라인 경로
+탐색은 `ui/*` JSON-RPC 브리지를 통해 호스트 actions를 중재합니다(및
+제어된 프레임 경로에 대한 `agentNative.mcpHost.*` postMessage 릴레이) 및
+전체 앱 경로가 렌더링되지 않도록 리소스 셸 높이를 고정합니다.
+대규모 채팅 아티팩트.
+
+전체 임베딩 브리지 세부정보는 [MCP Apps](/docs/mcp-apps#mcp-app-bridge)를 참조하세요. 이식 대 제어 프레임, `ui/*` 및 postMessage 테이블, `create_embed_session`/`embedStartUrl`, CSP 및 도메인 규칙, 확장 `srcDoc` 임베딩, 높이 클램핑 및 호스트 브리지 클라이언트 API.
+
+## 도구 {#tools}
+
+모든 발신자는 기본적으로 **간소한 카탈로그**(템플릿 선언 앱 actions 및 교차 앱 내장 기능)를 받게 되며, 전체 작업 화면은 명시적인 동의 시에만 제공되고 `tool-search`는 항상 나머지 사용자에게 도달할 수 있습니다. 전체 설명은 [External Agents → Catalog tiers](/docs/external-agents#catalog-tiers)를 참조하세요.
+
+각 작업은 하나의 MCP 도구에 직접 매핑됩니다.
+
+| 액션 속성          | MCP 도구 속성 |
+| ------------------ | ------------- |
+| `tool.description` | `description` |
+| `tool.parameters`  | `inputSchema` |
+| 액션 이름          | 도구 이름     |
+
+`mcpApp`가 있는 경우 도구 항목에는 `_meta.ui.resourceUri`, `_meta["ui/resourceUri"]` 및 `_meta["openai/outputTemplate"]`도 포함되며 해당 `ui://` 리소스는 `text/html;profile=mcp-app`로 반환됩니다.
+
+### `ask-agent` 도구 {#ask-agent}
+
+개별 작업 도구 외에도 모든 MCP 서버에는 `ask-agent` 메타 도구가 포함되어 있습니다. 그러면 앱의 AI 에이전트에 자연어 메시지가 전송되고 응답이 반환됩니다.
+
+에이전트의 추론과 맥락을 활용하는 복잡한 작업에는 `ask-agent`를 사용하세요.
+
+```json
+{
+  "name": "ask-agent",
+  "arguments": {
+    "message": "Draft a follow-up email to the Q3 planning thread with John, summarizing the action items we discussed"
+  }
+}
+```
+
+에이전트는 대화형 채팅과 동일한 루프를 실행합니다. 즉, 여러 도구를 호출하고 상황에 대해 추론하고 사려 깊은 응답을 생성할 수 있습니다.
+
+## 인증 {#authentication}
+
+MCP 엔드포인트는 표준 원격 MCP OAuth와 기존 베어러 토큰 폴백을 지원합니다.
+
+| 모드                    | 작동 방식                                                                                                                          |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| 표준 MCP OAuth          | 클라이언트는 `WWW-Authenticate`에서 인증을 검색하고, 등록하고, PKCE를 실행하고, `Authorization: Bearer <access-token>`를 보냅니다. |
+| Connect-minted JWT      | `npx @agent-native/core@latest connect` / 연결 페이지는 사용자별로 취소 가능한 JWT를 생성합니다                                    |
+| `ACCESS_TOKEN`          | 정적 전달자 토큰 — 클라이언트가 `Authorization: Bearer <token>`를 보냅니다                                                         |
+| `ACCESS_TOKENS`         | 유효한 정적 전달자 토큰의 쉼표로 구분된 목록                                                                                       |
+| `A2A_SECRET`            | JWT 기반 인증 — 토큰은 암호화 방식으로 확인됩니다.                                                                                 |
+| _(설정 없음, 루프백만)_ | 로컬 개발 프로브에는 인증이 필요하지 않습니다                                                                                      |
+
+OAuth 가능 MCP 호스트의 경우 정적 헤더 없이 원격 서버 URL를 구성합니다.
+
+```bash
+claude mcp add --transport http agent-native https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+인증되지 않은 첫 번째 MCP 요청은 다음을 수신합니다.
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://dispatch.agent-native.com/.well-known/oauth-protected-resource", scope="mcp:read mcp:write mcp:apps"
+```
+
+검색 엔드포인트:
+
+| 엔드포인트                                | 목적                             |
+| ----------------------------------------- | -------------------------------- |
+| `/.well-known/oauth-protected-resource`   | RFC 9728 보호 리소스 메타데이터  |
+| `/.well-known/oauth-authorization-server` | OAuth 인증 서버 메타데이터       |
+| `/_agent-native/mcp/oauth/register`       | 동적 공개 클라이언트 등록        |
+| `/_agent-native/mcp/oauth/authorize`      | 브라우저 승인 + 동의             |
+| `/_agent-native/mcp/oauth/token`          | 인증 코드 및 새로 고침 토큰 부여 |
+
+```an-diagram title="OAuth discovery flow" summary="A 401 kicks off discovery, registration, and a PKCE authorize → token exchange. The Bearer token is audience-bound and scoped."
+{
+  "html": "<div class=\"diagram-oauth\"><div class=\"diagram-box\" data-rough>first request<br><small class=\"diagram-muted\">no token</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill warn\">401 · WWW-Authenticate</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill\">/.well-known/oauth-protected-resource</span><span class=\"diagram-pill\">/.well-known/oauth-authorization-server</span><small class=\"diagram-muted\">discover</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill\">register</div><div class=\"diagram-pill\">authorize (PKCE)</div><div class=\"diagram-pill\">token</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Bearer access token<br><small class=\"diagram-muted\">audience-bound · mcp:read / write / apps</small></div></div>",
+  "css": ".diagram-oauth{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-oauth .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-oauth .diagram-col{display:flex;flex-direction:column;gap:6px}.diagram-oauth .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+액세스 토큰은 대상이 정확한 MCP 리소스 URL인 서명된 JWT입니다. 서버는 자체적으로 발행된 토큰만 허용하고 도구를 나열/호출하기 전에 범위를 적용합니다.
+
+| 범위        | 허용                               |
+| ----------- | ---------------------------------- |
+| `mcp:read`  | 읽기 전용 actions                  |
+| `mcp:write` | actions 및 `ask-agent` 돌연변이    |
+| `mcp:apps`  | MCP 앱 리소스(`ui://` HTML 리소스) |
+
+새로 고침 토큰은 해시로만 저장되며 새로 고칠 때마다 교체됩니다. `npx @agent-native/core@latest connect`는 기본적으로 Claude 코드 클라이언트에 대해 이 URL 전용 OAuth 항목을 작성합니다. 연결 페이지, `npx @agent-native/core@latest connect --token <token>`, 로컬 stdio 프록시, 이전 클라이언트 및 긴급/디버그 흐름을 위한 정적 베어러 구성을 유지합니다.
+
+## 사용자 정의 MCP 설정 {#custom-setup}
+
+MCP 서버는 에이전트 채팅 플러그인에 의해 자동 마운트됩니다. 대부분의 앱에는 구성이 필요하지 않습니다. 사용자 정의 동작이 필요한 경우 서버 플러그인에 수동으로 마운트할 수 있습니다:
+
+```ts
+// server/plugins/mcp.ts
+import { mountMCP } from "@agent-native/core/mcp";
+import { autoDiscoverActions } from "@agent-native/core/server";
+
+export default defineNitroPlugin(async (nitro) => {
+  const actions = await autoDiscoverActions(import.meta.url);
+
+  mountMCP(nitro, {
+    name: "My App",
+    description: "Custom MCP server",
+    actions,
+    // Optional: provide ask-agent handler
+    askAgent: async (message) => {
+      // Your custom agent logic
+      return "Response";
+    },
+    // Optional: override the route prefix (default "/_agent-native")
+    // routePrefix: "/_agent-native",
+  });
+});
+```
+
+## 예: Claude 코드 분석 {#example}
+
+`analytics.example.com`에 분석 앱이 배포되어 있습니다. Claude 코드에서:
+
+```bash
+claude mcp add --transport http analytics https://analytics.example.com/_agent-native/mcp
+```
+
+또는 `.mcp.json`에 직접 추가하세요.
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "analytics": {
+      "type": "http",
+      "url": "https://analytics.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+이제 Claude 코드에서:
+
+```
+> How many signups did we get last week?
+
+Claude Code calls: run-query(sql: "SELECT count(*) FROM signups WHERE created_at > now() - interval '7 days'")
+→ "1,247 signups last week"
+```
+
+더 복잡한 분석을 원하시면:
+
+```
+> Ask the analytics agent to prepare a full breakdown of Q3 signups by source, with trends
+
+Claude Code calls: ask-agent(message: "Prepare a full breakdown of Q3 signups by source, with trends")
+→ The analytics agent runs multiple queries, reasons about the data, and returns a formatted report
+```