Odysseus AI MCP: 서버, OAuth 설정과 문제 해결

Odysseus 작업 공간에서 MCP가 의미하는 것

Model Context Protocol(MCP)은 AI 애플리케이션이 서버가 제공하는 도구를 검색하고 호출하게 하는 프로토콜입니다. 서버는 문서 읽기, 캘린더 조회, 웹 검색, 작업 생성 같은 기능을 제공할 수 있습니다. 서버가 입력 스키마와 실제 동작을 정의하고, 호스트는 언제 연결할지, 어떤 도구를 보여줄지, 사용자의 승인이 필요한지를 관리합니다.

Odysseus AI MCP를 설정할 때 모델, 작업 공간과 MCP 프로세스를 하나의 신뢰 영역으로 취급하면 안 됩니다. 모델이 내 컴퓨터에서 실행되어도 MCP 서버가 호스팅된 API로 검색어를 보낼 수 있습니다. Odysseus 화면이 로컬이어도 원격 서버는 다른 네트워크에 있을 수 있습니다. 자격 증명이나 개인 파일을 보내기 전에 이 경계를 문서로 남기세요.

먼저 MCP가 켜졌는지만 확인하지 마세요. 어떤 호스트가 연결을 소유하는지, 어떤 서버가 등록됐는지, 어떤 도구가 공개됐는지, 결과가 어디로 돌아오는지를 확인합니다. 서버가 보이지 않는 문제, OAuth 콜백 거부, 잘못된 도구 응답 형식을 서로 다른 문제로 진단할 수 있습니다.

설정 전 인증, 관리자 권한과 네트워크 경계 확인

Odysseus 공식 설정 자료에서는 MCP 관리와 API 토큰 관리가 관리자 영역에 있습니다. 권한이 있는 계정으로 로그인하고 웹 프로세스가 같은 환경 변수를 읽는지 확인하세요. 브라우저에서 채팅이 작동한다고 해서 서버 프로세스가 MCP 엔드포인트에 접근할 수 있다는 뜻은 아닙니다.

테스트 중에도 인증을 유지하세요. 관리자 경로를 잠깐 공개하거나 모델 포트를 외부에 열면 다시 닫는 일을 놓치기 쉽습니다. Docker에서 Odysseus를 실행한다면 콜백과 서비스 이름이 호스트 브라우저뿐 아니라 컨테이너 네트워크에서도 해석되어야 합니다. DNS, TLS, 방화벽과 허용된 출처를 확인하세요.

처음에는 범위를 작게 잡습니다. 서버 하나, 읽기 전용 도구 하나, 민감한 데이터가 없는 작업 공간과 예상 결과를 준비하세요. 등록 이름, 전송 방식, 명령 또는 엔드포인트, 필요한 환경 변수와 자격 증명 소유자를 기록하면 첫 테스트를 안전하게 되돌릴 수 있습니다.

내장 MCP 서버와 npx 캐시 확인

Odysseus는 내장 MCP 서버를 시작점으로 설명합니다. 그래도 내장이라는 표시만으로 서버가 정상이라고 판단할 수는 없습니다. 실행 환경에 명령이 존재하고 예상 인자로 프로세스가 시작되며 필요한 런타임에 접근할 수 있는지 확인해야 합니다.

일부 예시는 로컬 캐시의 npx 패키지를 사용합니다. 처음 실행할 때 패키지를 확인하고 이후에는 캐시된 사본을 사용할 수 있습니다. 허용된 패키지와 버전을 기록하세요. 네트워크가 분리된 호스트라면 승인된 캐시를 준비하거나 로컬 명령을 설치하는 편이 반복적인 registry 연결 실패보다 낫습니다.

가장 안전한 첫 확인은 도구 검색입니다. 서버를 시작하고 출력과 오류 로그를 읽은 뒤 Odysseus가 도구 이름과 입력 스키마를 실행 없이 보여주는지 확인하세요. 위험한 동작을 하기 전에 프로토콜 핸드셰이크를 검증할 수 있습니다.

