API 키로 내 도구 연결하기: Claude Code·Codex에 안전하게 붙이는 법

AI로 뭔가를 만들다 보면 어느 순간 이런 말이 나옵니다. "매일 들어오는 주문을 구글 시트에 정리해 줘", "노션에 쌓인 문의를 요약해서 메일로 보내 줘". 그런데 Claude Code나 Codex는 처음부터 내 구글 시트, 노션, 쇼핑몰 관리자 화면에 들어가 있지 않습니다. 누군가 문을 열어 줘야 하거든요. 그 문을 여는 게 연결이고 직접 붙이려면 대개 API 키라는 열쇠를 발급받게 돼요.

처음 연결할 때 막히는 지점은 대체로 세 곳입니다. 어떤 방식으로 붙일지, 키를 어디에 둘지, AI에게 어디까지 맡길지. 이 글은 그 세 가지에 한 번 성공한 연결을 다음에도 다시 쓰게 만드는 기록 습관을 더해 정리합니다. 마지막에는 키 없이 되는 공개 API로 한 바퀴 돌아 보는 실습이 있어요.

연결 방식 세 가지: 무엇부터 시도할까

외부 서비스를 AI에 붙이는 길은 크게 세 가지입니다. 위에서부터 순서대로 찾아보는 걸 권합니다.

① 공식 커넥터·MCP. MCP는 AI가 외부 도구에 붙는 방식을 통일한 표준입니다. 서비스 회사가 직접 MCP 서버나 커넥터를 내놓았다면 이게 가장 편해요. 로그인 창에서 허락만 하면 되는 경우가 많고 AI가 쓸 수 있는 기능(도구)이 이미 정리되어 있습니다. Claude Code는 claude.ai 구독 계정으로 로그인했다면 claude.ai에서 인증까지 마친 커넥터를 자동으로 가져다 쓰고(API 키 로그인 등은 제외) claude mcp add 명령으로 서버를 직접 추가할 수도 있습니다(Claude Code MCP 문서). Codex는 ChatGPT 데스크톱 앱의 설정 > MCP servers 또는 codex mcp add 명령으로 추가하고 플러그인 탭에서 MCP 도구가 묶인 플러그인을 설치할 수도 있어요(Codex MCP 문서, 플러그인 문서). 어떤 서버를 먼저 붙일지는 Claude Code MCP 서버 추천 5개와 최소 설정에 정리해 두었습니다.

② API·CLI를 스크립트로. 공식 MCP가 없거나 원하는 기능이 빠져 있다면 서비스의 API 문서 주소와 하고 싶은 일을 AI에게 주고 호출 스크립트를 짜게 합니다. 문서를 다 이해할 필요는 없고 결과만 확인하면 돼요. 한 번 짠 스크립트는 AI 없이도 다시 돌릴 수 있어서 매일 반복하는 일에 잘 맞습니다(모든 걸 AI에게 시키지 않기).

③ 브라우저 조작. API가 아예 없는 관리자 화면이라면 AI가 브라우저를 직접 열고 클릭하게 하는 방법도 있습니다. 가장 무겁습니다. 화면을 읽을 때마다 사용량이 크게 들고 버튼 위치가 바뀌면 깨지며 로그인이나 추가 인증 단계에서 멈추기도 해요. 마지막 수단으로 남겨 두세요.

MCP 서버도 결국 남이 만든 프로그램입니다. Claude Code 문서는 연결하기 전에 그 서버를 믿을 수 있는지 확인하라고 경고합니다. 외부 내용을 가져오는 서버는 프롬프트 주입 위험이 있기 때문이에요. 되도록 서비스 회사가 직접 만든 것부터 고르세요.

API 키는 비밀번호와 같습니다

API 키는 "이 요청은 내 계정이 보낸 것"이라고 서비스에 증명하는 긴 문자열입니다. 키를 가진 사람은 내 계정으로 그 서비스를 쓸 수 있어요. 누가 내 메일 발송 서비스 키를 손에 넣으면 내 이름으로 메일을 보낼 수 있고 쇼핑몰 키라면 주문 정보를 읽을 수 있습니다. 그래서 비밀번호처럼 다뤄야 합니다.

발급할 때: 권한은 좁게, 만료는 짧게

서비스마다 화면은 다르지만 키를 만들 때 보통 두 가지를 고를 수 있습니다.

