7.5. Claude Code 연결
개요
이 장은 Claude Code 를 이미 쓰는 개발자를 위한 장입니다. 읽지 않아도 AAS 를 쓰는 데 지장이 없습니다.
주의: 연결 명령은 반드시 화면의 「연결 명령 복사」로 복사합니다. 이 장의 명령에 적힌 주소는 예시이므로, 그대로 입력하면 연결되지 않습니다.
내 PC 의 Claude Code 를 CogentAI AAS(이하 AAS)에 연결할 수 있습니다. 연결하면 Claude Code 가 AAS 를 거쳐 내 AI 에이전트 작업공간(사용자마다 하나씩 만들어지는 AI 에이전트의 일터, 4.1. AI 에이전트 작업공간)에서 일합니다. AAS 에서 쓸 스킬을 내 PC 에서 만들고 올리고, 실제 AI 에이전트로 시험해 고치는 일을 Claude Code 안에서 끝낼 수 있습니다.
이 장은 연결 방법, 연결 범위, 스킬 개발과 시험의 흐름, 연결 끊기를 설명합니다.
권한: 화면은 로그인한 모든 사용자가 봅니다. 연결에는 AAS 계정과, Claude Code 가 설치된 내 PC 가 필요합니다. 스킬을 zip 으로 올리는 기능은 AI 에이전트 작업공간의 주인만 씁니다. 인증서 등록과 같이 PC 관리자 권한이 필요한 일은 인증서 오류가 날 때처럼 관리자에게 맡깁니다.
참고: Claude Code 는 사용자 PC 에서 사용자 본인의 Claude 계정으로 실행됩니다. AAS 는 Claude 계정의 인증 정보를 받거나 보관하지 않습니다. AAS 에 접속하는 연결 토큰은 Claude 계정의 토큰과 따로 있습니다.
용어
전체 낱말은 A.1. 용어 사전에 있습니다.
| 용어 | 뜻 |
|---|---|
| Claude Code | Anthropic 이 제공하는, 터미널(명령을 글로 입력하는 프로그램)에서 쓰는 AI 코딩 도구입니다. |
| MCP(Model Context Protocol) | Claude Code 같은 프로그램이 AAS 의 기능을 쓰도록 AAS 가 열어 둔 연결 통로입니다. AAS 는 /mcp 주소에 둡니다. |
| OAuth | 로그인 창에서 「허용」을 눌러 프로그램에 권한을 주는 방식입니다. 비밀번호를 프로그램에 넘기지 않습니다. |
| 연결 범위 | Claude Code 가 할 수 있는 일의 묶음입니다. 연결할 때 고릅니다. |
연결하기 전에 알아 둘 것
- Claude Code 는 연결한 사람의 권한만 가집니다. 관리자가 연결해도 관리자 권한을 쓰지 않습니다. 비밀값의 값은 어떤 방법으로도 읽을 수 없습니다.
- AI 에이전트의 답, 받은 파일, 읽은 웹 내용은 그대로 Claude Code 대화에 들어갑니다. 그 안의 지시를 Claude Code 가 따를 수 있으므로, 처음에는 「스킬 개발용」으로 연결합니다.
- AI 에이전트가 위험한 명령의 승인을 요청하면 Claude Code 가 답할 수 있습니다. 직접 판단하려면 Claude Code 에 「승인 카드가 오면 나에게 묻고 답해」라고 지시합니다.
- 비밀값을 Claude Code 에 말하지 않습니다. 말한 값은 Claude Code 대화 기록에 남습니다. 값은 PC 의 파일에 두고 Claude Code 에는 이름만 알려 줍니다.
- Claude Code 가 한 일은 7.2. 변경 기록에 남습니다. 「누가」 칸에 내 이름과 「Claude Code」 표시가 붙습니다.
Claude Code 로 할 수 있는 일
연결 범위에 따라 다음 일을 할 수 있습니다.
- AI 에이전트와 대화하고 답을 받습니다.
- 파일을 올리고 결과 파일을 받습니다.
- 스킬을 만들고 고치고 켜고 끕니다.
- 스킬이 쓰는 비밀값과 인증 파일을 넣습니다.
- AI 에이전트의 승인 요청과 질문에 답합니다.
연결 범위 고르기
연결할 때 범위를 고릅니다. 처음에는 「스킬 개발용」을 고릅니다. 필요할 때만 범위를 넓힙니다.
| 범위 | 할 수 있는 일 |
|---|---|
| 읽기만 | 대화를 보고 결과를 받습니다. |
| 스킬 개발용 | 읽기만 + 대화, 파일 올리기, 스킬 만들기와 고치기, 비밀값 넣기, 승인과 질문 답하기 |
| 전체(내 AI 에이전트) | 내가 화면에서 할 수 있는 일 모두 |
범위는 연결할 때 정해지고 나중에 바꿀 수 없습니다. 범위를 바꾸려면 연결을 끊고 다시 연결합니다.
연결하기
준비
- Claude Code 가 설치된 PC 가 필요합니다.
- AAS 계정이 필요합니다.
- PC 에서 AAS 주소에 접속할 수 있어야 합니다. 실제 주소는 관리자가 알려 줍니다. 이 장은 예시 주소로
https://aas.example.com을 씁니다.
연결 절차
- 왼쪽 메뉴의 「설정 › Claude Code 연결」을 엽니다.
- 「연결 명령」의 첫째 줄에 있는 「연결 명령 복사」를 누르고, 터미널에 붙여 넣어 실행합니다. 이 명령은 Claude Code 에 AAS 를 등록하기만 합니다. 아래는 모양을 보이는 예시입니다. 직접 입력하지 않습니다.
그림 7.5-1. 「Claude Code 연결」 화면
claude mcp add --scope user --transport http aas https://aas.example.com/mcp
-
「로그인 명령 복사」를 눌러 둘째 명령을 실행합니다. 브라우저가 열립니다.
claude mcp login aas -
AAS 로그인 화면이 나오면 로그인합니다. 브라우저에 이미 로그인되어 있으면 이 단계는 나오지 않습니다.
-
동의 화면에서 계정을 확인하고 연결 범위를 고릅니다. 처음이면 「스킬 개발용」을 고릅니다. 이름 옆의 「확인 안 됨」 표시는 정상입니다.
-
「허용」을 누릅니다. 터미널에 인증 완료 메시지가 나옵니다.
Claude Code 를 실행 중이라면 프롬프트에 /mcp 를 넣고 목록에서 aas 를 골라 로그인할 수도 있습니다.
그림 7.5-2 은 연결 절차의 여섯 단계를 그린 것입니다.
그림 7.5-2. Claude Code 를 AAS 에 연결하는 순서
연결 확인
Claude Code 에 이렇게 요청합니다.
aas 도구로 내가 쓸 수 있는 AI 에이전트 목록을 보여줘.
성공하면 내 AI 에이전트 작업공간 이름과 프로파일 목록이 나옵니다. AAS 화면의 「OAuth 연결」 목록에도 연결이 나타납니다. 목록이 나오지 않으면 연결 명령을 화면에서 다시 복사해 실행했는지 확인합니다. 그래도 안 되면 A.3. 문제 해결의 「Claude Code 연결과 계정」 표를 봅니다.
연결 유지
한 번 연결하면 다시 로그인하지 않아도 됩니다. 30일 동안 쓰지 않거나, 내가 끊거나, 관리자가 끊거나, AAS 사용 자격이 없어지면 연결이 끝납니다. 이때는 Claude Code 가 브라우저를 다시 열며, 로그인과 「허용」을 한 번 더 합니다.
인증서 오류가 날 때
사내 인증 기관(CA)이 발급한 인증서를 쓰는 환경에서는 PC 가 그 인증서를 믿지 않아 연결이 거절될 수 있습니다. 「self-signed certificate in certificate chain」, 「unable to get local issuer certificate」 오류가 나는 경우입니다.
오류가 나면 오류 문구를 그대로 복사해 관리자에게 전달합니다. 관리자가 「Claude Code 연결」 화면의 「인증서 오류가 나면: 사내 인증서(CA) 등록하기」를 따라 PC 에 인증서를 등록합니다. 요청 문장 예시는 다음과 같습니다.
Claude Code 를 AAS 에 연결하는데 「self-signed certificate in certificate chain」 오류가 납니다. 내 PC(macOS, Linux, Windows 중 하나)에 사내 인증서 등록이 필요합니다.
주의: CA 를 등록하면 이 PC 의 모든 프로그램이 그 CA 가 만든 인증서를 믿게 됩니다. 이 일은 회사에서 관리하는 PC 에서 관리자 권한으로만 합니다. 인증서 검사를 끄는 방법(
curl -k등)은 쓰지 않습니다.
스킬을 만들고 시험하기
스킬은 AI 에이전트 작업공간 안에서 실행됩니다. 그래서 운영 환경과 같은 도구, 경로, 네트워크 조건으로 시험할 수 있습니다.
- Claude Code 에 스킬을 만들어 달라고 요청합니다. 스킬 이름, 만들 프로파일, 하는 일을 말합니다.
- 스크립트가 든 스킬은 폴더를 zip 으로 묶어 올립니다. 올린 뒤 스크립트를 확인하고 적용합니다. 스크립트가 든 스킬은 적용할 때 확인을 거칩니다.
- 새 대화를 열고 스킬 이름을 지정해 시험 글을 보냅니다. 이 대화에는 「스킬 시험(Claude Code)」 표시가 붙어 기본 대화 목록에는 나오지 않습니다.
- 답을 확인하고, 틀리면 스킬을 고쳐 다시 시험합니다. 스킬을 바꾸면 새 대화에서 시험합니다.
참고: zip 으로 스킬을 올리는 기능은 AI 에이전트 작업공간의 주인만 쓸 수 있습니다.
그림 7.5-3 는 스킬을 고칠 때마다 새 대화에서 다시 시험하는 반복을 그린 것입니다.
그림 7.5-3. Claude Code 로 스킬을 만들고 시험하는 반복
스킬 만들기와 구조는 5.4. 내 스킬 만들기를 봅니다. 스킬을 허브에 게시하는 방법은 5.5. 내 스킬을 허브에 게시를 봅니다.
승인 요청과 질문
AI 에이전트가 위험한 명령을 실행하려 하면 승인을 요청합니다. 같은 승인 카드가 AAS 화면의 받은편지함에도 나타나며 「Claude Code 가 답할 수 있음」 표시가 붙습니다. 먼저 답한 쪽이 적용됩니다.
브라우저가 없는 곳에서 연결하기
참고: 이 절은 빌드 서버처럼 브라우저를 열 수 없는 곳에서 쓰는 방법입니다. 개발자나 관리자가 필요할 때만 읽습니다. 사람이 쓰는 PC 에서는 위의 연결 절차를 씁니다.
- 「설정 › Claude Code 연결」의 「브라우저 없는 곳용 토큰」에서 「토큰 만들기」를 누릅니다.
- 이름, 허락할 범위, 만료를 고릅니다. 만료는 7일, 30일, 60일, 90일 중에서 고르며 처음 값은 30일입니다. 무기한은 없습니다.
- 「만들기」를 누릅니다.
- 토큰을 복사합니다. 토큰 원문은 이 창에서 한 번만 보입니다. 창을 닫으면 다시 볼 수 없습니다.
- 창에 나온 명령을 순서대로 복사해 그 서버에서 실행합니다.
주의: 토큰을 설정 파일이나 코드 저장소에 적지 않습니다. 토큰을 잃어버리면 새로 만듭니다.
연결 만료 확인과 끊기
만료 확인
「Claude Code 연결」 화면의 목록에서 연결마다 마지막 사용 시각과 만료일을 봅니다. 곧 끝나는 연결에는 「곧 끝남」 표시가 붙습니다. 행의 「자세히」에서 토큰 앞 8자, 마지막 접속 IP, 만든 날을 볼 수 있습니다.
연결이 끝나기 7일 전부터 왼쪽 메뉴의 「Claude Code 연결」 옆에 숫자가 나옵니다. 이 숫자는 7일 안에 끝나는 수동 토큰의 수입니다. 받은편지함에도 「Claude Code 연결」 알림이 옵니다.
끝나거나 끊긴 연결은 「끝난 연결 보기(30일)」를 켜면 30일 동안 목록에 보입니다.
연결 끊기
- 연결 하나를 끊으려면 그 줄의 「연결 끊기」(OAuth) 또는 「토큰 폐기」(수동 토큰)를 누르고 확인합니다. 그 연결을 쓰던 Claude Code 가 바로 끊깁니다. 다시 쓰려면 새로 연결합니다.
- 모든 연결을 끊으려면 「모두 끊기」를 누릅니다. 확인을 위해 내 이메일을 적습니다. 내 AAS 로그인 세션도 모두 끝나므로 이 브라우저도 로그아웃됩니다. 다시 로그인하면 됩니다.
Claude Code 쪽 등록은 다음 명령으로 지웁니다.
claude mcp remove aas
연결은 한 사람당 10개까지 만들 수 있습니다. 한도에 닿으면 안 쓰는 연결을 끊고 다시 만듭니다. 관리자도 사용자의 연결을 끊을 수 있고, 이때 사유가 내 받은편지함에 나옵니다.