MCP, 인증, 일회성 명령

일회성 명령

모든 것이 대화인 것은 아닙니다. 아래 것들은 CLI를 실행해 출력한 것을 읽고 종료합니다 — 시간을 두고 말을 거는 프로세스가 아니라, 답이 있는 질문입니다.

await command.version();                 // '2.1.170', 판별 불가하면 null
await command.usage();                   // CLI가 출력하는 그대로의 사용량 리포트
await command.update();                  // CommandResult — 성공 여부는 설치 방식에 따라 다름
await command.describe();                // 이곳에서 유효한 모델, 에이전트, 계정, 설정
await command.supportsModel('haiku');    // boolean
await command.exec(['mcp', 'list']);     // 탈출구

메서드	알아둘 것
`version()`	throw하지 않고 `null`을 냅니다. “어느 버전인가”는 호스트가 무엇을 제공할지 결정하려고 던지는 질문이고, 답하지 않는 CLI는 처리해야 할 하나의 사실입니다.
`describe()`	자신만의 일회성(ephemeral) 세션에서 실행되므로, CLI에게 스스로를 설명하라고 요청해도 하던 일을 방해하거나 사용자의 트랜스크립트에 남지 않습니다. 타임아웃 시 `null` — 오래된 CLI는 이 요청을 지원하지 않을 수 있습니다.
`supportsModel(m)`	가능한 한 가장 저렴한 턴을 보내고 되돌아오는지 보는 방식으로 묻습니다. 사용 권한은 계정과 조직에 달려 있으므로, 정직한 검사는 실제로 시도해 보는 것입니다. 요청 비용이 드니 답을 캐시하세요.
`exec(args)`	CLI는 이 라이브러리가 감싸는 속도보다 빠르게 서브커맨드를 늘립니다. 인자는 셸을 거치지 않고 전달되므로, 인용과 메타문자가 리터럴로 유지됩니다.

인증

const status = await command.auth.status();
status.loggedIn;  // boolean
status.raw;       // 계정이 스스로를 기술한 내용, 손대지 않은 그대로
status.text;      // 사람이 읽는 출력, JSON이 없을 때를 위해

로그인은 답이 있는 질문이라기보다 사용자와 나누는 대화이므로, 살아 있는 세션을 반환합니다.

const login = command.auth.login('console');  // 또는 기본값인 'claudeai'

login.onUrl((url) => showToUser(url));
login.onFinished((code) => console.log('sign-in exited', code));

login.submitCode(pastedCode);
login.cancel();

MCP 서버

아래 각각은 문서화된 CLI 명령을 실행하고 그 출력을 파싱합니다.

await command.mcp.list();          // McpListEntry[] — 이름과 상태
await command.mcp.get('playwright'); // McpServer | null — transport 세부까지
await command.mcp.all();           // 모든 서버를 전부: list한 뒤 각각을 describe

await command.mcp.add('playwright', {
  command: 'npx',
  args: ['@executeautomation/playwright-mcp-server'],
}, { scope: 'user' });

await command.mcp.remove('playwright', { scope: 'user' });

메서드	알아둘 것
`list()`	이름과 상태만 — `claude mcp list`가 보고하는 것이 그것뿐입니다. 명령이 실패하면 `[]`를 반환하는데, MCP가 설정되어 있지 않은 것이 평범한 경우이고 출력만으로는 실패와 구별되지 않기 때문입니다.
`all()`	서버당 두 개의 명령이므로 눈에 띄게 느립니다. transport 세부가 실제로 필요할 때에만 값어치를 합니다.
`add()`	“이미 존재함”은 에러로 올리지 않고 하나의 상태로 받아들입니다. CLI는 실패를 종료 코드가 아니라 출력으로 보고합니다.
`remove()`	project 및 local 스코프 서버에는 scope를 넘기세요. 그러지 않으면 CLI가 엉뚱한 설정 파일을 뒤지고 아무것도 찾지 못합니다.

설정은 하나의 위치 인자로 전달되는데, 이것이 이 모든 것이 셸을 거치지 않는 이유입니다 — win32에서 cmd.exe는 JSON의 따옴표와 &, |, 공백을 토큰화해 설정을 망가뜨리고 인젝션 표면을 열게 됩니다.

다음으로 볼 것

크로스 플랫폼 — Windows에서 mcp add-json을 온전히 지켜내는 캐럿 이스케이프.