• 권한(범위). 읽기, 쓰기, 삭제, 발송 같은 권한을 나눠 주는 서비스가 많습니다. 처음에는 읽기 전용으로 만드세요. 첫 연결의 목표는 "데이터가 보인다"까지입니다. 쓰기 권한은 읽기가 확실히 된 다음 필요한 범위만 추가한 새 키로 받는 편이 안전해요.
• 만료일. 고를 수 있다면 짧게 잡습니다. 실습용이라면 며칠이면 충분하고 오래 쓸 키라도 무기한보다는 기한을 두고 갱신하는 쪽이 사고 범위를 줄입니다.

키 값은 발급 직후 한 번만 보여 주는 서비스가 많으니 창을 닫기 전에 아래 방법으로 바로 보관해 두세요.

보관할 때: 파일에 두고 이름으로 부르기

키를 두는 곳은 두 가지 중 하나입니다.

프로젝트 안의 .env 파일. 프로젝트 폴더에 .env라는 파일을 만들고 이름=값 형태로 적습니다. 코드는 값 대신 이름(WEATHER_API_KEY 같은)만 부릅니다. 이 방식을 환경변수라고 해요. 이때 꼭 확인할 것이 .gitignore입니다. .gitignore에 .env가 들어 있지 않으면 GitHub에 올리는 순간 키가 같이 올라갑니다.

# .env (이 파일은 GitHub에 올리지 않는다)
NOTION_API_KEY=
SHEET_ID=

프로젝트 밖의 별도 파일. 여러 프로젝트에서 같은 키를 쓰거나 실수로 올릴 가능성 자체를 없애고 싶다면 프로젝트 폴더 밖에 따로 둡니다. 저는 이 방식을 씁니다. 비밀 값은 저장소 밖의 별도 폴더에 서비스별 파일로 나눠 두고 AI가 그 값을 화면에 출력하지 않게 하라는 규칙을 전역 규칙 파일에 적어 두었어요. 서비스별로 나누면 키 하나가 새도 그 파일만 바꾸면 됩니다.

어느 쪽이든 원칙은 같습니다.

• 채팅창에 키를 붙여 넣지 않습니다. 대화 내용은 기록에 남고 AI 회사 서버로 전송됩니다. "이 키로 연결해 줘"라며 값을 그대로 보내는 게 가장 흔한 실수예요.
• 키 파일은 빈 값으로 만들게 하고 값은 내가 채웁니다. AI에게는 ".env에 NOTION_API_KEY= 줄만 빈 값으로 만들어 줘"까지만 시키고 값은 직접 붙여 넣습니다. 저도 키가 들어갈 파일은 이렇게 만듭니다.
• 화면 공유·녹화 중에는 키 파일을 열지 않습니다. 발급 화면, .env 파일, 키가 찍힌 터미널이 화면에 잠깐 비치는 것만으로도 노출입니다.
• 노출됐다면 지우는 게 아니라 폐기합니다. 채팅에 붙여 넣었거나 GitHub에 올렸거나 녹화에 찍혔다면 새어 나갔다고 보고 서비스 설정에서 바로 폐기(revoke·delete)한 뒤 새로 발급합니다. 파일이나 커밋에서 지우는 것만으로는 이미 복사된 값을 되돌릴 수 없어요.

AI에게 요청할 때: "값은 보지 말고 이름으로만"

AI가 키를 쓰게 하려면 값을 알려 줄 필요가 없습니다. 스크립트가 실행될 때 파일에서 값을 읽어 오게 짜면 되거든요. 요청할 때 이렇게 분명히 말해 두세요.

노션 API로 데이터베이스 목록을 읽는 스크립트를 만들어 줘.
- 키는 .env 파일의 NOTION_API_KEY에 있어. 값은 열어 보거나 출력하지 말고, 코드에서는 변수 이름으로만 불러 줘.
- 테스트할 때도 키 값이 화면이나 로그에 찍히지 않게 해 줘. 성공 여부와 상태 코드만 보여 줘.
- .gitignore에 .env가 들어 있는지 먼저 확인해 줘.

이 부탁을 매번 하기 번거롭다면 규칙 파일(CLAUDE.md·AGENTS.md)에 적어 둡니다. 두 도구를 같이 쓴다면 규칙을 AGENTS.md 한 곳에 두고 CLAUDE.md에서 불러오는 방법이 있어요. 그 방법과 두 파일의 차이는 AI가 알아서 찾는 작업 폴더 만들기에, 작성법은 CLAUDE.md 작성법에 있습니다.

## 비밀 값
- API 키·토큰 값은 어떤 명령의 출력, 파일, 대화에도 쓰지 않는다. 코드에서는 환경변수 이름으로만 부른다.
- 키가 들어갈 파일은 빈 값으로만 만든다. 값은 사용자가 직접 채운다.
- 키가 노출된 것 같으면 작업을 멈추고 폐기·재발급을 안내한다.

