MCP OAuth 인증
OAuth 2.1을 사용하여 사용자 위임 액세스가 필요한 MCP 서버에 Bob Shell을 연결합니다. Bob Shell이 인증 및 토큰 갱신 프로세스를 관리하므로 토큰을 수동으로 관리할 필요가 없습니다.
일반적인 MCP 구성은 MCP 서버 구성을 참조하세요.
개요
리포지토리, 클라우드 리소스, 기업 서비스 등에 사용자를 대신하여 액세스하는 MCP(Model Context Protocol) 서버에 Bob Shell을 연결할 수 있습니다. 이러한 서버는 OAuth 2.1을 사용하여 로그인하고 액세스를 승인합니다.
Bob Shell은 인증 흐름을 직접 관리합니다. OAuth가 필요한 서버를 구성하면 Bob Shell이 기본 브라우저에서 인증 창을 엽니다. 로그인하고 권한을 승인한 후 Bob Shell은 자격 증명을 수동으로 처리할 필요 없이 액세스 토큰을 저장하고 갱신합니다.
다음과 같은 경우 OAuth를 사용하세요:
- 개인 또는 기업 사용자 계정과 연결된 리소스에 액세스해야 하는 경우
- 서버가 자동 토큰 갱신이 필요한 단기 토큰을 사용하는 경우
- 구성 파일에서 정적 자격 증명과 시크릿을 제외하려는 경우
만료되지 않는 정적 API 토큰이나 개인 액세스 토큰이 이미 있는 경우 headers에 Bearer 토큰을 대신 사용할 수 있습니다.
인증 흐름 작동 방식
headers또는env자격 증명 없이 구성 파일에 원격 MCP 서버 URL을 추가합니다.- Bob Shell이 서버에 연결하면 OAuth 요구 사항을 감지합니다.
- Bob Shell이 브라우저 로그인 창을 열어 요청된 권한을 확인하고 액세스를 승인합니다.
- Bob Shell이 인증 토큰을 받아 세션 전반에 걸쳐 안전하게 저장합니다.
- Bob Shell이 토큰이 만료되기 전에 자동으로 갱신하여 중단 없이 작업할 수 있습니다.
Bob Shell Authorization Server MCP Server
| | |
|-- connect to server ---------->| |
|<-- OAuth metadata (401) -------| |
|-- open auth prompt ----------->| |
| (user signs in & consents) | |
|<-- authorization code ---------| |
|-- exchange for tokens -------->| |
|<-- access + refresh tokens ----| |
|-- authenticated requests ---------------------------------> |
| (auto-refresh when needed) |OAuth 지원 서버 구성
MCP 서버는 전역 구성(~/.bob/mcp_settings.json) 또는 프로젝트 구성(.bob/mcp.json)에서 설정할 수 있습니다.
최소 구성 (자동 검색)
MCP 서버가 자동 OAuth 메타데이터 검색을 제공하는 경우 url만 지정하면 됩니다:
{
"mcpServers": {
"my-oauth-server": {
"url": "https://mcp.example.com/mcp"
}
}
}Bob Shell이 연결 시 OAuth 요구 사항을 감지하고 브라우저 로그인 프로세스를 안내합니다.
커스텀 OAuth 매개변수
ID 공급자가 사전 등록된 클라이언트 ID, 커스텀 스코프 또는 클라이언트 시크릿을 요구하는 경우 oauth 객체를 구성합니다:
{
"mcpServers": {
"my-oauth-server": {
"url": "https://mcp.example.com/mcp",
"oauth": {
"enabled": true,
"clientId": "your-client-id-from-idp",
"clientSecret": "your-client-secret-if-required",
"scope": "mcp:connect read:data"
}
}
}
}구성 속성
| 속성 | 유형 | 설명 |
|---|---|---|
url | string | 원격 MCP 엔드포인트 URL (필수). |
oauth.enabled | boolean | OAuth를 비활성화하려면 false, 요구하려면 true로 설정합니다. Authorization 헤더가 없으면 기본적으로 활성화됩니다. |
oauth.clientId | string | ID 공급자가 발급한 사전 등록된 OAuth 클라이언트 ID. |
oauth.clientSecret | string | 인증 서버가 기밀 클라이언트에 요구하는 경우의 OAuth 클라이언트 시크릿. |
oauth.scope | string | 요청할 OAuth 스코프의 공백으로 구분된 목록. |
MCP 서버 구성에 정적 Authorization 헤더를 추가하면 OAuth가 비활성화됩니다. Authorization 헤더가 있으면 Bob Shell은 OAuth 흐름을 시작하지 않습니다. OAuth가 활성화되면 Bob Shell은 요청을 보내기 전에 정적 Authorization 헤더를 제거합니다. 서버당 하나의 인증 방법만 사용하세요.
ID 공급자에 Bob 등록
연결 전에 ID 공급자(IdP)가 Bob을 클라이언트 애플리케이션으로 등록하도록 요구하는 경우 다음 애플리케이션 설정을 사용합니다:
| 설정 | 값 |
|---|---|
| 애플리케이션 또는 클라이언트 유형 | Public, Native, 또는 Loopback (PKCE를 사용한 인증 코드) |
| 리디렉션 URI | http://127.0.0.1:33418/callback |
| 추가 리디렉션 URI | http://127.0.0.1:33419/callback ~ http://127.0.0.1:33427/callback (포트 33418이 사용 중인 경우 권장) |
| 부여 유형 | 인증 코드 (authorization_code) 및 갱신 토큰 (refresh_token) |
| 스코프 | MCP 서버 문서에 지정된 스코프 |
발급된 클라이언트 ID를 구성 파일의 oauth.clientId에 복사합니다.
프롬프트가 표시되면 인증
OAuth 지원 서버에 처음 연결할 때:
- 인증 프롬프트와 함께 브라우저 창이 열립니다.
- 서버가 요청하는 권한을 검토합니다.
- 계정에 로그인하고 액세스를 승인합니다.
- Bob Shell이 자격 증명을 저장하고 자동으로 서버 도구에 연결합니다.
문제 해결
인증 프롬프트가 열리지 않음
- 구성에서 서버를 비활성화로 표시하지 않았는지 확인합니다.
- 구성 파일의
headers에 정적Authorization헤더가 포함되어 있지 않은지 확인합니다. - Bob Shell을 다시 시작하여 연결을 다시 시작합니다.
- 브라우저나 방화벽이
127.0.0.1의 로컬 루프백 연결을 차단하지 않는지 확인합니다.
ID 공급자가 리디렉션 URI 불일치 오류를 반환함
- ID 공급자 클라이언트 등록에
http://127.0.0.1:33418/callback이 포함되어 있는지 확인합니다. - 포트 33418이 사용 중인 경우
33419부터33427까지 추가 포트를 등록합니다.
인증은 성공하지만 서버가 연결에 실패함
- 서버 URL이 올바르고 네트워크에서 액세스할 수 있는지 확인합니다.
- 로그인 단계에서 필요한 모든 스코프를 승인했는지 확인합니다.
- 필수 사용자 역할 또는 권한에 대한 서버 로그 또는 문서를 검토합니다.
토큰이 자주 만료되고 재인증이 필요함
- 인증 서버가 갱신 토큰을 발급하는지 확인합니다.
- 조기 토큰 만료를 방지하기 위해 시스템 시계가 동기화되어 있는지 확인합니다.
로그아웃하거나 계정을 전환하려는 경우
구성 파일에서 서버 항목을 제거하거나 이름을 바꾼 후 다시 추가합니다. Bob Shell이 이를 새 서버로 처리하고 다음 연결 시 로그인을 요청합니다.