--- title: "ChatGPT, Claude, Cursor, VS Code를 위한 Minds MCP 설정" description: "ChatGPT, Claude Desktop, Cursor, VS Code, OpenRouter, Open WebUI 및 API 키 인증을 사용하여 Minds MCP 서버를 설정합니다." canonical_url: "https://getminds.ai/mcp/ko/setup" last_updated: "2026-08-13T13:01:12.723Z" --- # ChatGPT, Claude, Cursor, VS Code를 위한 Minds MCP 설정 이 가이드는 [시장 조사용 Minds MCP 서버](/mcp/overview)를 원격 도구를 지원하는 AI 클라이언트에 연결하는 방법을 설명합니다. 서버 URL로 `https://getminds.ai/mcp`를 사용하세요. ## ChatGPT 1. **ChatGPT** → **Settings** (설정) → **Connected Apps** (연결된 앱)로 이동합니다. 2. "Minds"를 검색하거나 MCP URL을 추가합니다: `https://getminds.ai/mcp` 3. **Connect** (연결)를 클릭하고 OAuth를 통해 인증합니다 (Minds 계정 로그인). 4. 대화를 시작하세요. ChatGPT에게 Minds 생성, 패널 실행, 결과 분석을 요청할 수 있습니다. ChatGPT는 대화창 내에 대화형 위젯을 직접 렌더링합니다. 그룹화된 응답이 포함된 패널 결과, 막대 그래프, 클릭 가능한 Mind 아바타가 채팅창에 바로 표시됩니다. ## Claude Desktop ### 옵션 A: 원격 커넥터 (권장 - 대화형 위젯 활성화) 1. Claude Desktop을 열고 **Customize** → **Connectors** (또는 **Settings** → **Connections**)로 이동합니다. 2. `https://getminds.ai/mcp`를 새 원격 커넥터로 추가합니다. 3. 안내에 따라 OAuth를 통해 인증합니다 (Minds 계정 로그인). 4. 인증이 완료되면 도구가 자동으로 나타납니다. ### 옵션 B: 로컬 커넥터 (API 키, 텍스트 전용) 설정 파일(macOS의 경우 `~/Library/Application Support/Claude/claude_desktop_config.json`)에 다음을 추가합니다: ```json { "mcpServers": { "mindsai": { "command": "npx", "args": [ "-y", "mcp-remote", "https://getminds.ai/mcp", "--header", "Authorization: Bearer minds_YOUR_API_KEY" ] } } } ``` Claude Desktop을 재시작합니다. 도구는 즉시 작동하지만, 로컬 커넥터에서는 대화형 위젯을 사용할 수 없습니다. ### Claude에서의 위젯 지원 공개되는 15개 도구는 구조화된 텍스트와 클릭 가능한 링크를 반환합니다. 명시적 통합을 위해 18개의 정식 라이프사이클 도구도 추가로 등록되어 있습니다. 위젯 표시는 클라이언트와 버전에 따라 달라지므로, 통합은 구조화 결과와 텍스트 결과만으로도 완전히 사용할 수 있어야 합니다. ## Claude Code (CLI) ```bash claude mcp add --transport http mindsai https://getminds.ai/mcp \ --header "Authorization: Bearer minds_YOUR_API_KEY" ``` ## Cursor 1. Cursor Settings (설정) → **MCP**로 이동합니다. 2. 다음 URL로 새 서버를 추가합니다: `https://getminds.ai/mcp` 3. 안내에 따라 액세스를 승인합니다. ## VS Code (GitHub Copilot) 1. VS Code Settings (설정) → **Extensions** (확장) → **GitHub Copilot** → **MCP Servers**로 이동합니다. 2. `https://getminds.ai/mcp`를 새 서버로 추가합니다. 3. 안내에 따라 인증합니다. ## OpenRouter, Open WebUI 및 OpenAI 호환 게이트웨이 호스트가 아닌 **모델 제공업체(model provider)**가 서버 측에서 MCP 호출을 실행하는 환경(예: OpenRouter를 통해 액세스하는 `openai/*` 모델, OpenAI의 Responses API 직접 호출, 또는 *Native function-calling* 모드의 Open WebUI 등)에서는 **반드시 API 키 인증을 사용해야 합니다**. 이 경로에서는 OAuth가 지원되지 않습니다. ### 여기서 OAuth가 작동하지 않는 이유 Open WebUI가 Native 모드에서 `openai/gpt-5.2` 에이전트를 실행할 때, 요청의 일부로 MCP 도구 디스크립터를 OpenAI/OpenRouter로 전송합니다. 그러면 OpenAI의 서버 측 MCP 러너(Azure에서 실행되며 `User-Agent: python-httpx/*`로 식별 가능)가 Minds의 `/mcp` 엔드포인트를 직접 호출합니다. 이 러너는 도구 등록 시 설정된 **정적(static)** 헤더만 첨부하며, MCP OAuth 핸드셰이크(RFC 9728 / 8414 / 7591)를 수행하지 않습니다. 따라서 Open WebUI의 *OAuth - forwards system user's access token* 모드는 아무런 동작도 하지 않으며(no-op), 사용자의 토큰은 Open WebUI를 벗어나지 않습니다. 결과적으로 Minds는 `Authorization` 헤더가 없는 요청을 수신하고 다음을 반환합니다: ```text 401 Unauthorized www-authenticate: Bearer resource_metadata="https://getminds.ai/.well-known/oauth-protected-resource" {"error":{"code":-32001,"message":"Authentication required. Connect your Minds account via OAuth or provide an API key."}} ``` ### Open WebUI 설정 1. [Settings → API Keys](/settings/api-keys)에서 API 키를 생성합니다 (형식: `minds_…`). 2. Open WebUI에서 **Admin → Settings → Tools → + Connection**으로 이동합니다. 3. 다음과 같이 설정합니다: - **Type**: `Streamable HTTP (MCP)` - **URL**: `https://getminds.ai/mcp` - **Authentication**: `Bearer` *(OAuth 아님)* - **Token**: 생성한 `minds_…` 키 4. 연결을 저장합니다. 5. 에이전트의 *Werkzeuge / Tools* 탭에서 **Get Minds** 도구를 연결합니다. 6. 에이전트에게 Minds 목록을 보여달라고 요청하여 테스트합니다. `Authentication: OAuth`를 유지하는 경우, Open WebUI 자체가 도구를 실행하고(*Function calling = Default*로 설정, *Native* 아님) **동시에** 업스트림 모델이 도구 결과와 함께 다시 프롬프트될 수 있는 경우에만 호출이 성공합니다. 대부분의 사용자는 Native 모드를 원하므로 Bearer 키를 사용하세요. ### OpenRouter 직접 호출 (프로그래밍 방식) OpenRouter의 chat completions API를 호출하고 Minds MCP 서버를 연결할 때, 도구 디스크립터의 정적 `headers` 필드에 API 키를 전달합니다: ```json { "type": "mcp", "server_label": "minds", "server_url": "https://getminds.ai/mcp", "headers": { "Authorization": "Bearer minds_YOUR_API_KEY" } } ``` OpenAI의 Responses API를 직접 호출할 때도 동일하게 적용됩니다: ```python from openai import OpenAI client = OpenAI() client.responses.create( model="gpt-5.2", input="List my Minds", tools=[{ "type": "mcp", "server_label": "minds", "server_url": "https://getminds.ai/mcp", "headers": {"Authorization": f"Bearer {os.environ['MINDS_API_KEY']}"}, }], ) ``` ## API 키 인증 프로그래밍 방식의 액세스 또는 OAuth를 지원하지 않는 클라이언트의 경우: 1. Minds의 [Settings → API Keys](/settings/api-keys)로 이동합니다. 2. 새 API 키를 생성합니다 (`minds_`로 시작). 3. Bearer 토큰으로 전달합니다: `Authorization: Bearer minds_your_key_here` ## OAuth 디스커버리 MCP 연동을 개발하는 개발자를 위해 OAuth 메타데이터는 다음에서 제공됩니다:
엔드포인트 설명
/.well-known/oauth-protected-resource 보호된 리소스 메타데이터 (RFC 9728)
/.well-known/oauth-authorization-server 인증 서버 메타데이터 (RFC 8414)
/oauth/register 동적 클라이언트 등록 (RFC 7591)
PKCE (S256)를 사용하는 OAuth 2.1이 필요합니다. 퍼블릭 클라이언트(`token_endpoint_auth_method: "none"`)가 지원됩니다. ## 문제 해결 ### "Authentication required" 오류 OAuth 인증 흐름을 완료했는지 확인하세요. MCP 클라이언트의 연결을 끊었다가 다시 연결하여 재인증을 진행합니다. **OpenRouter, Native 모드의 Open WebUI, 또는 OpenAI의 Responses API 직접 호출**을 통해 Minds를 호출하는 경우, 해당 경로에서는 OAuth가 지원되지 않습니다. 모델 제공업체의 서버 측 MCP 러너가 OAuth 핸드셰이크를 수행할 수 없기 때문입니다. MCP 연결을 `minds_…` 키를 사용하는 **Bearer / API 키 인증**으로 전환하세요. 위의 [OpenRouter, Open WebUI 및 OpenAI 호환 게이트웨이](#openrouter-open-webui-and-openai-compatible-gateways) 섹션을 참조하세요. ### Claude Desktop OAuth 인증이 완료되지 않는 경우 OAuth 팝업은 열리지만 완료되지 않는 경우, API 키 방식(위의 옵션 B)을 사용해 보세요. Claude Desktop의 원격 커넥터 OAuth는 일시적으로 불안정할 수 있습니다. ### Mind를 찾을 수 없는 경우 `sparkName`를 사용할 때 이름이 내 Mind와 유사한지 확인하세요. 시스템은 퍼지 매칭(fuzzy matching)을 사용하지만, 일정 수준 이상의 유사도 점수가 필요합니다. ### Mind가 아직 학습 중인 경우 새로운 Minds는 학습을 완료하는 데 시간이 다소 걸릴 수 있습니다. 대화를 시작하기 전에 `get_mind_status`를 사용하여 학습이 완료되었는지 확인하세요. ### 패널 질문 시간 초과 그룹이 많은 패널 질문은 완료하는 데 2분 이상 걸릴 수 있습니다. 그룹 수를 줄이거나 질문을 단순화해 보세요. ### PDF 내보내기가 준비되지 않은 경우 PDF 보고서는 비동기식으로 생성됩니다. `get_panel_status`를 사용하여 내보내기 상태를 확인하세요. 생성에는 보통 30-60초가 소요됩니다.