규칙 파일은 AI가 무엇을 하려 할지에 영향을 줄 뿐 실제로 막지는 못합니다. Claude Code 문서도 이 점을 분명히 적어 둡니다. 그래서 다음 절의 권한 설정을 함께 씁니다.

권한 설정: 읽기는 허용, 쓰기·삭제·발송은 묻기

연결이 되면 AI는 내 계정으로 행동할 수 있게 됩니다. 그래서 어디까지 묻지 않고 하게 할지 정해야 해요. 이게 권한 모드입니다. 시작 기준은 간단합니다. 읽기는 허용하고 쓰기·삭제·발송은 매번 묻게 합니다. 조회는 잘못돼도 다시 하면 되지만 보낸 메일과 지운 데이터는 되돌리기 어렵거든요.

Claude Code

권한 모드 문서에 따르면 CLI에서는 Shift+Tab으로 모드를 바꿉니다. 대표적인 모드는 이렇습니다.

주의할 점이 두 가지 있습니다. 같은 문서에 따르면 Pro, Max, Team 플랜에서는 새 세션이 기본으로 auto 모드로 시작합니다(버전, 설정 파일, 로그인 방식에 따라 Manual로 시작하기도 합니다). 그런데 auto의 기본 허용 목록에는 .env를 읽어 그 키를 짝이 맞는 API로 보내는 일이 들어 있어요. 키를 엉뚱한 곳으로 보내는 건 막지만 키를 쓰는 호출 자체는 묻지 않고 진행될 수 있다는 뜻입니다. 또 acceptEdits는 작업 폴더 안의 rm까지 묻지 않고 실행하니 "삭제는 묻기"로 시작하려면 맞지 않습니다. 처음 외부 서비스를 붙이는 동안에는 Manual로 바꿔 두고 무엇이 실행되는지 직접 보는 편이 배우기 좋아요.

모드 위에 규칙을 얹을 수도 있습니다. /permissions를 입력하면 허용(Allow), 묻기(Ask), 거부(Deny) 규칙을 보고 고칠 수 있어요. 권한 문서에 따르면 규칙은 거부 → 묻기 → 허용 순서로 검사되고 먼저 맞는 규칙이 이깁니다. 외부 서비스 연결에서 쓸 만한 규칙은 세 가지입니다.

• Read(./.env)를 거부에 넣으면 Claude의 파일 읽기 도구와 cat처럼 파일 이름을 적는 명령이 현재 폴더의 .env를 열지 못합니다. 작업 폴더 안의 파일은 원래 묻지 않고 읽을 수 있어서 이 규칙이 필요해요. .env.local 같은 파일도 막으려면 설정 문서의 예시처럼 Read(./.env.*)를 한 줄 더 넣습니다. 다만 grep -r처럼 파일 이름을 적지 않는 명령이나 스크립트가 파일을 직접 여는 것까지는 막지 못합니다. 스크립트가 키를 읽어 쓰는 건 정상 동작이고 이 규칙은 AI가 값을 들여다보는 걸 줄이는 장치예요.
• MCP 도구는 mcp__서버이름__도구이름 형식으로 조회 도구는 허용에, 만들거나 지우는 도구는 묻기에 넣습니다. /mcp에 보이는 이름으로 겁니다.
• claude mcp add의 --env나 --header에 키 값을 직접 넣으면 설정 파일에 저장됩니다. --scope project로 추가하면 저장소에 함께 올라가는 .mcp.json에 들어가니 키 값 대신 MCP 문서처럼 ${API_KEY} 같은 환경변수 이름만 적습니다.

Codex

ChatGPT 데스크톱 앱의 Codex는 권한 문서 기준으로 세 가지 모드가 있습니다. 기본인 Ask for approval은 작업 폴더 안의 파일 수정과 일상적인 명령은 알아서 하고 인터넷 접속이나 폴더 밖 작업 전에 묻습니다. Approve for me(설정 이름 Auto-review)는 그 승인 요청을 ChatGPT가 대신 검토하고 Full access는 묻지 않고 전부 합니다. 처음에는 Ask for approval을 유지하세요. 보안 문서에 따르면 버전 관리(Git)를 하지 않는 폴더나 아직 신뢰하지 않은 폴더에서는 읽기 전용으로 시작할 수 있어서 폴더 안 수정도 승인을 거칠 수 있습니다. 같은 문서에 따르면 기본 설정에서는 명령의 인터넷 접속이 꺼져 있어서 스크립트로 API를 부르는 테스트에서도 승인 창이 뜨는 게 정상이에요. 무엇을 어디로 보내는지 읽고 승인하면 됩니다.