1. 위험이 작은 등록 선택

   테스트 리소스나 읽기 전용 목록을 선택하고 셸과 넓은 파일 경로는 피합니다.

2. 같은 실행 환경 확인

   Odysseus와 같은 이미지나 컨테이너에서 명령을 실행하고 stderr의 비밀을 제거합니다.

3. npx 해석 확인

   캐시 또는 허용된 registry에 접근되는지와 해석된 버전을 확인합니다.

4. 호출 전에 목록 확인

   승인하기 전에 이름, 스키마와 읽기 또는 쓰기 능력을 검토합니다.

npx -y @playwright/mcp@latest --help

docker compose logs --tail=120 odysseus

OAuth 원격 MCP 서버 추가

OAuth를 사용하는 원격 MCP 서버는 전송과 핸드셰이크에 신원 교환 단계를 더합니다. Odysseus 호스트가 권한 부여를 시작하고 사용자가 범위를 승인하면 제공자가 브라우저를 등록된 콜백으로 돌려보냅니다. 컨테이너 안의 localhost는 원격 브라우저가 돌아올 주소가 될 수 없습니다.

Odysseus 설정 안내는 OAuth 원격 MCP 서버에 OAUTH_REDIRECT_BASE_URL을 사용한다고 설명합니다. 배포 환경에서 설정하고 스킴과 경로를 안정적으로 유지한 뒤 환경 변수를 읽는 서비스를 재시작하세요. client secret을 페이지, 프롬프트, 스크린샷 또는 버전 관리 JSON에 넣지 마세요. redirect와 scope는 제공자 문서를 따릅니다.

승인 뒤에는 서버 등록과 토큰 범위를 확인합니다. 브라우저가 성공적으로 돌아온 것은 신원 교환만 증명하며 상위 API에 도달하거나 모든 도구를 켜도 된다는 뜻은 아닙니다. 읽기 호출 하나로 시작해 스키마와 비교하고 주소나 범위가 다르면 권한을 취소하세요.

1. 콜백 확인

   서버 문서에서 정확한 HTTPS 경로와 scope를 기록합니다.

2. OAUTH_REDIRECT_BASE_URL 설정

   배포 환경에 추가하고 값을 읽는 프로세스를 재시작합니다.

3. Odysseus에서 승인

   Odysseus에서 흐름을 시작하고 예상 host와 path로 돌아오는지 확인합니다.

4. 첫 호출 제한

   도구를 나열하고 읽기 도구를 선택해 응답을 스키마와 비교합니다.

OAUTH_REDIRECT_BASE_URL=https://mcp.example.com/oauth/callback

반복 가능한 테스트 순서 사용

Odysseus AI MCP 서버를 추가하거나 변경할 때마다 같은 순서를 사용하세요. 작업 공간 상태, 서버 프로세스, 핸드셰이크, 알고 있는 입력으로 한 번 읽기 순서입니다. 이렇게 하면 추론, 전송, 권한과 제공자 문제를 하나의 연결 오류로 뭉뚱그리지 않습니다.

서버와 도구 이름, 인자 형식, 상태, 실행 시간과 비밀이 없는 요청 ID를 기록합니다. 토큰, 인증 헤더, 개인 문서 내용과 전체 프롬프트는 기록하지 마세요. 실패하면 스키마와 가린 샘플만 보관합니다.

스모크 테스트는 되돌릴 수 있어야 합니다. fixture 읽기, 테스트 캘린더 목록, 민감하지 않은 엔드포인트 조회를 사용하세요. 승인 동작과 서버 소유자가 분명해질 때까지 이메일 전송이나 운영 데이터 변경은 하지 않습니다.

1. Odysseus 상태 확인

   MCP 화면을 열기 전에 웹 프로세스와 의존 서비스가 정상인지 봅니다.

2. 서버 프로세스 확인

   명령, 전송 방식, 환경과 엔드포인트를 로그와 비교합니다.

