MCP 서버 만들기, 파이썬으로 첫 도구 연결하기
핵심 요약 MCP 서버는 AI 모델에 도구를 노출해 외부 자원과 연결하는 프로그램이다. 파이썬 공식 SDK로 만드는 최소 코드, 호스트 등록, 로컬 stdio와 원격 HTTP 전송의 차이를 개발자 눈높이로 짚었다.
MCP 서버는 AI 모델이 파일, 사내 데이터베이스, 외부 API 같은 자원을 직접 다루도록 연결해 주는 작은 프로그램이다. 2026년 7월 기준 Anthropic 공식 문서에 따르면 MCP(Model Context Protocol·모델이 외부 도구와 데이터에 접근하는 방식을 정해 둔 규약)는 오픈 프로토콜로 소개되며, 파이썬이나 타입스크립트용 공식 SDK를 쓰면 열 줄 남짓으로 첫 서버를 띄울 수 있다. 이 글은 파이썬으로 로컬 서버를 처음 만들어 보는 개발자를 기준으로 개념, 최소 코드, 호스트 연결까지 순서대로 짚는다. 특정 상용 서비스의 배포나 인증 설계까지는 다루지 않는다.
MCP 서버가 하는 일은 무엇인가
한마디로 AI가 꺼내 쓸 '도구 상자'를 여는 일이다. 사용자가 대화하는 앱(호스트)이 있고, 그 안의 클라이언트가 우리가 만든 서버에 붙는다. 서버는 자기가 제공할 기능을 목록으로 알려 주고, 모델이 필요한 순간에 그 기능을 호출한다.
Anthropic Model Context Protocol 공식 문서는 서버가 크게 세 가지를 노출할 수 있다고 안내한다. 모델이 실행하는 함수인 도구(tool), 읽어 들이는 자료인 리소스(resource), 미리 짜 둔 지시문인 프롬프트(prompt)다. 처음에는 도구 하나부터 붙이면 충분하다.
시작 전 준비할 것
준비물은 단출하다. 아래 세 가지면 첫 서버를 굴리기에 넉넉하다.
- 언어 런타임 하나 — 이 글은 파이썬을 쓴다. 타입스크립트 등 다른 언어의 공식 SDK도 제공되는 것으로 안내된다.
- 공식 SDK 설치 — 파이썬이면 패키지 매니저로
mcp계열 SDK를 받는다. - 서버를 붙일 호스트 — 데스크톱 AI 앱이나 개발 도구처럼 MCP를 지원한다고 밝힌 프로그램이면 된다.
파이썬으로 최소 서버 만들기
도구 하나를 노출하는 서버는 다음처럼 짧다. 두 정수를 더해 돌려주는 예시다.
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("demo")
@mcp.tool()
def add(a: int, b: int) -> int:
"""두 수를 더한다"""
return a + b
if __name__ == "__main__":
mcp.run()흐름은 세 단계로 나뉜다. 먼저 서버 객체를 만들고, 함수 위에 도구 데코레이터를 붙여 "이 함수를 모델이 호출해도 된다"고 표시한 뒤, 마지막 줄에서 서버를 실행한다. 함수 아래 설명 문자열과 매개변수 타입은 모델이 도구의 쓰임과 인자를 이해하는 단서가 되므로 비워 두지 않는 편이 좋다.
만든 서버를 호스트에 연결하기
서버 파일만 있으면 아직 아무 일도 일어나지 않는다. 호스트에 "이런 서버가 있으니 실행하라"고 등록해야 한다. 데스크톱 앱 계열은 대체로 설정 파일에 서버의 실행 명령을 적어 두는 방식으로 안내된다.
{
"mcpServers": {
"demo": {
"command": "python",
"args": ["server.py"]
}
}
}여기서 command는 서버를 띄우는 실행 파일, args는 그 뒤에 붙는 인자다. 등록한 뒤 호스트를 다시 시작하면 도구 목록에 방금 만든 기능이 나타난다. 경로나 실행 명령이 틀리면 서버가 조용히 안 뜨는 경우가 많으니, 터미널에서 서버 파일이 단독으로 실행되는지 먼저 확인하는 편이 빠르다.
로컬과 원격, 전송 방식은 어떻게 다른가
둘의 차이는 서버와 호스트가 메시지를 주고받는 통로에 있다. 공식 문서에 따르면 로컬 서버는 표준 입출력(stdio·프로그램이 콘솔로 입력과 출력을 주고받는 기본 통로)을, 원격 서버는 HTTP 기반 전송을 쓰는 것으로 안내된다. 주고받는 메시지 자체는 JSON-RPC(JSON으로 요청과 응답을 주고받는 원격 호출 규약) 형식으로 알려져 있다.
처음 연습할 때는 stdio가 가장 간단하다. 내 컴퓨터에서 호스트가 서버를 자식 프로세스로 띄우고 곧장 통신하기 때문이다. 여러 사용자가 붙는 원격 서버로 키우려면 HTTP 전송에 서버를 올리게 되는데, 이때는 컨테이너로 배포하는 경우가 많다. 컨테이너 여러 개를 묶어 띄운다면 도커 컴포즈의 네트워크 구성을 함께 점검해 두면 서버 사이 연결에서 헤매는 일이 준다.
붙이기 전 짚을 것
도구를 늘리기 전에 두 가지만 먼저 챙기면 시행착오가 줄어든다.
- 도구 하나씩 검증 — 함수를 단위 테스트로 먼저 통과시킨 뒤 서버에 노출한다. 모델이 잘못 부르는 문제와 함수 자체의 버그를 분리해 볼 수 있다.
- 권한 최소화 — 파일 삭제나 결제처럼 되돌리기 어려운 동작은 도구로 열 때 범위를 좁히고, 위험한 작업에는 확인 절차를 둔다.
여기까지 따라오면 도구 한 개짜리 MCP 서버가 호스트에서 동작한다. 다음은 리소스와 프롬프트를 붙이거나, 실제 업무 API를 도구로 감싸 보는 순서로 넓혀 가면 된다.