# AI 에이전트 연결 {/* #connect-an-ai-agent */}

Reconstruct는 MCP 서버를 통해 캡처된 인터페이스 데이터를 제공합니다. 설정 안내를 보려면 에이전트를 선택하세요:

- [Codex](/docs/ko/agents/codex)
- [Claude](/docs/ko/agents/claude)
- [Cursor](/docs/ko/agents/cursor)
- [Cline](/docs/ko/agents/cline)
- [VS Code의 GitHub Copilot](/docs/ko/agents/vscode-copilot)
- [Gemini CLI](/docs/ko/agents/gemini-cli)
- [MiMo](/docs/ko/agents/mimo)
- [Muse Code](/docs/ko/agents/muse-code)
- [Grok Build](/docs/ko/agents/grok-build)
- [Hermes Agent](/docs/ko/agents/hermes)
- [OpenClaw](/docs/ko/agents/openclaw)
- [OpenMausBot](/docs/ko/agents/openmausbot)
- [기타 MCP 클라이언트](/docs/ko/agents/other-mcp-clients)

## 시작하기 전 {/* #before-you-start */}

Reconstruct MCP 엔드포인트는 **`https://reconstruct.dev/mcp`**이며 **Streamable HTTP**를 사용합니다. OAuth 브라우저 로그인 또는 개인 액세스 토큰으로 연결할 수 있습니다.

| 방식 | 작동 방법 | 사용 시점 |
|---|---|---|
| **OAuth 브라우저 로그인** | MCP 클라이언트가 브라우저에서 Reconstruct 로그인을 엽니다. 로그인하고 액세스를 승인한 다음 클라이언트로 돌아오세요. Platform에서 토큰을 만들거나 복사할 필요가 없습니다. | OAuth를 지원하는 대화형 에이전트 및 편집기. |
| **개인 액세스 토큰** | Platform 설정에서 MCP 토큰을 만들고 클라이언트 자격 증명에 추가합니다. | OAuth를 지원하지 않는 클라이언트 또는 브라우저 로그인이 없는 자동화 환경. |

두 방식 모두 같은 MCP 서버에 연결하며 Reconstruct 계정의 구독과 사용 한도를 사용합니다.

## 브라우저에서 OAuth 로그인 {/* #oauth-browser-sign-in */}

OAuth 연결 전에 Platform에서 개인 토큰을 발급할 필요가 없습니다.

1. 클라이언트에 원격 HTTP MCP 서버로 `https://reconstruct.dev/mcp`를 추가하세요.
2. OAuth 또는 브라우저 로그인을 선택하세요. 연결 설정이 필요하다면 아래 값을 사용하세요.
3. **Sign in**, **Connect** 또는 클라이언트의 MCP 로그인 명령을 시작하세요. 정확한 동작은 클라이언트에 따라 다릅니다.
4. 브라우저에서 Reconstruct 계정에 로그인하고 요청된 액세스를 승인하세요. 등록이 불가능하면 계정 액세스를 위해 지원팀에 문의하세요.
5. 클라이언트로 돌아가 도구를 새로고침하세요. `list_products` 호출을 요청해 연결을 확인하세요.

| 설정 | 값 |
|---|---|
| 서버 URL | `https://reconstruct.dev/mcp` |
| 전송 | Streamable HTTP |
| OAuth 클라이언트 ID | 사전 설정된 클라이언트는 `reconstruct-mcp`를 사용하며 Claude Desktop은 자동 등록합니다 |
| 범위 | `openid aud-mcp` |
| 클라이언트 보안 비밀 | 비워 두기 |
| OAuth 발급자 | `https://reconstruct.dev/sso/realms/reconstruct` |
| 인증 엔드포인트 | `https://reconstruct.dev/sso/realms/reconstruct/protocol/openid-connect/auth` |
| 토큰 엔드포인트 | `https://reconstruct.dev/sso/realms/reconstruct/protocol/openid-connect/token` |

클라이언트는 로그인 후 OAuth 자격 증명을 받아 저장하고 MCP 호출에 사용합니다. 이 방식은 토큰 복사나 `CR_RECONSTRUCT_MCP_TOKEN` 설정이 필요하지 않습니다. 기존 연결을 OAuth로 바꿀 때 수동으로 설정한 `Authorization` 헤더 또는 bearer 토큰 설정을 제거하세요.

