목차

MCP Server

MCP 서버

외부 AI 코딩 도구 — Claude Code, Codex, Antigravity — 를 내 AiTalk 계정에 직접 연결합니다. 연결한 뒤에는 원하는 것을 평소 말로 설명하면 AI 가 만들어 줍니다. 에이전트, 워크플로우, 지식베이스 모두요.

무엇인가요

MCP(Model Context Protocol)는 AI 도구가 외부 서비스를 사용하는 표준 방식입니다. AiTalk 이 MCP 서버, 내 AI 도구가 클라이언트가 됩니다.

내 AI 도구 (Claude Code / Codex / Antigravity)
        │
        │  Authorization: Bearer aitk_...
        ▼
AiTalk MCP 서버  ──→  내 에이전트 · 워크플로우 · 지식베이스 · 대화 기록

연결된 AI 가 할 수 있는 일:

영역가능한 작업
에이전트 · 워크플로우목록 조회, 내용 확인, 템플릿이나 빈 상태에서 새로 만들기, 수정, 검증
배포워크플로우를 실서비스로 올리기, 실서비스 중인 워크플로우를 초안으로 내리기
지식베이스(RAG)소스 파일 목록 조회 · 읽기 · 추가 · 삭제
대화 기록지난 채팅 · 음성 통화 · 퀴즈 응시 기록 읽기

할 수 없는 일:

  • 워크플로우나 에이전트 삭제 — 대시보드에서 하세요
  • 테스트 실행 — 대시보드에서 하세요
  • 구독 · 결제 · 크레딧 변경
  • 다른 고객의 데이터 접근. 모든 요청은 그 토큰을 소유한 계정으로 제한됩니다

액세스 토큰이 왜 필요한가요

액세스 토큰은 AI 도구가 "나"임을 증명하는 수단입니다. 다른 경로는 없습니다 — 토큰이 없으면 MCP 서버로 오는 모든 요청이 거절됩니다. 첫 토큰을 만들기 전까지는 아무것도 연결되지 않습니다.

알아두실 점:

  • 토큰은 만든 직후 단 한 번만 표시됩니다. 바로 복사하세요. 잃어버렸다면 폐기하고 새로 만드세요.
  • 쓰기 권한이 기본으로 켜져 있습니다. AI 가 만들고 수정할 수 있어야 하기 때문입니다. 해제하면 읽기 전용 토큰이 발급됩니다(AI 가 보기만 하고 손대지 않게 하려는 경우에 유용합니다).
  • 토큰은 최대 5개까지 만들 수 있습니다. 기기별 또는 도구별로 하나씩 두는 습관이 좋습니다 — 문제가 생겼을 때 하나만 폐기하면 됩니다.
  • 토큰은 비밀번호처럼 다루세요. 토큰을 가진 사람은 내 계정에서 나로서 행동할 수 있습니다.

연결 방법

1단계: 토큰 만들기

  1. AiTalk 에서 설정 → MCP 서버 로 이동합니다
  2. 이름을 입력합니다 — 사용할 기기나 도구 이름을 쓰면 좋습니다. 예: Claude Code - MacBook
  3. 쓰기 도구 허용 을 켠 채로 둡니다(읽기 전용 토큰이 필요하면 해제)
  4. 토큰 생성 을 누릅니다
  5. 토큰을 지금 복사하세요 — 한 번만 표시됩니다

2단계: AI 도구에 AiTalk 추가하기

AI 도구 연결 에서 사용하는 도구 탭을 고릅니다. 표시되는 명령에는 새로 만든 토큰이 이미 들어 있습니다 — 복사해서 아래 설명대로 사용하세요.

Claude Code — 터미널에서 실행합니다:

claude mcp add --transport http aitalk https://www.aitalk.ch/api/mcp-server \
  --header "Authorization: Bearer aitk_내_토큰"

