How do I troubleshoot api 키 문제?

키가 mgv_ 접두사로 시작하는지 확인하세요 키가 환경에 올바르게 설정되어 있는지 확인하세요 키가 만료되지 않았는지 확인하세요

How do I troubleshoot 저장소를 찾을 수 없음?

저장소가 app.maguyva.ai에 연결되어 있는지 확인하세요 owner/repo 형식이 올바른지 확인하세요 저장소에 접근 권한이 있는지 확인하세요

How do I troubleshoot mcp 연결 문제?

npx가 PATH에서 사용 가능한지 확인하세요 API 토큰이 유효하고 만료되지 않았는지 확인하세요 https://maguyva.tools/mcp로의 연결을 테스트하세요 클라이언트의 MCP 설정 문법을 확인하세요

Maguyva MCP 설정이 제대로 작동하는지 어떻게 확인하나요?

연결한 후, 에이전트에게 서로 다른 검색 방식을 시험해보는 프롬프트를 던져보세요: "제가 연결한 저장소는 무엇인가요?" (연결이 작동하는지 확인합니다); "이 코드베이스에서 인증은 어떻게 처리되나요?" (시맨틱 검색을 테스트합니다); "데이터베이스를 호출하는 모든 함수를 찾아줘" (의존성 검색을 테스트합니다); "UserService 클래스는 무엇에 의존하나요?" (심볼 조회를 테스트합니다). 연결된 저장소의 파일 경로와 줄 번호가 포함된 결과를 볼 수 있어야 합니다.

Maguyva MCP 요청에서 저장소는 어떻게 지정하나요?

MCP 클라이언트가 요청 기본값을 제공하거나 키가 정확히 하나의 저장소에만 접근할 수 있으면 저장소를 생략합니다. 그 외에는 기본 브랜치에 "owner/repo"(예: "owner/repository"), 특정 브랜치에 "owner/repo:branch"(예: "owner/repository:develop")를 사용합니다.

설치 가이드

5분 이내에 시작할 수 있습니다. 이 가이드는 Claude Code, Claude Desktop, Cursor, VS Code / GitHub Copilot, 그리고 Windsurf 등을 포함한 24개 MCP 클라이언트의 설정 방법을 다룹니다.

사전 준비물: app.maguyva.ai에서 발급받은 API 키와 연결된 GitHub 저장소가 필요합니다.

환경 설정#

먼저 API 키를 환경 변수에 설정합니다. MCP 클라이언트가 요청 기본값을 제공하거나 키가 정확히 하나의 저장소에만 접근할 수 있으면 repository을(를) 생략하고, 그 외에는 명시적으로 전달합니다.

macOS/Linux (Bash/Zsh)#

# Add to your shell profile for persistence:
echo 'export MAGUYVA_API_KEY="mgv_xxxx"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # reload

Windows (PowerShell)#

# Make it persist in your profile:
'$Env:MAGUYVA_API_KEY="mgv_xxxx"' | Out-File -Append $PROFILE
. $PROFILE

mgv_xxxx를 app.maguyva.ai에서 발급받은 실제 API 키로 교체하세요.

클라이언트 설정#

아래에서 사용하는 MCP 클라이언트를 선택하면 구체적인 설정 방법을 확인할 수 있습니다.

호환성 참고: Maguyva는 표준 MCP를 사용합니다. MCP를 지원하는 클라이언트라면 저희가 아직 자체 설정 가이드를 작성하지 않았더라도 동일한 서버에 연결할 수 있습니다.

Claude Code

Claude Code 마켓플레이스에서 Maguyva 플러그인을 설치하세요:

Maguyva 마켓플레이스를 추가한 다음 플러그인을 설치하세요(각 명령어를 Claude Code 안에서 실행합니다):

/plugin marketplace add maguyva/claude-code-plugin
/plugin install maguyva@maguyva

사용자 계정에 설치됩니다. 팀의 경우, 두 명령어 모두에 --scope project를 추가하면 플러그인이 저장소의 .claude/settings.json에 커밋되어 팀원들도 자동으로 받게 됩니다.

플러그인은 MAGUYVA_API_KEY 환경 변수를 통해 인증합니다. 셸에서 이를 설정하세요:

export MAGUYVA_API_KEY=mgv_xxxx

프로젝트별 direnv(.envrc) 사용을 권장합니다 — 키는 저장소 단위이므로, 프로젝트별 값이 각 프로젝트의 접근 권한에 맞아떨어집니다. 하나의 키로 모든 작업을 처리한다면 전역 셸 export도 괜찮습니다.