MCP 서버는 설정 파일(config.toml)에서 도구별 승인 방식을 정할 수 있습니다. Codex MCP 문서에 따르면 서버 단위로 default_tools_approval_mode를 두고 prompt(묻기), writes(읽기 전용이 아닌 도구만 묻기) 같은 값을 고르고 특정 도구만 다르게 하려면 tools.<도구이름>.approval_mode를 씁니다. 설정 파일을 직접 고치기 부담스럽다면 이렇게 부탁해도 됩니다.

방금 추가한 notion MCP 서버의 도구 중에 읽기 전용이 아닌 것은 실행 전에 항상 묻도록 설정해 줘.
어떤 설정 파일의 어느 줄을 바꿨는지 알려 줘.

API 학습 노트: 한 번 겪은 삽질을 다시 겪지 않게

처음 연결할 때는 거의 항상 뭔가 막힙니다. 키를 넣는 위치가 헤더인지 주소인지, 날짜 형식이 무엇인지, 한 번에 몇 건까지 가져올 수 있는지. AI와 한참 주고받은 끝에 연결에 성공해도 새 대화를 열면 그 과정을 기억하지 못하고 같은 삽질을 처음부터 다시 해요.

그래서 연결에 성공하면 무엇이 됐고 무엇이 막혔는지를 파일로 남기게 합니다. 서비스별로 docs/api-notes/<서비스>.md 파일을 두고 규칙 파일에는 "외부 API를 쓰기 전에 이 폴더를 먼저 읽는다"를 적어 두는 방식입니다.

## 외부 API
- 외부 서비스를 호출하기 전에 docs/api-notes/<서비스>.md가 있으면 먼저 읽는다.
- 처음 연결에 성공하거나 새로 막힌 점을 해결하면 그 파일을 갱신한다.
- 노트에는 키 값을 쓰지 않는다. 환경변수 이름만 쓴다.

노트 한 장에는 이 정도면 충분합니다.

# 노션 API 노트

- 공식 문서: (문서 주소)
- 인증: 환경변수 NOTION_API_KEY, Authorization 헤더에 Bearer로 넣음. SDK 없이 부르면 Notion-Version 헤더도 필요
- 권한: 읽기 기능만 켠 연결. 대상 페이지를 연결에 따로 공유해야 접근됨
- 된 것: 데이터베이스 목록 조회 (scripts/notion/list-db.js)
- 막힌 것: 처음에 404(object_not_found)가 옴 → 페이지를 연결에 공유하지 않아서였음
- 한도: (문서에서 확인한 요청 한도)
- 마지막 확인: 2026-09-25

위 내용은 예를 들어 이런 식으로 쓴다는 가상의 노트입니다. 인증 방식은 노션 개발자 문서에 맞춰 적었지만 내 서비스의 노트는 그 서비스 문서에서 확인한 내용으로 채워야 해요.

이렇게 쌓이면 docs/api-notes/에는 서비스별 노트가, scripts/에는 서비스별 스크립트가 모입니다. 다음에 "지난번에 만든 노션 스크립트로 이번 주 문의만 뽑아 줘"라고 하면 AI가 노트와 스크립트를 찾아서 이어서 일해요. 이런 폴더를 처음부터 잡는 법은 AI가 알아서 찾는 작업 폴더 만들기에 있습니다.

실습: 키 없는 공개 API로 한 바퀴 돌기

처음부터 내 쇼핑몰 키로 연습하면 실수가 곧 사고가 됩니다. 연결 흐름은 서비스가 달라도 같으니 키가 필요 없는 공개 API로 먼저 한 바퀴 돌아 보세요. 여기서는 날씨 API인 Open-Meteo를 씁니다. 공식 문서에 따르면 비상업적 용도에는 API 키가 필요 없고 무료 사용 조건과 호출 한도는 이용 약관에 있어요. 아래 대화는 실제 기록이 아니라 이렇게 요청하면 된다는 가상의 흐름입니다.

1. 문서를 주고 계획부터 받기

Open-Meteo 날씨 API로 서울의 현재 기온을 가져오는 작은 스크립트를 만들고 싶어.
공식 문서는 https://open-meteo.com/en/docs 야. 먼저 문서를 읽고
어떤 주소로 어떤 값을 보내야 하는지 설명해 줘. 아직 코드는 만들지 마.

