사내 위키/이슈 트래커를 에이전트에 붙이려고 MCP 서버 만들려는데 어디부터 시작하나요 (입문)

Question

Claude Desktop이랑 Claude Code에서 우리 회사 내부 API(사내 위키, 이슈 트래커)를 에이전트가 직접 조회하게 하고 싶습니다. MCP라는 걸 쓰면 된다는 건 알겠는데, 막상 시작하려니 막막합니다.

서버를 어떤 언어/SDK로 짜야 하나요
우리 내부 API에 인증 토큰이 필요한데 그건 어떻게 처리하나요
로컬에서만 쓸 건데 stdio랑 HTTP 중 뭘 골라야 하나요

경험 있으신 분 가이드 부탁드립니다. 처음이라 용어부터 헷갈립니다.

Accepted Answer

MCP(Model Context Protocol)는 에이전트(클라이언트)랑 도구(서버) 사이의 표준 규약이라고 보면 됩니다. 님이 만들 건 "MCP 서버"고, Claude Desktop/Code가 "클라이언트"예요. 헷갈리는 게 정상이니 순서대로 갈게요.

SDK 공식 SDK가 여러 언어로 있는데 Python이나 TypeScript가 예제가 제일 많아요. 사내 API가 무슨 스택이든 상관없습니다. MCP 서버는 그 API를 감싸는 얇은 래퍼라서, 그냥 본인이 제일 익숙한 언어로 하세요.

transport — 로컬이면 무조건 stdio 로컬 단독이면 stdio가 정답입니다. 클라이언트가 서버를 자식 프로세스로 띄우고 표준입출력으로 통신해서 설정이 제일 단순해요. HTTP는 여러 사람이 원격으로 붙거나 별도 호스팅할 때 의미가 있는데, 그 순간 인증 설계가 통째로 따라옵니다(이거 안 하면 사고). 지금 단계에선 거기까지 갈 필요 없어요. stdio로 시작.

인증 토큰 — 환경변수로 stdio 로컬이면 제일 쉬운 건 환경변수입니다. 클라이언트 MCP 등록 JSON에 env로 토큰 넘기고, 서버에서 os.environ으로 읽어 사내 API 호출 헤더에 붙이면 끝.

{ "command": "python", "args": ["/abs/path/server.py"], "env": { "WIKI_TOKEN": "..." } }

토큰을 툴 인자로 받거나 코드에 하드코딩하지 마세요. 인자로 받으면 모델 컨텍스트에 토큰이 그대로 노출됩니다.

처음엔 작게 툴 2~3개(위키 검색, 이슈 조회)만 노출하고, 각 툴에 이름/설명/입력 스키마 정의 + 핸들러에서 API 호출. 동작 확인되면 점진적으로 늘리세요. 한 방에 20~30개 붙이면 모델이 뭘 골라야 할지 헷갈려서 오히려 안 부릅니다. 설명(description)에 "언제 쓰는 도구인지"를 또박또박 적는 게 생각보다 중요해요.

Answer

위에서 거의 다 짚었고, 입문자가 100% 한 번씩 밟는 디버깅 지뢰만 추가합니다.

stdio 서버는 표준출력으로 프로토콜 메시지가 오가서, print로 디버깅하면 프로토콜이 깨집니다. 저도 처음에 이거 모르고 print("여기 도달") 박아놨다가 서버가 연결 안 된다고 두 시간 헤맸어요. 로그는 무조건 stderr나 파일로 빼세요.

그리고 등록했는데 클라이언트에서 툴이 안 보이면 십중팔구 설정 JSON의 경로나 실행 커맨드 문제입니다. command/args는 절대경로로 쓰고, 그 커맨드를 터미널에서 그대로 복붙해서 서버가 에러 없이 뜨는지부터 확인하세요. 클라이언트 안에서 디버깅하려고 하면 답 없습니다. 터미널 단독 실행 → 통과하면 그때 클라이언트에 물리기.

사내 위키/이슈 트래커를 에이전트에 붙이려고 MCP 서버 만들려는데 어디부터 시작하나요 (입문)

답변 2개