수동 설정(.mcp.json) — 고급

.mcp.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Claude Code MCP 문서 →

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %AppData%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Claude Desktop 설정 파일에 추가하세요:

claude_desktop_config.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Claude Desktop은 원격 서버를 claude_desktop_config.json에 헤더 인증 항목으로 지원하지 않고, Settings를 통한 OAuth "커넥터"로만 지원하므로, 여기서는 mcp-remote 브리지를 사용합니다(Node.js / npx 필요).

Claude Desktop MCP 문서 →

Cursor

macOS: ~/.cursor/mcp.json
Windows: %UserProfile%\.cursor\mcp.json
Linux: ~/.cursor/mcp.json

프로젝트 루트의 .cursor/mcp.json에 추가하세요:

.cursor/mcp.json

{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Cursor MCP 문서 →

VS Code / GitHub Copilot

프로젝트의 .vscode/mcp.json에 추가하세요(또는 사용자 설정에):

.vscode/mcp.json

{
  "servers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

VS Code / GitHub Copilot MCP 문서 →

Windsurf

macOS: ~/.codeium/windsurf/mcp_config.json
Windows: %UserProfile%\.codeium\windsurf\mcp_config.json
Linux: ~/.codeium/windsurf/mcp_config.json

Windsurf MCP 설정에 추가하세요:

mcp_config.json

{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Windsurf MCP 문서 →

Codex

macOS: ~/.codex/config.toml
Windows: %UserProfile%\.codex\config.toml
Linux: ~/.codex/config.toml

Codex CLI 설정(~/.codex/config.toml)에 추가하세요:

.codex/config.toml

[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"

[mcp_servers.maguyva.http_headers]
Authorization = "Bearer ${MAGUYVA_API_KEY}"

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Codex MCP 문서 →

GitHub Copilot CLI

.copilot/mcp-config.json에 추가하세요:

.copilot/mcp-config.json

{
  "servers": {
    "maguyva": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

GitHub Copilot CLI MCP 문서 →

Gemini CLI

macOS: ~/.gemini/settings.json
Windows: %UserProfile%\.gemini\settings.json
Linux: ~/.gemini/settings.json

Gemini CLI 설정(~/.gemini/settings.json)에 추가하세요:

settings.json

{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Gemini CLI MCP 문서 →

Cline

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Cline MCP 설정에 추가하세요:

cline_mcp_settings.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

이 클라이언트는 아직 커스텀 인증 헤더를 사용하는 원격 MCP 서버를 지원하지 않으므로, mcp-remote 브리지를 통해 연결합니다(Node.js / npx 필요). Maguyva는 전적으로 원격에서 실행되며 — 브리지만 로컬에서 실행됩니다.

Cline MCP 문서 →

Roo Code

macOS: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json

Roo Code MCP 설정에 추가하세요:

mcp_settings.json

{
  "mcpServers": {
    "maguyva": {
      "type": "streamable-http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Roo Code MCP 문서 →

Goose

macOS: ~/.config/goose/config.yaml
Windows: %AppData%\goose\config.yaml
Linux: ~/.config/goose/config.yaml

Goose 설정에 추가하세요:

config.yaml

extensions:
  maguyva:
    name: maguyva
    cmd: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    enabled: true
    envs:
      MAGUYVA_API_KEY: mgv_xxxx
    type: stdio

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Goose MCP 문서 →

LM Studio

LM Studio는 Agent 설정을 통해 MCP 서버를 지원합니다. Settings → Agent → MCP Servers에서 표준 mcpServers JSON 형식을 사용해 새 MCP 서버를 추가하세요. LM Studio는 stdio를 통해 MCP 서버에 연결합니다. 문서 보기 →

Continue

macOS: ~/.continue/config.json
Windows: %UserProfile%\.continue\config.json
Linux: ~/.continue/config.json

Continue 설정(~/.continue/config.json)에 추가하세요:

config.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Continue MCP 문서 →

Amazon Q Developer

macOS: ~/.aws/amazonq/mcp.json
Windows: %UserProfile%\.aws\amazonq\mcp.json
Linux: ~/.aws/amazonq/mcp.json

Amazon Q MCP 설정에 추가하세요:

mcp.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Amazon Q Developer MCP 문서 →

PyCharm

프로젝트 루트의 .ai/mcp/mcp.json에 추가하거나, Settings > Tools > AI Assistant > MCP에 붙여넣으세요:

.ai/mcp/mcp.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

PyCharm MCP 문서 →

Zed

macOS: ~/.config/zed/settings.json
Windows: %AppData%\Zed\settings.json
Linux: ~/.config/zed/settings.json

Zed 설정(~/.config/zed/settings.json)에 추가하세요:

settings.json

{
  "context_servers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Zed MCP 문서 →

Trae

프로젝트 루트의 .trae/mcp.json에 추가하세요:

.trae/mcp.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Trae MCP 문서 →

OpenCode

프로젝트 루트의 opencode.json에 추가하세요:

opencode.json

{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

OpenCode MCP 문서 →

BoltAI

macOS: ~/Library/Application Support/BoltAI/mcp_config.json

BoltAI MCP 설정에 추가하세요:

mcp_config.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

BoltAI MCP 문서 →

LibreChat

LibreChat 설정에 추가하세요:

librechat.yaml

mcpServers:
  maguyva:
    command: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    env:
      MAGUYVA_API_KEY: mgv_xxxx

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

LibreChat MCP 문서 →

Antigravity

macOS: ~/.gemini/antigravity/mcp_config.json
Windows: %UserProfile%\.gemini\antigravity\mcp_config.json
Linux: ~/.gemini/antigravity/mcp_config.json

Antigravity MCP 설정에 추가하세요:

mcp_config.json

{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Antigravity MCP 문서 →

Claude Cowork

Claude Cowork는 다른 Anthropic 클라이언트와 동일한 MCP 형식을 사용합니다:

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

mgv_xxxx를 app.maguyva.ai에서 발급받은 API 키로 교체하세요.

Claude Cowork MCP 문서 →

ChatGPT

ChatGPT는 Business, Enterprise, Edu 플랜에서 Settings → Apps → Create를 통해 원격 MCP 서버를 지원합니다. 원격 HTTPS 엔드포인트가 필요합니다 — ChatGPT는 로컬 stdio 서버를 지원하지 않습니다. 설정 방법은 OpenAI의 MCP 가이드를 참고하세요. 문서 보기 →

Warp

Warp는 Agent Mode에서 MCP 서버를 지원합니다. 설정은 Warp UI(Settings → Agent Mode → MCP Servers)를 통해 관리되며 Warp Drive를 통해 동기화됩니다. 서버를 추가할 때 표준 mcpServers JSON을 붙여넣으세요. 문서 보기 →

Maguyva는 표준 MCP를 사용합니다. 위에 자체 가이드가 없더라도, 이 프로토콜을 지원하는 클라이언트라면 무엇이든 연결할 수 있습니다. 24개 클라이언트가 문서화되어 있으며, 계속 추가되고 있습니다.

설정 검증하기#

연결한 후, 에이전트에게 몇 가지 질문을 던져보세요:

"제가 연결한 저장소는 무엇인가요?" — 연결이 작동하는지 확인합니다
"이 코드베이스에서 인증은 어떻게 처리되나요?" — 시맨틱 검색을 테스트합니다
"데이터베이스를 호출하는 모든 함수를 찾아줘" — 의존성 검색을 테스트합니다
"UserService 클래스는 무엇에 의존하나요?" — 심볼 조회를 테스트합니다

연결된 저장소의 파일 경로와 줄 번호가 포함된 결과를 볼 수 있어야 합니다. 그렇지 않다면 아래의 troubleshooting section를 확인하세요.

저장소 형식#

저장소를 지정할 때:

브랜치 지정: "owner/repo:branch" (e.g., "owner/repository:develop")
기본 브랜치: "owner/repo"

팁: repository_context(action="info", repository="...")로 저장소 해석을 확인하세요. v3 서버는 상태를 유지하지 않으므로 저장소 재정의는 한 번의 호출에만 적용됩니다.

문제 해결#

API 키 문제#

키가 mgv_ 접두사로 시작하는지 확인하세요
키가 환경에 올바르게 설정되어 있는지 확인하세요
키가 만료되지 않았는지 확인하세요

저장소를 찾을 수 없음#

저장소가 app.maguyva.ai에 연결되어 있는지 확인하세요
owner/repo 형식이 올바른지 확인하세요
저장소에 접근 권한이 있는지 확인하세요

MCP 연결 문제#

npx가 PATH에서 사용 가능한지 확인하세요
API 토큰이 유효하고 만료되지 않았는지 확인하세요
https://maguyva.tools/mcp로의 연결을 테스트하세요
클라이언트의 MCP 설정 문법을 확인하세요

다음 단계#

MCP API 레퍼런스 - 전체 API 문서
작동 방식 - 컨텍스트 최적화 이해하기
문제 해결 - 설정 및 연결 문제 해결하기