2. 스크립트 만들기

좋아. scripts/weather/current.js 파일로 만들어 줘.
- 서울 좌표는 위도 37.57, 경도 126.98 로 해 줘.
- 결과는 "서울 현재 기온: OO도" 한 줄과 HTTP 상태 코드만 출력해 줘.
- 외부 패키지는 설치하지 말고, 실패하면 상태 코드와 이유를 짧게 보여 줘.

3. 테스트 호출 한 번

스크립트를 한 번만 실행해 줘. 반복 실행하지 마.

Codex라면 명령으로 인터넷에 접속하는 단계라 승인 창이 뜹니다. Claude Code의 Manual 모드에서도 명령 실행 전에 물어요. 무엇을 실행하는지 읽고 승인합니다.

4. 결과 확인

받은 기온이 말이 되는 값인지, 응답에 들어 있는 시간이 언제 기준인지 확인해 줘.
시간대를 서울 기준으로 보려면 무엇을 바꿔야 하는지도 알려 줘.

문서에 따르면 timezone 값을 넣거나 auto로 두면 좌표에 맞는 현지 시간대로 바꿔 줍니다. 이런 세부 사항이 노트에 남길 거리예요.

5. 노트 남기기

오늘 한 것을 docs/api-notes/open-meteo.md에 정리해 줘.
공식 문서 주소, 요청 주소 형식, 키 필요 여부, 시간대 설정, 된 것과 막힌 것, 스크립트 위치, 오늘 날짜를 넣어 줘.

키가 필요한 서비스로 넘어갈 때는 2번 요청에 "키는 .env의 ○○_API_KEY에 있고 값은 보지 말고 이름으로만 불러 줘"를 한 줄 더하고 키 줄은 빈 값으로 만들게 한 뒤 내가 채우면 됩니다. Node.js라면 node --env-file=.env scripts/weather/current.js처럼 실행할 때 .env를 읽어 오게 할 수 있어요(Node.js 문서, 20.6 버전부터). 받은 데이터를 데이터베이스에 저장하는 쪽까지 가 보고 싶다면 Supabase로 첫 데이터베이스가 다음 단계입니다.

상태 코드로 어디서 막혔는지 알기

호출 결과에는 세 자리 숫자인 상태 코드가 붙어 옵니다. 에러 메시지가 길어도 이 숫자만 보면 어디부터 볼지 감이 와요. MDN 상태 코드 문서를 기준으로 짧게 풀었습니다.

401은 "누구세요?", 403은 "누군지는 아는데 안 됩니다"로 기억하면 쉬워요. 다만 서비스마다 쓰는 코드가 조금씩 달라서 결국 그 서비스의 오류 문서를 함께 봐야 합니다.

관련 글

• Claude Code MCP 서버 추천 5개와 최소 설정
• 모든 걸 AI에게 시키지 않기: 스크립트·크론으로 돌릴 일 가르기
• AI가 알아서 찾는 작업 폴더 만들기
• Supabase로 첫 데이터베이스: 로그인 없는 폼 저장하기
• 용어: 환경변수, MCP, 권한 모드

출처와 확인 (2026-09-25)

• Claude Code: Configure permissions (/permissions, 허용·묻기·거부 순서, Read(./.env), MCP 규칙 형식, 규칙 파일은 실제로 막지 못한다는 안내)
• Claude Code: Choose a permission mode (모드 목록, Shift+Tab, Pro·Max·Team의 시작 모드, acceptEdits가 자동 승인하는 명령, auto 기본 허용 목록)
• Claude Code: Settings reference (permissions.deny의 .env 제외 예시)
• Claude Code: MCP (claude mcp add, 설치 범위, .mcp.json의 환경변수 확장, claude.ai 커넥터, 서버 신뢰 경고)
• Claude Code: Memory (CLAUDE.md와 AGENTS.md를 읽는 조건)
• Codex: Permissions (Ask for approval, Approve for me, Full access)
• Codex: Agent approvals & security (기본 네트워크 꺼짐, 버전 관리 없는 폴더의 읽기 전용 시작)
• Codex: Model Context Protocol (앱·CLI에서 MCP 추가, default_tools_approval_mode, 도구별 승인)
• Codex: Plugins (플러그인에 MCP 도구 포함)
• Open-Meteo 문서와 이용 약관 (비상업적 용도 키 불필요, 호출 한도, timezone)
• MDN HTTP 상태 코드
• 노션 인증과 상태 코드 (노트 예시의 헤더, 공유하지 않은 페이지의 404)
• Node.js CLI --env-file