[Codex](/docs/ko/agents/codex#oauth-browser-sign-in), [Claude Code](/docs/ko/agents/claude-code#oauth-browser-sign-in), [Cursor](/docs/ko/agents/cursor#oauth-browser-sign-in), [Cline](/docs/ko/agents/cline#oauth-browser-sign-in), [OpenMausBot](/docs/ko/agents/openmausbot#oauth-browser-sign-in) 또는 [다른 MCP 클라이언트](/docs/ko/agents/other-mcp-clients#oauth-browser-sign-in)의 OAuth 설정 예시를 참고하세요. 해당 클라이언트에 문서화된 콜백 설정을 사용하세요. 다시 로그인하라는 요청이 표시되면 MCP 로그인 절차를 반복하세요.

### 클라이언트 호환성 {/* #client-compatibility */}

브라우저 로그인 예시는 등록된 콜백을 사용하는 Claude, Cursor, Claude Code, Codex, Grok Build 및 Muse Code를 다룹니다. Gemini CLI, VS Code, MiMo Code, MiMo Desktop, Hermes Agent 및 OpenClaw 가이드는 개인 액세스 토큰을 사용하며 VS Code 가이드는 자동 클라이언트 등록을 통한 원클릭 설치도 제공합니다. Claude Desktop과 웹 커넥터는 승인된 정확한 HTTPS 콜백으로 자동 등록을 지원합니다. OAuth 검색과 동적 클라이언트 등록을 지원하는 다른 클라이언트도 서버 URL만으로 연결할 수 있으며 자체의 정확한 HTTPS 또는 루프백 콜백을 등록하고 처리합니다. DCR이 없는 클라이언트는 사전 설정된 공개 클라이언트 설정을 대신 사용할 수 있습니다.

OAuth 엔드포인트는 검색 메타데이터에서 가져옵니다. 웹사이트 루트의 `/authorize`나 `/token`이 아니라 SSO realm 아래에 있습니다. 클라이언트가 루트 엔드포인트를 연다면 서버 설정을 다시 로드하고 로그인하여 캐시된 검색 정보를 갱신하세요.

Claude 클라우드 커넥터는 [Claude Desktop 가이드](/docs/ko/agents/claude-desktop)를 따르세요. 다른 클라우드 통합을 연결하기 전에는 정확한 콜백 URI로 지원팀에 문의하세요. `reconstruct-mcp`에는 클라이언트 보안 비밀을 입력하면 안 됩니다.

## 에이전트 검색 및 기기 로그인 {/* #agent-discovery-and-device-sign-in */}

공개 검색은 `https://reconstruct.dev/mcp/server-card`에서 시작됩니다. 루트 `/.well-known/api-catalog`에는 공개 API 문서, `/.well-known/agent-skills/index.json`에는 Reconstruct 워크플로와 설치용 아카이브가 나열됩니다. 9개 워크플로, 별도 설치 없는 MCP 리소스 접근, 웹사이트 또는 GitHub CLI 설치, 수동 다운로드 및 클라이언트별 플러그인 패키지는 [Reconstruct 스킬](/docs/ko/skills)을 참고하세요. 원격 MCP 서버 연결에는 사용자 컴퓨터의 .NET SDK가 필요하지 않습니다.

공개된 웹사이트 페이지와 문서는 `Accept: text/markdown`을 지원합니다. 워크스페이스 페이지에는 여전히 계정 액세스가 필요합니다.

OAuth Device Authorization을 구현한 클라이언트는 `https://reconstruct.dev/auth.md`를 읽고 `https://reconstruct.dev/agent/register`에 `{"type":"anonymous"}`를 POST할 수 있습니다. 응답에는 대기 중인 기기 인증, 사용자 확인 URL과 코드, 만료 시각, 폴링 간격 및 비공개 PKCE `code_verifier`가 있습니다. 확인 안내를 사용자에게 보여주세요. 사용자가 로그인하고 액세스를 승인해야 합니다. 에이전트는 이후 device-code grant와 반환된 `code_verifier`로 발급자의 토큰 엔드포인트를 폴링합니다. 폴링 간격과 `slow_down` 응답을 준수하세요. 등록 자체가 액세스 토큰을 발급하거나 계정을 만들지는 않습니다. 기존 역할, 구독 한도 및 동의 요건은 계속 적용됩니다.

기기 코드, 코드 검증자 및 토큰을 비공개로 유지하세요. 사용자를 대신해 액세스를 승인하지 마세요. 이 방식은 이를 구현한 클라이언트에서만 사용할 수 있으며 편집기의 기존 Authorization Code + PKCE 설정을 대체하지 않습니다.

## 개인 액세스 토큰 {/* #personal-access-token */}

1. [Reconstruct Platform](https://reconstruct.dev/platform/)에 로그인하고 **Settings → API tokens**를 여세요.
2. **MCP** 범위(`mcp`) 토큰을 만들고 표시될 때 비밀을 복사하세요.
3. 클라이언트가 `Authorization: Bearer <token>`을 보내도록 설정하세요. 환경 변수에서 읽는다면 `CR_RECONSTRUCT_MCP_TOKEN`을 사용하세요.
4. 연결한 후 클라이언트에 `list_products` 호출을 요청하세요.

토큰은 로컬 비밀 저장소 또는 클라이언트 자격 증명 저장소에 보관하세요. 만료되거나 취소되면 Platform 설정에서 새로 만들고 클라이언트 자격 증명을 갱신하세요.

## 캡처 데이터 선택 {/* #select-captured-data */}

`list_products`, `list_platforms`, `list_versions`부터 시작하세요. 반환된 ID를 사용해 `list_platforms.options.platforms[]`에서 플랫폼 형식과 환경을 선택하세요. `list_platforms.platforms[]`는 실제 캡처 데이터가 있는 쌍을 포함합니다. 페이지 도구에는 `list_pages.views[]`의 정확한 저장 `view` 키를 사용하세요. 버전에 환경이 여러 개라면 `environment`를 명시하세요. 컨텍스트 도구는 남은 구독 사용량이 필요하며 캐시 결과를 포함해 호출이 수락되면 컨텍스트 읽기 1회를 소비합니다. 수락된 호출은 나중에 실패해도 계산됩니다. 검색, 이미지 도구 및 에셋 다운로드는 컨텍스트 읽기를 소비하지 않습니다. [사용 한도](/docs/ko/mcp-tools#usage-limits)를 참고하세요.

## 문제 해결 {/* #troubleshooting */}

| 증상 | 확인 사항 |
|---|---|
| `401 Unauthorized` | OAuth 로그인을 완료하거나 개인 토큰을 확인하세요. 만료되거나 취소되었다면 교체하세요. |
| `/authorize`가 404를 반환함 | 연결 메타데이터를 갱신하고 다시 로그인하세요. 인증 엔드포인트는 `https://reconstruct.dev/sso/realms/reconstruct` 아래에 있습니다. |
| `invalid_scope` | `openid aud-mcp`를 요청하세요. Grok Build는 선택적 `offline_access` 범위도 요청할 수 있습니다. |
| 로그인 후 인증이 필요함 | 서버를 새로고침하고 OAuth 로그인을 반복하세요. 충돌하는 수동 bearer 자격 증명은 제거하세요. |
| OAuth 리디렉션 불일치 | 클라이언트에 문서화된 콜백 포트를 사용하세요. 계속 오류가 나면 클라이언트에 표시된 콜백 URI로 지원팀에 문의하세요. |
| 동적 클라이언트 등록 거부 | 자동 OAuth 등록을 선택하고 1분 후 재시도하세요. 클라이언트는 정확한 HTTPS 또는 루프백 콜백을 제공하고 PKCE S256을 지원해야 합니다. 자체 등록이 불가능하면 해당 가이드의 사전 설정 OAuth 값을 사용하세요. |
| 서버에 연결할 수 없음 | 에이전트가 실행되는 컴퓨터에서 `https://reconstruct.dev/mcp`에 접근할 수 있는지 확인하세요. |
| 도구가 액세스 거부를 반환함 | Reconstruct 계정으로 로그인하고 구독을 확인하세요. 여전히 접근할 수 없다면 지원팀에 문의하세요. |
| 할당량 또는 사용량을 사용할 수 없음 | 계정 설정의 사용량과 상태 페이지를 확인하세요. 액세스가 가능해지면 다시 시도하세요. |
| 여러 환경이 캡처됨 | `list_versions`의 `environment`를 제공하세요. |
| 요청한 플랫폼/뷰를 사용할 수 없음 | 캡처된 플랫폼/환경 쌍과 정확한 `list_pages.views[]` 키를 사용하세요. 지원되는 옵션이 저장된 데이터를 보장하지는 않습니다. |
| 도구가 표시되지 않음 | 에이전트를 재시작하거나 MCP 도구 목록을 새로고침한 다음 서버 상태를 확인하세요. |

연결 후 [프롬프트 예시](/docs/ko/prompt-examples)를 사용하거나 [MCP 도구 카탈로그](/docs/ko/mcp-tools)를 살펴보세요.

### 새 캡처 또는 업데이트 요청 {/* #request-a-new-capture-or-update */}

MCP 서버에는 `get_request_options`, `create_product_request`, `get_product_request`, `list_product_requests`, `wait_product_request`가 있습니다. OAuth로 로그인하거나 MCP 액세스 토큰을 사용하세요. 요청을 지원하는 구독이 필요하며 해당 계정으로 제출한 요청만 볼 수 있습니다. 에이전트에 새 제품 URL 제출 또는 알려진 공개 제품 키 업데이트를 요청한 다음 `requestId`를 보관하고 검토 상태 변경을 기다리게 하세요. 요청 승인이 캡처 완료를 의미하지는 않습니다. 매개변수는 [요청 도구](/docs/ko/mcp-tools#product-requests)를 참고하세요.