Claude Desktop — 설정 → 개발자 → 설정 편집에서 붙여넣고 앱을 재시작합니다. Node.js(npx)가 필요합니다. 설정 파일 위치:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Codex — ~/.codex/config.toml 에 추가합니다. Codex 앱에서는 New MCP → Type = Streamable HTTP 를 선택한 뒤 URL 과 Authorization: Bearer 헤더를 입력합니다.

Antigravity — ~/.gemini/config/mcp_config.json 에 추가합니다(Settings → Customizations → Open MCP Config). 저장 후 새로고침하세요.

3단계: AI 에게 시키기

평소 말로 지시하면 됩니다. 예를 들어:

  • "내 AiTalk 에이전트와 워크플로우 목록 보여줘"
  • "고객 응대 워크플로우가 무슨 일을 하는지 설명해줘"
  • "FAQ 템플릿으로 워크플로우 만들고 인사말을 ... 로 설정해줘"
  • "이 내용을 지식베이스에 추가해줘"
  • "예약 워크플로우 배포해줘"

AI 가 AiTalk 내장 가이드를 알아서 읽으므로, 워크플로우 구조를 따로 설명하지 않아도 됩니다.

접속 확인하기

토큰이 어떻게 쓰이고 있는지 두 곳에서 볼 수 있습니다:

  • 설정 → MCP 서버 — 토큰별로 마지막 사용 시각과 접속한 IP · 국가
  • 대시보드 — 요약: 토큰 개수, 가장 최근 접속 시각과 위치

모르는 접속이 보이면 그 토큰을 즉시 폐기하세요(옆의 휴지통 아이콘). 연결된 도구는 곧바로 접근 권한을 잃습니다.

국가는 접속한 IP 주소로 판별합니다. VPN 을 쓰거나 클라우드에서 돌아가는 AI 도구라면 내 위치가 아니라 그 서버의 국가가 표시됩니다.

안전장치

실수 — 또는 AI 가 지시를 잘못 이해한 경우 — 가 조용히 사고로 이어지지 않도록 몇 가지 제약을 두었습니다:

  • 배포는 드러나게 합니다. 워크플로우를 실서비스로 올리는 것은 의도적인 행위입니다. 올라가기 전에 직접 확인하고 싶다면, AI 에게 배포를 요청하도록 시키세요 — 링크를 받아 직접 열고 Deploy 를 누르는 방식입니다.
  • 실서비스 중인 워크플로우를 수정하면 고객에게 즉시 반영됩니다. AI 는 먼저 확인을 받도록 안내되어 있습니다.
  • 비밀값은 절대 나가지 않습니다. 워크플로우에 들어 있는 API 키 · 비밀번호 · 토큰은 서버를 떠나기 전에 가려지므로, 연결된 AI 가 읽을 수 없습니다.
  • 호출 한도가 토큰별로 적용됩니다(읽기와 쓰기를 따로 계산).
  • 모든 호출이 기록됩니다 — 어떤 도구를 실행했는지, 성공했는지, 얼마나 걸렸는지.

문제 해결

증상원인 / 해결
401 Unauthorized토큰이 틀렸거나 폐기됐거나, Authorization: Bearer 접두어가 빠졌습니다. 새 토큰을 만들어 다시 등록하세요.
연결은 되는데 에이전트가 안 보임그 토큰의 계정에 아직 에이전트가 없습니다. 대시보드에서 먼저 만드세요.
쓰기 작업이 거절됨읽기 전용으로 만든 토큰입니다. 쓰기 도구 허용 을 켜서 새 토큰을 만드세요.
"Rate limit exceeded"1분 안에 호출이 너무 많았습니다. 잠시 기다린 뒤 계속하세요.
새로 넣은 소스 파일이 아직 검색되지 않음색인이 백그라운드에서 진행됩니다. 몇 초 기다린 뒤 다시 물어보세요.
PDF · Word · Excel 파일을 올릴 수 없음바이너리 파일은 MCP 로 전송되지 않습니다. AI 에게 내용을 먼저 텍스트로 변환하게 하거나, 대시보드 저장소 페이지에서 직접 업로드하세요.

문의

support@aitalk.ch 로 연락 주세요.

← 이전: MCP