3. 도구와 스키마 목록

   이름, 필수 인자, 읽기와 쓰기 능력을 확인합니다.

4. 제한된 읽기 실행

   무해한 리소스를 사용하고 응답을 스키마와 비교합니다.

5. 등록 삭제 또는 축소

   운영하지 않을 테스트 등록을 지우고 필요 없는 범위를 줄입니다.

연결할 수 없는 서버, 권한과 오래된 등록 수정

실패한 계층부터 확인하세요. 프로세스가 시작되지 않으면 명령, 패키지, 작업 폴더와 환경을 확인합니다. 시작되지만 도구가 보이지 않으면 전송과 핸드셰이크를 확인합니다. 도구는 보이지만 호출이 실패하면 인자, OAuth 범위, quota와 상위 엔드포인트를 살펴봅니다. 모델이 도구를 무시한다면 호스트의 tool calling 문제일 수도 있습니다.

컨테이너 네트워크는 MCP 오류를 잘못 판단하게 만드는 원인입니다. 노트북 브라우저에서 해석되는 이름이 컨테이너 안에서 해석된다는 보장은 없습니다. Odysseus와 같은 runtime에서 엔드포인트를 시험하고 인증서와 외부 통신 정책을 확인하며 맞는 서비스 이름이나 host gateway를 사용하세요. 모델과 서비스 포트는 기본적으로 외부에 공개하지 않습니다.

오래된 등록도 흔한 원인입니다. 명령, 콜백 또는 환경 변수를 바꾼 뒤 설정을 소유한 프로세스를 재시작하고 중복 항목을 지웁니다. 화면의 상태만 믿지 말고 실제 이름과 endpoint를 로그와 비교하세요. 로그나 터미널 기록에 비밀이 나타났다면 이전 OAuth 권한을 취소하고 자격 증명을 교체합니다.

제공자가 형식은 맞지만 잘못된 내용을 반환하면 원시 도구 결과와 프롬프트 경계를 확인하세요. 가져온 페이지와 문서는 신뢰하지 않는 데이터로 취급해야 하며, 그 안의 지시가 사용자 요청이나 승인 정책을 덮어쓰게 두면 안 됩니다.

토큰과 네트워크 보안 체크리스트 적용

MCP는 기능을 조합하게 하므로 작업을 해결하는 가장 작은 구성이 안전합니다. 필요한 폴더, 도메인과 동작만 허용하세요. 조사에는 읽기 전용을 우선하고 쓰기에는 화면 승인을 요구하며 OAuth와 API 자격 증명 교체 계획을 세웁니다. 로컬 프로세스도 외부 제공자에게 데이터를 보낼 수 있습니다.

배포 경계를 비밀 정보만큼 보호하세요. 인증을 유지하고 원격 콜백에 HTTPS를 사용하며 관리자 접근을 제한하고 모델과 서비스 포트를 공개하지 않습니다. 도구가 사설 네트워크를 필요로 한다면 필요한 host와 port만 허용합니다. 비밀을 저장소, 프롬프트, 캡처, URL, 오류 보고서에 두지 마세요.

삭제 방법도 기록하세요. 누가 서버를 추가했는지, 목적은 무엇인지, 무엇에 접근하는지, 어떻게 취소하는지를 남깁니다. 긴급해지기 전에 취소 흐름을 시험하면 제공자, 컨테이너와 OAuth 등록이 바뀌어도 Odysseus AI MCP 구성을 감사하기 쉽습니다.

• 첫 연결에는 테스트 계정 또는 테스트 작업 공간 사용
• 명령과 패키지 버전을 검토하고 추적 가능하게 유지
• OAuth와 API 자격 증명을 환경 또는 비밀 관리자에 저장
• 폴더, 도메인과 도구를 필요한 만큼만 허용
• 로그에서 토큰, 개인 문서와 전체 프롬프트 마스킹
• 실수로 노출했을 때 삭제와 교체 절차 기록