sbx mcp auth — MCP 서버 인가

sbx mcp auth — MCP 서버 인가

sandbox mcp의 하위 명령인 sbx mcp auth는 호스팅된 MCP 컨트롤 플레인을 통해 등록된 원격 MCP 서버를 인가해요. 서버별로 인가하거나 재인가하고, 스코프를 조정할 수 있어요.

출처: 문서

본문

설명 (Description)

호스팅된 MCP 컨트롤 플레인을 통해 등록된 원격 MCP 서버를 인가해요.

명령은 sbx login의 Docker Hub 계정을 요청 주체(principal)로 사용해요. 사용자·테넌트 신원은 컨트롤 플레인이 파생하고 요청 본문에는 보내지 않아요.

sbx mcp auth 를 실행하면 서버 하나를 인가하거나 재인가해요. 저장된 자격증명이 만료됐으면 sbx는 먼저 컨트롤 플레인에 갱신을 요청하고, 갱신이 사용자 동의를 필요로 할 때만 인터랙티브 OAuth로 폴백해요.

OAuth를 시작하지 않고 호스팅 자격증명 상태를 검사하려면 sbx mcp auth status를, 로컬 MCP 서버 등록은 제거하지 않고 호스팅 자격증명만 제거하려면 sbx mcp auth rm을 사용해요.

--scope(반복 가능)를 전달하면 이번 실행에서 특정 스코프 세트를 인가하고 sbx mcp add 시점에 기록된 기본값을 덮어써요. 우선순위는 --no-scope > 명시적 --scope > 기록된 기본값 > 리소스가 요구한다고 말하는 스코프 세트(RFC 9728 메타데이터 또는 WWW-Authenticate 챌린지에서) > 광고된 openid, email, profile, offline_access 중 해당하는 것. 다른 광고된 스코프는 이 폴백에서 제외돼요. 선택된 스코프가 없으면 scope 매개변수가 생략되어 authorization server가 자체 기본 grant를 적용해요.

필수 세트를 게시하는 리소스는 플래그 없이도 그 세트가 요청되고, 동의 블록은 그 세트를 파생된 것으로 표시해요. --no-scope를 전달하면 모든 스코프 폴백을 억제하고 서버의 기본 grant를 요청해요.

선택한 스코프는 authorization server의 RFC 8414 scopes_supported와 리소스의 RFC 9728 메타데이터 양쪽에 대해 확인돼요. 어느 쪽에도 없는 스코프는 경고를 출력하지만 여전히 요청돼요. 어느 문서도 스코프를 게시하지 않으면 요청은 주어진 대로 받아들여져요. 멤버십은 약속이 아니에요: scopes_supported는 서버가 지원하는 것이지 이 클라이언트에게 승인할 것이라는 게 아니므로, 광고된 스코프도 동의 시점에 거부될 수 있어요. 로컬 데이터 플레인 모드에서 거부는 요청된 세트, 광고된 세트, 서버가 명명한 스코프, 더 좁은 재시도 명령을 출력해요. 호스팅 컨트롤 플레인은 인가가 실패했거나 타임아웃됐다는 것만 보고해요.

기존 또는 방금 완료된 인가에 대해 부여된(GRANTED) 세트 — authorization server가 실제로 건네준 것 — 가 상태와 함께 보고돼요. authorization server는 요청한 것보다 덜 부여할 수 있고, 세트를 전혀 다시 말하지 않으면 RFC 6749 §5.1에 따라 요청된 세트가 곧 그 세트예요.

스코프 값은 URN 모양(urn:ietf:params:oauth:scope:mail)이거나 URL 모양(https://www.fastmail.com/dev/mcp)일 수 있고, 둘 다 따옴표가 필요 없어요.

명령 (Commands)

| 명령 | 설명 | | sbx mcp auth rm | MCP 서버 OAuth 자격증명 제거 | | sbx mcp auth status | MCP 서버 OAuth 상태 표시 |

옵션 (Options)

| 옵션 | 기본값 | 설명 | | --all | | 모든 등록된 OAuth 서버에 적용 | | --format | text | 출력 형식: "text" 또는 "json" | | --json | | JSON 형식 출력 (--format json의 별칭) | | --no-scope | | 이번 실행에서 스코프를 전혀 요청하지 않아 authorization server가 자체 기본 grant를 적용하게 함. 기록된 필수·OIDC 폴백 스코프를 억제; --scope와 함께 쓸 수 없음 | | --scope | | 이번 실행에서 인가할 OAuth 스코프 (반복 가능; 기록된 기본값을 덮어씀; 인식되지 않은 스코프는 경고하지만 여전히 요청됨). --scope도 기록된 기본값도 없으면 리소스 자체가 요구하는 스코프 세트가 요청되고, 그중 아무것도 없으면 광고된 openid, email, profile, offline_access 중 해당하는 것이 요청됨; 다른 광고된 스코프는 이 폴백에서 제외 | | --verbose | | 인가 폴링 진행 출력 |

전역 옵션 (Global options)

| 옵션 | 기본값 | 설명 | | --cloud | | 로컬 sandboxd 대신 Docker Cloud Sandboxes API로 디스패치 (점점 더 많은 동사 지원 — 현재 목록은 'sbx --cloud --help' 실행) | | -D, --debug | | 디버그 로깅 활성화 |

예시 (Examples)

sbx mcp auth status --all
sbx mcp auth status notion
sbx mcp auth rm --all
sbx mcp auth rm notion
sbx mcp auth --all
sbx mcp auth notion
sbx mcp auth notion --scope read --scope write
sbx mcp auth notion --no-scope

더 알아보기 (Learn more)

  • 서버 등록은 sbx mcp add, 스코프 기록은 그 --scope 옵션을 참고해요.
  • 자격증명 상태·제거는 sbx mcp auth status / sbx mcp auth rm을 참고해요.