환율 변환 MCP 서버 구축하기
안녕하세요 novice-22입니다.
이번에 작성한 글은 간단한 환율 변환 MCP 서버를 구축하는 방법입니다. MCP서버에 대해서 잘 모르시는분들은 이전에 작성한 글 MCP가 무엇인지 글부터 읽으시면 서버 구축하는데 보다 더 이해하기 좋습니다.
1. 환경 구축
MCP SDK를 사용하여 서버를 구축할거여서 먼저 MCP SDK가 무엇인지 부터 설명을 시작하고 Python SDK를 사용하여 서버를 구축하기때문에 Python SDK에 대해서도 설명을 한다
1-1 MCP SDK란?
MCP SDK는 MCP를 기반으로, 개발자가 MCP 클라이언트나 MCP 서버를 쉽게 구축할 수 있도록 지원하는 공식 소프트웨어 개발 키트이다.
SDK를 사용하는 이유는 다음과 같다. MCP를 직접 만든다면 JSON-RPC 메시지를 조립하고 전송 방식을 구현하고 tools/list, tools/call 같은 메서드를 전부 구현해야 한다. 하지만 SDK를 사용하면 함수 하나를 등록하는 것으로 끝난다. 도구 정의를 생성하고, 들어온 요청을 해석해 함수를 부르고, 결과를 응답으로 돌려주는 과정을 직접 만들지 않아도 된다.
공식 SDK
공식 SDK는 여러 언어로 나와 있다. TypeScript, Python, C#, Go, Rust, Java, Ruby, Swift, PHP, Kotlin이 있고 전부 같은 기능을 제공한다. 서버 구현, 클라이언트 구현, 로컬·원격 전송 방식을 공통으로 지원한다.
설치 방법
uv add "mcp[cli]"
# 또는
pip install "mcp[cli]"Python SDK의 두 가지 방식
Python SDK는 두 가지 방식을 제공한다.
MCPServer- 데코레이터로 함수를 등록하면 나머지를 SDK가 처리한다- 저수준
Server- 도구 정의를 직접 작성하고 핸들러도 직접 연결한다
공식 문서의 MCPServer 예시는 다음과 같다. 공식 예시에는 Tools와 Resources만 있어서 Prompts를 추가했다.
from mcp.server import MCPServer
mcp = MCPServer("Demo")
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
"""Greet someone by name."""
return f"Hello, {name}!"
@mcp.prompt()
def review_code(code: str) -> str:
"""Review a piece of code."""
return f"Please review this code:\n\n{code}"코드 작성 방법은 각 함수 위에 데코레이터(@)를 붙이는 방식이다. 데코레이터가 붙은 함수는 MCP 서버에 등록되고, 타입 힌트(a: int)와 독스트링을 보고 SDK가 정의를 만들어준다.
다음은 Tools, Resources, Prompts에서 사용하는 데코레이터 설명이다. Tools는 @mcp.tool(), Resources는 @mcp.resource(), Prompts는 @mcp.prompt() 를 사용한다. 붙이는 데코레이터 이름만 다를 뿐 방식은 같다.
Resources에는 한 가지가 더 있다. greeting://{name} 처럼 URI에 중괄호를 사용하면 중괄호 안의 이름이 함수 인자가 된다. 중괄호가 없으면 등록한 주소 하나가 대상 하나여서, greeting://Tom과 greeting://Amy를 둘 다 지원하려면 함수를 두 개 만들어야 한다. 이때 중괄호를 사용하면 함수 하나로 끝낼 수 있다. 클라이언트가 greeting://Tom을 읽어달라고 하면 SDK가 Tom을 꺼내 greeting(name="Tom") 을 호출하기 때문이다.
이렇게 둘로 나뉘다 보니 목록을 조회하는 메서드도 두 개이다. resources/list 는 바로 읽을 수 있는 주소만 담는 목록이고, resources/templates/list 는 중괄호가 있는 주소만 담는 목록이다.
resources/list- 중괄호가 없는 주소. 주소 그대로 읽는다resources/templates/list- 중괄호가 있는 양식. 값을 채워서 읽는다
버전 주의
공식 Python SDK는 현재 버전이 v2다. v1의 fastmcp 가 v2에서 mcpserver 로 바뀌었다.
그래서 import 경로와 클래스 이름도 달라졌다. v1은 from mcp.server.fastmcp import FastMCP 였지만 v2는 from mcp.server import MCPServer 다.
다만 이름만 바뀐 것은 아니다. v2는 SDK 전반을 다시 만든 버전이라 다음도 함께 변경되었다.
- 예외 클래스가
McpError에서MCPError로 변경되었다 - 필드 이름이 camelCase에서 snake_case로 변경되었다.
inputSchema는input_schema가 된다. 다만 실제로 오가는 JSON은 그대로 camelCase다 - 프로토콜 스키마 검증이 엄격해졌다. 모르는 메서드 요청에는
-32601을 반환한다 - Roots, Sampling, Logging을 사용하면 경고가 발생한다
MCP_*환경 변수와.env파일을 더 이상 읽지 않는다
그래서 v1 기준으로 쓰인 코드는 import만 바꿔서는 돌아가지 않는다. mcp.server.fastmcp 를 import하면 ModuleNotFoundError 가 난다. 검색하면 아직 FastMCP 로 된 자료가 많은데, 이 글은 v2 기준으로 작성했기 때문에 fastmcp 는 사용하지 않는다.
출처
1-2 환율 API 선정
MCP 서버가 환율을 가져오려면 외부 환율 API가 필요하다. 아래의 표는 환율 API 목록들이다.
| API | 인증키 | 무료 범위 | 갱신 | 데이터 출처 |
|---|---|---|---|---|
| 한국수출입은행 | 필요 | 일 1,000회 | 영업일 1회 (11시 전후) | 수출입은행 고시 환율 |
| Frankfurter | 불필요 | 쿼터 없음 | 일 1회 | 중앙은행 등 공식 기관 98곳 |
| ExchangeRate-API | 불필요 | IP 단위 제한 | 24시간 | 자체 집계 |
API 선정 이유
이번 환율 MCP 서버는 한국수출입은행 API를 사용한다. 이유는 두 가지다.
첫째, 국내 기관이 고시하는 환율이다. Frankfurter와 ExchangeRate-API도 원화를 지원하지만 해외에서 집계한 값이다. 수출입은행 API는 국내 은행이 직접 고시하는 값을 그대로 받아온다. 매매 기준율뿐 아니라 전신환 송금 환율까지 같이 준다.
둘째, 인증키가 필요하다. 키가 없는 API가 사용하기는 편하지만, 실제로 쓰이는 MCP 서버는 대부분 외부 API를 사용하기 때문에 키가 있는 API로 선택하였다.
인증키 발급
한국수출입은행 홈페이지에서 신청가능하다. 본인인증을 하고 신청서를 작성하면 바로 발급된다.
API 사용 방법
요청 양식은 아래와 같다.
https://oapi.koreaexim.go.kr/site/program/financial/exchangeJSON?authkey={발급받은 인증키}&searchdate=20260917&data=AP01요청변수 (Requester Parameter)
| 변수명 | 타입 | 변수설명 | 값설명 |
|---|---|---|---|
| authkey | String(필수) | 인증키 | OpenAPI 신청시 발급된 인증키 |
| searchdate | String | 검색요청날짜 | ex) 2015-01-01, 20150101, (DEFAULT)현재일 |
| data | String(필수) | 검색요청API타입 | AP01 : 환율, AP02 : 대출금리, AP03 : 국제금리 |
출력결과 (Response Element)
| 변수명 | 타입 | 변수설명 | 값설명 |
|---|---|---|---|
| RESULT | Integer | 조회 결과 | 1 : 성공, 2 : DATA코드 오류, 3 : 인증코드 오류, 4 : 일일제한횟수 마감 |
| CUR_UNIT | String | 통화코드 | |
| CUR_NM | String | 국가/통화명 | |
| TTB | String | 전신환(송금) 받으실때 | |
| TTS | String | 전신환(송금) 보내실때 | |
| DEAL_BAS_R | String | 매매 기준율 | |
| BKPR | String | 장부가격 | |
| YY_EFEE_R | String | 년환가료율 | |
| TEN_DD_EFEE_R | String | 10일환가료율 | |
| KFTC_DEAL_BAS_R | String | 서울외국환중개 매매기준율 | |
| KFTC_BKPR | String | 서울외국환중개 장부가격 |
주의할 점
요청 URL 도메인이 바뀌었다. 2025-06-25에 www.koreaexim.go.kr에서 oapi.koreaexim.go.kr로 변경되었고 기존 도메인은 2026-04-30에 종료되었다. 검색하면 나오는 예제 코드는 대부분 구 도메인이라 그대로 사용하면 동작하지 않는다.
영업일 기준으로 하루 한 번 갱신된다. 11시 전후에 그날 고시 환율이 올라온다. 주말과 공휴일, 영업일이라도 11시 이전에는 데이터가 비어서 온다. 실시간 환율이 아니다.
일일 호출 1,000회 제한이 있다. 초과하면 데이터 대신 result 가 4 로 온다.
출처
1-3 프로젝트 만들기
PowerShell 기준으로 진행한다.
uv 설치
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"설치가 끝나면 터미널을 다시 열어야 uv 명령을 인식한다. 이미 설치되어 있다면 uv --version 으로 확인하고 넘어가면 된다.
프로젝트 생성
프로젝트를 담을 폴더를 만들고 그 안에서 실행한다.
cd {프로젝트를 만들 경로}
uv init --no-packageuv init 은 이름을 주지 않으면 현재 폴더에 만든다. 폴더 이름이 곧 프로젝트 이름이 된다.
--no-package 를 붙이면 src\ 폴더와 [build-system] 같은 배포용 설정이 생기지 않는다. 배포할 계획이라면 옵션 없이 실행하면 된다.
가상환경 만들기
uv venv
.\.venv\Scripts\activate가상환경 만들때 Powershell 실행 정책 에러 해결 방법
Windows의 PowerShell 실행 정책은 기본값이 Restricted 라서 .ps1 스크립트가 전부 차단된다. activate 도 activate.ps1 파일이라 차단된다.
.\.venv\Scripts\activate : 이 시스템에서 스크립트를 실행할 수 없으므로
C:\...\.venv\Scripts\activate.ps1 파일을 로드할 수 없습니다.실행 정책을 바꿔서 해결할 수 있고 따로 관리자 권한은 필요하지 않다.
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSignedRemoteSigned 는 로컬에서 만든 스크립트는 실행하고 다운로드한 스크립트만 서명을 요구하는 정책이다.
SDK 설치와 서버 파일 생성
uv add "mcp[cli]"
New-Item server.py결과 확인
여기까지 따라하면 다음과 같이 폴더가 만들어진다.
exchange-rate-server\
├── .venv\
├── .gitignore
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
├── server.py
└── uv.lockmain.py 는 uv init 이 만든 샘플이라 사용하지 않는다. server.py 가 앞으로 작성할 파일이다.
pyproject.toml 에는 설치한 패키지가 기록된다.
[project]
name = "exchange-rate-server"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = [
"mcp[cli]>=2.2.0",
]1-1에서 설명한 v2가 실제로 설치된 것을 확인할 수 있다.
HTTP 클라이언트는 따로 설치하지 않았는데도 들어와 있다. 공식 문서 설명이다.
httpx2is the HTTP client the SDK itself depends on, so installingmcpalready brought it in.
uv.lock 을 열어보면 httpx2 가 함께 설치된 것이 확인된다. 2장에서 환율 API를 부를 때 사용한다.
코드를 작성하기 전에 주의할 것
stdio로 서버를 만들 때 주의해야 할 것이 있다.
Claude Desktop은 시작할 때 설정 파일을 읽어 MCP 서버를 자식 프로세스로 실행하고, 표준 스트림으로 메시지를 주고받는다.
서버가 stdout에 쓰는 내용은 화면에 출력되는 것이 아니라 전부 Claude Desktop으로 전달된다.
stdout은 한 줄에 JSON-RPC 메시지 하나를 담아서 보낸다. 이때 Claude Desktop은 줄을 JSON으로 해석한다. print() 로 문자열을 보내면 Claude Desktop이 JSON으로 해석하려다 실패하게 된다.
print() 를 사용하고 싶을 때는 표준 라이브러리인 logging 을 사용하면 된다. logging 은 stderr로 출력하기 때문에 Claude Desktop이 JSON으로 해석하지 않는다. 찍은 값은 로그 파일에 따로 쌓이고 %APPDATA%\Claude\logs 의 mcp-server-이름.log 에서 확인할 수 있다.
출처
- Build an MCP server (2026-07-28 버전)
- uv 설치 문서
2. 환율 변환 서버 만들기
2-1 Tool 정의 (convert_currency)
Tools는 LLM이 스스로 판단해 호출을 요청하면 서버가 실행하는 함수이다.
무엇을 받고 무엇을 돌려줄지
도구 이름은 convert_currency 로 만든다. 역할은 금액과 통화 두 개를 받아 변환 결과를 돌려주는 도구이다.
| 받을 값 | 설명 |
|---|---|
amount | 변환할 금액 |
from_currency | 변환 전 통화 코드 |
to_currency | 변환 후 통화 코드 |
"100달러 얼마야"라는 질문이 들어오면 LLM이 amount=100, from_currency=USD, to_currency=KRW 로 채워서 도구를 호출하게 된다.
코드
server.py
from mcp.server import MCPServer
mcp = MCPServer("exchange-rate")
@mcp.tool()
async def convert_currency(amount: float, from_currency: str, to_currency: str) -> str:
"""환율을 조회해서 금액을 변환한다.
Args:
amount: 변환할 금액
from_currency: 변환 전 통화 코드 (예: USD)
to_currency: 변환 후 통화 코드 (예: KRW)
"""
return "아직 구현하지 않음"
if __name__ == "__main__":
mcp.run(transport="stdio")첫 줄부터 설명을 하자면 v1에서는 FastMCP라는 이름을 사용했지만 v2부터는 MCPServer 를 사용한다. 그래서 mcp.server 모듈에서 MCPServer 클래스를 먼저 불러와야 한다. 그리고 MCPServer 객체를 만들어 mcp 변수에 담는데, 괄호 안에 적은 문자열은 이 서버의 이름이 된다. 다음으로는 @mcp.tool() 을 붙여서 아래 함수를 도구로 등록한다. API를 호출하는 도구이기 때문에 비동기 함수로 만들어주고, 함수 이름이 그대로 도구 이름이 되므로 convert_currency로 정해준다.
convert_currency는 총 세 개의 인자를 받는다. amount는 금액이라 실수형인 float 으로 선언해주고, from_currency와 to_currency는 USD나 KRW 같은 통화 코드가 들어오므로 문자열인 str 로 선언해준다. 세 인자 모두 기본값을 주지 않았기 때문에 전부 필수값이 된다. 마지막의 -> str은 이 함수가 문자열을 돌려준다는 뜻이다. 함수 선언 바로 아래 """ 로 감싼 부분은 독스트링이다. 주석처럼 보이지만 실행 중에도 남아 있는 문자열이라 SDK가 읽어갈 수 있고, 이 내용이 그대로 도구 설명이 되어 LLM에게 전달된다. LLM은 이 문장을 보고 언제 이 도구를 써야 할지 판단한다. return은 아직 자리만 잡아둔 것이다. 도구가 무엇을 받고 무엇을 돌려주는지 먼저 정해두고, 실제 환율 조회는 2-2에서 채운다.
마지막 if __name__ == "__main__": 은 이 파일을 직접 실행했을 때만 아래를 실행하라는 뜻이다. mcp.run 이 서버를 stdio 방식으로 띄우고, 이 줄이 실행되면 서버는 stdin으로 메시지가 들어오기를 기다리며 대기 상태가 된다.
SDK가 함수에서 읽어가는 것
데코레이터(@)를 붙이면 SDK가 도구 정의를 만들어준다. 무엇을 보고 만드는지는 아래의 표를 참고하면 된다.
| 도구 정의 | 어디서 가져오나 |
|---|---|
| 이름 | 함수 이름 (convert_currency) |
| 설명 | 독스트링 |
받을 값 (inputSchema) | 타입 힌트 |
| 필수 여부 | 기본값이 있으면 선택, 없으면 필수 |
공식 문서 설명이다.
The name of the tool is the name of the function ... The description the model sees is the docstring ... The arguments the model is allowed to pass come from the type hints
독스트링은 LLM이 읽는다. 사람을 위한 주석이 아니라 LLM이 이 도구를 언제 사용해야 하는지 판단하는 근거다. 서버가 도구 목록을 내줄 때 이 문장이 같이 나가고, LLM은 그것을 보고 도구를 고른다.
타입 힌트도 마찬가지다. amount: float 라고 적어두면 SDK가 스키마를 만들고 들어온 값을 실행 전에 검증한다.
from 은 사용할 수 없다
통화를 나타내는 이름으로는 from 과 to 가 자연스럽다. 그런데 from 은 Python 예약어라 인자 이름으로 사용할 수 없다. 그래서 from_currency , to_currency 로 만들었다.
async def 를 사용하는 이유
이 도구는 환율 API를 호출한다. 공식 문서는 I/O가 있는 도구를 async def 로 선언하라고 권한다.
If a tool does I/O (calls an API, reads a file, queries a database), declare itasync def... A plaindeftool works too: the SDK runs it in a thread.
출처
2-2 환율 API 연동
비워뒀던 함수 안을 채운다. 하는 일은 세 가지다. 환율 API를 호출하고, 응답에서 필요한 값을 꺼내고, 계산해서 돌려준다.
인증키는 코드에 적지 않는다
인증키는 코드에 직접 작성하지 않는다.
api_key = os.environ.get("EXIM_API_KEY")인증키를 코드에 작성하지 않고 환경 변수에 등록해두고, 등록한 이름으로 불러오는 방식으로 선언해야 한다.
환경 변수는 프로그램이 실행될 때 운영체제가 같이 넘겨주는 이름과 값의 목록이다. os.environ.get() 은 환경 변수 목록에서 이름으로 값을 꺼내오기만 한다. 그래서 코드에 남는 것은 인증키가 아니라 키를 부르는 이름뿐이고, server.py 를 그대로 공유해도 인증키는 따라가지 않는다.
인증키 등록과 실행 방법은 아래와 같다. 등록 방법은 두 가지다.
현재 PowerShell 창에만 등록하는 방법
$env:EXIM_API_KEY = "발급받은 인증키"
uv run server.py$env: 문법으로 지금 열려 있는 PowerShell 창의 환경 변수에 EXIM_API_KEY 이름으로 인증키를 등록하고, uv run으로 server.py 를 실행하면 된다. 같은 창에서는 서버를 재실행해도 값이 남아 있지만, 창을 닫으면 사라지기 때문에 새 창에서는 다시 등록해야 한다.
윈도우 환경 변수에 영구 등록하는 방법
# 등록
[Environment]::SetEnvironmentVariable("EXIM_API_KEY", "발급받은 인증키", "User")
# PowerShell 창을 새로 연 뒤
uv run server.py내 계정의 환경 변수로 등록되어 이후에 여는 모든 창에 적용된다. 관리자 권한은 필요 없다. 다만 등록한 뒤에 여는 창부터 반영되므로, 지금 쓰던 창은 닫고 새로 열어야 한다.
MCP 공식 문서도 stdio 서버에는 환경 변수로 인증키를 넘기는 방식을 권장한다.
For MCP servers using the STDIO transport, you can use environment-based credentials or credentials provided by third-party libraries embedded directly in the MCP server instead.
파이썬에서는 .env 파일에 키를 적어두고 라이브러리가 읽어가게 하는 방식도 많이 사용된다.
v1 SDK는 .env 파일을 자동으로 읽어서 환경 변수로 올려줬지만, v2에서는 .env 파일을 읽지 않는다. .env 에 적어두어도 값이 들어오지 않기 때문에 v2에서는 위의 두 방법 중 하나로 등록해야 한다.
응답 구조
응답은 배열 하나로 온다. 배열 안에 원소가 23개 들어 있고, 원소 하나가 통화 하나에 대응하고 원소마다 필드가 11개씩 담겨 있다.
아래는 미국 달러 원소 부분이다.
[
{
"result": 1,
"cur_unit": "USD",
"ttb": "1,366.49",
"tts": "1,394.1",
"deal_bas_r": "1,380.3",
"bkpr": "1,380",
"yy_efee_r": "0",
"ten_dd_efee_r": "0",
"kftc_bkpr": "1,380",
"kftc_deal_bas_r": "1,380.3",
"cur_nm": "미국 달러"
}
]응답에 오는 통화는 23개이고 다음과 같다.
AED AUD BHD BND CAD CHF CNH DKK EUR GBP HKD IDR(100)
JPY(100) KRW KWD MYR NOK NZD SAR SEK SGD THB USD원하는 통화만 요청할 수 없기 때문에, 응답에서 필요한 통화만 골라서 사용해야 한다.
환율 MCP에서 사용할 필드는 두 개뿐이다
여기서 사용할 필드는 두 개다. 첫 번째는 cur_unit 필드로 통화 코드가 담겨 있다. 두 번째는 deal_bas_r 필드로 매매 기준율을 알려준다.
| 필드 | 사용하는 이유 |
|---|---|
cur_unit | 통화 코드. 어느 통화의 환율인지 구분한다 |
deal_bas_r | 매매 기준율, 실제 환산에 사용한다 |
deal_bas_r 은 각 통화 1단위가 원화로 얼마인지를 나타낸다. USD의 값이 1,380.3 이면 1달러가 1,380.3원이라는 뜻이다. 원화도 목록에 들어 있고 값은 1 이다.
모든 통화가 원화라는 같은 기준으로 맞춰져 있기 때문에 변환이 식 하나로 정리된다. 변환 전 통화를 원화로 바꾸고, 그 금액을 변환 후 통화로 다시 나누는 것이다.
변환 결과 = 금액 × 변환 전 통화의 원화값 ÷ 변환 후 통화의 원화값경우를 나눠 쓰지 않아도 되는 이유는 원화의 값이 1 이기 때문이다.
| 질문 | 계산 |
|---|---|
| 100달러는 얼마인가 | 100 × 1380.3 ÷ 1 = 138,030원 |
| 100만원은 몇 달러인가 | 1000000 × 1 ÷ 1380.3 = 약 724달러 |
| 100달러는 몇 엔인가 | 100 × 1380.3 ÷ 8.8529 = 약 15,591엔 |
원화로 바꿀 때는 나누기가, 원화에서 바꿀 때는 곱하기가 1 이라 계산에 영향을 주지 않는다. 원화가 끼지 않는 변환에서만 두 계산이 모두 작동한다. 그래서 경우를 나누지 않고 식 하나로 처리할 수 있다.
엔화의 8.8529 는 100엔 기준값인 885.29 를 100으로 나눈 값이다.
코드
server.py 의 도구 함수 위에 환율을 가져오는 함수를 하나 만든다.
import os
import httpx2
from mcp.server import MCPServer
mcp = MCPServer("exchange-rate")
API_URL = "https://oapi.koreaexim.go.kr/site/program/financial/exchangeJSON"
async def fetch_rates() -> dict[str, float]:
"""환율 API를 호출해서 통화 코드별 원화 환산값을 돌려준다."""
api_key = os.environ.get("EXIM_API_KEY")
params = {"authkey": api_key, "data": "AP01"}
async with httpx2.AsyncClient() as client:
response = await client.get(API_URL, params=params, timeout=10.0)
rows = response.json()
rates = {}
for row in rows:
unit = row["cur_unit"]
rate = float(row["deal_bas_r"].replace(",", ""))
if "(" in unit:
code, per = unit.split("(")
rates[code] = rate / float(per.rstrip(")"))
else:
rates[unit] = rate
return rates
# 이 아래에 2-1에서 만든 @mcp.tool() 도구 함수가 이어진다환경 변수를 읽기 위해 os 모듈이 필요하고 API요청을 하기 위해서는 httpx2 모듈이 필요해 각각 import 로 os, httpx2를 불러온다.
다음으로는 실제 요청할 API주소를 API_URL에 작성했다. 다음으로는 fetch_rates함수를 보면 함수의 반환 타입을 딕셔너리로 설정하였고 키는 str로 통화 코드가 들어가고 값은 float로 원화 환산값이 들어간다.
함수 안에서는 먼저 환경 변수에서 인증키를 꺼내 api_key에 담는다. params에는 API에 보낼 값을 담는데, authkey에는 인증키를 넣고 data에는 환율을 뜻하는 AP01을 넣는다. searchdate는 생략했기 때문에 현재일로 조회된다.
그다음 httpx2로 클라이언트를 열어 API_URL에 GET 요청을 보낸다. params에 담아둔 값들이 주소 뒤에 붙어서 전송된다. timeout을 10초로 준 것은 API가 응답하지 않을 때 무한정 기다리지 않게 하기 위해서다. 받아온 응답은 json()으로 파이썬 객체로 바꿔 rows에 담는다. 응답이 배열이었으므로 rows는 리스트가 된다.
이제 rows를 사용하기 좋은 형태로 바꿔준다. 빈 딕셔너리 rates를 만들어두고 원소를 하나씩 돌면서 cur_unit과 deal_bas_r을 꺼낸다. deal_bas_r은 문자열로 오고 천 단위에 쉼표가 들어가기 때문에 replace로 쉼표를 지우고 float로 바꿔준다.
통화 코드에 괄호가 있는지 확인하는 이유는 JPY(100) 처럼 100단위로 고시되는 통화가 있기 때문이다. 괄호가 있으면 split으로 앞뒤를 나눈 뒤 rstrip으로 닫는 괄호를 떼고, 괄호 안 숫자로 나눠서 1단위 값으로 맞춘다. 괄호가 없으면 그대로 넣는다.
마지막으로 완성된 rates를 return해준다.
환율을 불러오는 코드를 만들었으니 이제는 convert_currency 함수에 위에서 만든 fetch_rates()를 사용한다.
@mcp.tool()
async def convert_currency(amount: float, from_currency: str, to_currency: str) -> str:
"""환율을 조회해서 금액을 변환한다.
Args:
amount: 변환할 금액
from_currency: 변환 전 통화 코드 (예: USD)
to_currency: 변환 후 통화 코드 (예: KRW)
"""
rates = await fetch_rates()
source = from_currency.upper()
target = to_currency.upper()
converted = amount * rates[source] / rates[target]
return f"{amount:,.2f} {source} = {converted:,.2f} {target}"도구 함수 안에서는 먼저 fetch_rates를 호출해 환율 목록을 받아 rates에 담는다. 앞에 await를 붙인 것은 fetch_rates가 비동기 함수이기 때문이다. 비동기 함수는 await 없이 호출하면 실행되지 않고 코루틴 객체만 돌아온다.
다음으로는 받은 통화 코드를 upper로 대문자로 바꿔 source와 target에 담는다. LLM이 usd처럼 소문자로 채워 보낼 수 있는데, rates의 키는 USD처럼 대문자라 그대로 조회하면 찾지 못하기 때문이다.
마지막으로 앞에서 세운 식을 그대로 옮겨 계산하고 결과를 문자열로 만들어 돌려준다. :,.2f 는 천 단위에 쉼표를 넣고 소수점 두 자리까지 보여달라는 서식이다. 100달러를 원화로 바꾸면 100.00 USD = 138,030.00 KRW 같은 문자열이 나온다.
여기까지는 모든 것이 정상일 때만 동작한다. 에러가 났을 때의 처리는 다음 2-3에서 설명한다.
출처
2-3 에러 처리
API 인증키 에러
환율 API는 인증키가 틀려도 HTTP 상태 코드를 200 으로 응답한다. 실제로 틀린 키로 호출해보면 다음과 같은 응답이 온다.
[{"result":3,"cur_unit":null,"ttb":null,"tts":null,"deal_bas_r":null,"bkpr":null,"yy_efee_r":null,"ten_dd_efee_r":null,"kftc_bkpr":null,"kftc_deal_bas_r":null,"cur_nm":null}]응답은 정상적으로 왔고 모든 필드가 null 이며 result 만 3 이다. 실제 데이터가 들어 있는 정상 응답은 result 가 1 이 나와야 한다. 여기서 주의할 점이 있다. response.raise_for_status() 같은 HTTP 상태 검사로는 이 실패를 잡을 수 없다. 상태 코드가 아니라 본문의 result 값을 봐야 한다.
환율 조회가 실패하는 경우
에러를 처리하기 위해 무슨 에러들이 나는지부터 파악해야 한다. 그래서 나올 수 있는 에러를 아래의 표에 정리했다.
| 상황 | 어떻게 알아차리나 |
|---|---|
| 인증키가 설정되지 않음 | 환경 변수가 비어 있다 |
| 인증키가 틀림 | result가3 |
| 일일 호출 한도 초과 | result가4 |
| 주말·공휴일, 11시 이전 | 배열이 비어서 온다 |
| 없는 통화 코드 | 환율 목록에 해당 코드가 없다 |
인증키가 설정되지 않은 경우는 환경 변수에서 읽어온 값이 비어 있는지로 알 수 있고, 인증키가 틀리거나 일일 호출 한도를 넘긴 경우는 응답 본문의 result 값으로 구분한다. 주말이나 공휴일, 영업일 11시 이전에는 고시된 환율이 없어서 배열이 비어서 오는데, 에러가 아니라 정상 응답인데 내용만 없는 상태다. 없는 통화 코드는 응답을 다 받은 뒤 rates에 해당 코드가 있는지 확인해야 알 수 있다.
ToolError로 LLM에게 전달한다
SDK는 도구 안에서 사용하는 예외 클래스를 두 가지 제공한다.
| 구분 | 언제 사용하나 | LLM이 보는 것 |
|---|---|---|
ToolError | 실행이 실패했고 LLM이 고쳐볼 여지가 있을 때 | 적어보낸 메시지 |
MCPError | 요청 자체가 성립하지 않을 때 | 없음 |
공식 문서가 제시하는 기준은 한 문장이다.
Key question: Could a smarter model have avoided this error? Yes →ToolError. No →MCPError.
ToolError 를 사용하면 응답이 is_error=True 로 돌아가고 메시지가 LLM에게 그대로 전달된다. 이 값은 실제로 오가는 JSON에서는 isError 로 표기되며 3-2에서 확인한다. LLM은 그 메시지를 읽고 값을 고쳐 다시 호출하거나 사용자에게 상황을 설명할 수 있다. 그래서 ToolError 를 사용하여 에러 처리를 한다.
나머지 예외는 따로 잡지 않는다. 공식 문서는 ToolError 와 MCPError 가 아닌 예외를 이렇게 처리한다고 명시한다.
Model receives only:"Error executing tool <name>"/ Server logs full traceback atERRORlevel / No details leak to the client about internal state
예상하지 못한 에러의 내부 내용이 클라이언트로 나가지 않고 서버 로그에만 남는다.
코드
예외 클래스를 가져오고 result 코드별 메시지를 정리해둔다.
import os
import httpx2
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError # 추가
mcp = MCPServer("exchange-rate")
API_URL = "https://oapi.koreaexim.go.kr/site/program/financial/exchangeJSON"
# 추가
RESULT_MESSAGE = {
2: "요청한 데이터 종류가 잘못되었다.",
3: "인증키가 잘못되었다.",
4: "일일 호출 한도를 넘었다.",
}ToolError는 mcp.server.mcpserver.exceptions에서 가져온다. RESULT_MESSAGE는 result 값을 키로, LLM에게 보여줄 메시지를 값으로 갖는 딕셔너리다. 코드마다 if를 나열하는 대신 딕셔너리에서 꺼내 사용하면 처리할 코드가 늘어도 한 줄만 추가하면 된다. 2 는 data 값이 잘못됐을 때인데 AP01 을 고정해서 보내므로 실제로는 나오지 않는다. 명세에 있는 값이라 같이 적어두었다.
fetch_rates 함수에 ToolError를 두 개 추가한다.
async def fetch_rates() -> dict[str, float]:
"""환율 API를 호출해서 통화 코드별 원화 환산값을 돌려준다."""
api_key = os.environ.get("EXIM_API_KEY")
if not api_key:
raise ToolError("EXIM_API_KEY 환경 변수가 설정되어 있지 않다.")
params = {"authkey": api_key, "data": "AP01"}
async with httpx2.AsyncClient() as client:
response = await client.get(API_URL, params=params, timeout=10.0)
rows = response.json()
if not rows:
raise ToolError("환율 데이터가 비어 있다. 주말·공휴일이거나 영업일 11시 이전이다.")
result = rows[0].get("result")
if result != 1:
raise ToolError(RESULT_MESSAGE.get(result, f"환율 조회에 실패했다. result={result}"))
rates = {}
for row in rows:
unit = row["cur_unit"]
rate = float(row["deal_bas_r"].replace(",", ""))
if "(" in unit:
code, per = unit.split("(")
rates[code] = rate / float(per.rstrip(")"))
else:
rates[unit] = rate
return rates검사는 세 군데 들어간다. 먼저 인증키를 꺼낸 직후에 값이 비어 있는지 확인한다. 환경 변수를 등록하지 않고 서버를 실행하면 여기서 걸린다.
다음은 응답을 받은 직후다. rows가 비어 있으면 주말이나 공휴일, 또는 영업일 11시 이전이다. 이 검사가 없으면 아래 반복문이 한 번도 돌지 않아 빈 딕셔너리가 돌아가고, 도구는 환율을 못 가져왔다는 말 대신 통화를 못 찾았다는 엉뚱한 메시지를 내놓게 된다.
마지막은 result 검사다. 값이 1이 아니면 RESULT_MESSAGE에서 해당 메시지를 꺼내 ToolError를 호출한다. get의 두 번째 인자는 딕셔너리에 없는 값이 왔을 때 대신 사용할 문장이다. 명세에 없는 코드가 오더라도 서버가 죽지 않고 값을 그대로 알려준다.
도구 함수에는 통화 코드 검사를 넣는다.
@mcp.tool()
async def convert_currency(amount: float, from_currency: str, to_currency: str) -> str:
"""환율을 조회해서 금액을 변환한다.
Args:
amount: 변환할 금액
from_currency: 변환 전 통화 코드 (예: USD)
to_currency: 변환 후 통화 코드 (예: KRW)
"""
rates = await fetch_rates()
source = from_currency.upper()
target = to_currency.upper()
# 추가
for code in (source, target):
if code not in rates:
raise ToolError(f"{code}는 지원하지 않는 통화 코드다.")
converted = amount * rates[source] / rates[target]
return f"{amount:,.2f} {source} = {converted:,.2f} {target}"source와 target을 차례로 확인해서 rates에 없으면 ToolError를 호출한다. 이 검사가 없으면 바로 아래에서 rates[source]를 조회할 때 KeyError가 난다. KeyError는 ToolError도 MCPError도 아니기 때문에 LLM은 이유를 모른 채 "Error executing tool convert_currency"만 받게 된다. 검사를 넣어두면 어떤 통화가 문제인지까지 전달된다.
출처
2-4 전체 코드
아래는 server.py 의 전체 코드이다.
import os
import httpx2
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
mcp = MCPServer("exchange-rate")
API_URL = "https://oapi.koreaexim.go.kr/site/program/financial/exchangeJSON"
RESULT_MESSAGE = {
2: "요청한 데이터 종류가 잘못되었다.",
3: "인증키가 잘못되었다.",
4: "일일 호출 한도를 넘었다.",
}
async def fetch_rates() -> dict[str, float]:
"""환율 API를 호출해서 통화 코드별 원화 환산값을 돌려준다."""
api_key = os.environ.get("EXIM_API_KEY")
if not api_key:
raise ToolError("EXIM_API_KEY 환경 변수가 설정되어 있지 않다.")
params = {"authkey": api_key, "data": "AP01"}
async with httpx2.AsyncClient() as client:
response = await client.get(API_URL, params=params, timeout=10.0)
rows = response.json()
if not rows:
raise ToolError("환율 데이터가 비어 있다. 주말·공휴일이거나 영업일 11시 이전이다.")
result = rows[0].get("result")
if result != 1:
raise ToolError(RESULT_MESSAGE.get(result, f"환율 조회에 실패했다. result={result}"))
rates = {}
for row in rows:
unit = row["cur_unit"]
rate = float(row["deal_bas_r"].replace(",", ""))
if "(" in unit:
code, per = unit.split("(")
rates[code] = rate / float(per.rstrip(")"))
else:
rates[unit] = rate
return rates
@mcp.tool()
async def convert_currency(amount: float, from_currency: str, to_currency: str) -> str:
"""환율을 조회해서 금액을 변환한다.
Args:
amount: 변환할 금액
from_currency: 변환 전 통화 코드 (예: USD)
to_currency: 변환 후 통화 코드 (예: KRW)
"""
rates = await fetch_rates()
source = from_currency.upper()
target = to_currency.upper()
for code in (source, target):
if code not in rates:
raise ToolError(f"{code}는 지원하지 않는 통화 코드다.")
converted = amount * rates[source] / rates[target]
return f"{amount:,.2f} {source} = {converted:,.2f} {target}"
if __name__ == "__main__":
mcp.run(transport="stdio")서버 실행 방법
uv run server.py실행하면 아무 출력 없이 멈춰 있는데 정상이다. stdio 서버는 클라이언트가 stdin으로 메시지를 보내주기를 기다리는 상태로 있기 때문이다.
3. 서버 동작 확인 (MCP Inspector)
MCP Inspector는 서버를 브라우저에서 직접 호출해볼 수 있는 공식 도구다. Node.js로 실행하기 때문에 먼저 Node.js를 설치해야 한다.
Node.js 설치
공식 사이트에서 LTS 버전을 내려받아 설치한다.
PowerShell에서 winget으로 설치해도 된다.
winget install OpenJS.NodeJS.LTS설치 후 터미널을 다시 열고 확인한다.
node --version
npx --version3-1 Inspector 실행
Inspector는 서버를 자식 프로세스로 실행하고 stdio로 연결한다. Claude Desktop이 하는 일과 같다. 차이는 오가는 메시지를 화면에서 그대로 볼 수 있다는 점이다. 서버를 붙여놓고 테스트와 디버깅을 하는 도구라고 보면 된다.
실행
server.py 가 있는 폴더에서 실행한다.
npx @modelcontextprotocol/inspector -e "EXIM_API_KEY=$env:EXIM_API_KEY" uv run server.pynpx 는 패키지를 설치하지 않고 바로 실행하는 명령이고 @modelcontextprotocol/inspector 가 Inspector 패키지다. 뒤에 붙은 uv run server.py 는 Inspector가 실행할 서버 명령이다. 2-4에서 서버를 직접 실행하던 명령을 그대로 붙이면 된다.
서버를 미리 띄워둘 필요는 없다. Inspector가 이 명령을 자식 프로세스로 실행하고 그 프로세스의 stdin과 stdout에 붙어서 메시지를 주고받는다.
명령 중간의 -e 는 서버에 넘길 환경 변수를 이름=값 형태로 지정하는 옵션이다. 이 옵션 없이 실행하면 도구를 호출했을 때 다음 에러가 나온다.
Error executing tool convert_currency: EXIM_API_KEY 환경 변수가 설정되어 있지 않다.2-2에서 환경 변수를 등록했는데도 나온다. Inspector가 지금 열려 있는 창의 환경 변수를 서버에 그대로 넘기지 않기 때문이다. Windows에서 넘겨주는 환경 변수는 다음 12개로 고정되어 있다.
APPDATA HOMEDRIVE HOMEPATH LOCALAPPDATA
PATH PROGRAMFILES SYSTEMDRIVE SYSTEMROOT
TEMP USERNAME USERPROFILE PROCESSOR_ARCHITECTURE인증키를 담아둔 EXIM_API_KEY 는 이 목록에 없다. 서버에 연결하고 도구 목록을 보는 것까지는 인증키가 없어도 되지만, 도구를 호출하는 순간부터는 없으면 동작하지 않는다. 그래서 처음 실행할 때부터 같이 넣어야 한다.
-e 는 여러 번 사용할 수 있다. 위 명령은 지금 창에 등록된 EXIM_API_KEY 값을 꺼내서 그대로 넘기는 방식이다. 인증키를 명령에 직접 적어도 동작하지만 그렇게 하면 PowerShell 명령 기록에 인증키가 남는다.
접속
실행하면 터미널에 주소가 출력되고 브라우저가 자동으로 열린다.
MCP Inspector Web is up and running at:
http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=<토큰>
Sandbox (MCP Apps): http://127.0.0.1:6275/sandbox
Auth token: <토큰>
Opening browser...브라우저가 열리지 않으면 출력된 주소를 직접 열면 된다. 주소 뒤에 붙은 토큰은 실행할 때마다 새로 만들어지는 값이고 Inspector의 /api 경로를 보호한다. 다만 브라우저로 페이지를 열면 서버가 이 토큰을 HTML에 심어서 내려주기 때문에, 주소에서 토큰을 빼고 http://127.0.0.1:6274 만 열어도 동작한다.
토큰이 막는 대상은 사용자가 아니라 다른 사이트다. 다른 출처의 페이지는 이 HTML을 읽을 수 없어서 토큰을 얻지 못하고, 그래서 /api 를 호출할 수 없다.
기본 포트는 6274이고 127.0.0.1 에만 바인드된다. 같은 PC에서만 접속된다.
프로토콜 버전
서버가 연결되면 Servers 탭에서 연결 상태를 확인할 수 있다.

서버 카드 오른쪽에 MCP 2025-11-25이, Protocol 패널에 LEGACY 배지가 보인다. 현재 명세는 2026-07-28인데 이전 버전으로 연결된 것이다.
Inspector의 protocolEra 설정 기본값이 legacy 이기 때문이다. legacy 는 initialize 로 버전을 맞추는 기존 방식이고 modern 은 server/discover 를 사용하는 방식이다. 명령에 --protocol-era 를 붙여서 바꿀 수 있고 legacy , auto , modern 세 가지를 받는다.
npx @modelcontextprotocol/inspector --protocol-era modern -e "EXIM_API_KEY=$env:EXIM_API_KEY" uv run server.py출처
3-2 실제로 오가는 메시지 확인
Inspector 화면은 세 영역으로 나뉜다. 왼쪽에서 도구를 고르고, 가운데에서 값을 넣어 호출하고 결과를 보고, 오른쪽 Protocol 탭에서 그때 오간 JSON-RPC 메시지를 본다.
서버가 내준 도구 정의
Tools 탭을 열면 서버가 tools/list 로 돌려준 도구 목록이 나온다. Protocol 탭에서 실제로 오간 응답을 보면 다음과 같다.

{
"jsonrpc": "2.0",
"id": 2,
"result": {
"tools": [
{
"description": "환율을 조회해서 금액을 변환한다.\n\nArgs:\n amount: 변환할 금액\n from_currency: 변환 전 통화 코드 (예: USD)\n to_currency: 변환 후 통화 코드 (예: KRW)\n",
"inputSchema": {
"properties": {
"amount": { "title": "Amount", "type": "number" },
"from_currency": { "title": "From Currency", "type": "string" },
"to_currency": { "title": "To Currency", "type": "string" }
},
"required": ["amount", "from_currency", "to_currency"],
"type": "object",
"title": "convert_currencyArguments"
},
"name": "convert_currency",
"outputSchema": {
"properties": {
"result": { "title": "Result", "type": "string" }
},
"required": ["result"],
"type": "object",
"title": "convert_currencyOutput"
}
}
]
}
}바깥의 jsonrpc , id , result 는 JSON-RPC 봉투다. id 는 요청과 응답을 짝지어 주는 번호라 호출할 때마다 올라가고, 서버가 만든 내용은 전부 result 안에 들어간다. 앞으로 나오는 응답도 전부 같은 형태다.
2-1에서 표로 정리한 내용이 그대로 들어가 있다. name 은 함수 이름에서, description 은 독스트링에서, inputSchema 는 타입 힌트에서 나왔다. 파이썬의 float 가 number 로, str 이 string 으로 바뀌었고 기본값을 주지 않은 세 인자가 전부 required 에 들어갔다.
outputSchema 는 반환 타입인 -> str 에서 만들어졌다. 문자열 하나를 result 라는 이름으로 감싼 형태다.
LLM이 보는 것은 이 JSON이 전부다. 함수 본문은 전달되지 않는다. 어떤 상황에 이 도구를 사용할지는 description 으로만 판단한다.
도구 호출
화면 맨 위의 탭에서 Tools를 클릭하면 다음과 같은 화면이 나온다.

왼쪽 목록에서 convert_currency 를 클릭하면 inputSchema 에 맞춰 입력칸이 세 개 만들어진다. 각각 값을 채우고 Execute Tool을 누르면 실제로 도구가 호출되면서 tools/call 이 나간다. 아래는 예시로 넣은 값이다.
amount : 100
from_currency : USD
to_currency : KRW응답은 다음과 같다.
{
"jsonrpc": "2.0",
"id": 15,
"result": {
"content": [
{
"text": "100.00 USD = 138,030.00 KRW",
"type": "text"
}
],
"isError": false,
"structuredContent": {
"result": "100.00 USD = 138,030.00 KRW"
}
}
}content 는 LLM이 읽는 본문이고 structuredContent 는 앞에서 본 outputSchema 형태에 맞춰 같은 값을 한 번 더 담은 것이다. Inspector 화면에서는 content 가 Results에, structuredContent 가 Structured Output에 표시된다. isError 가 false 면 정상이다.


에러가 날 때
2-3에서 넣은 ToolError 가 어떻게 전달되는지 확인한다. 응답에 없는 통화 코드인 INR을 넣고 호출해보면 된다.
{
"jsonrpc": "2.0",
"id": 16,
"result": {
"content": [
{
"text": "Error executing tool convert_currency: INR는 지원하지 않는 통화 코드다.",
"type": "text"
}
],
"isError": true
}
}
넣어둔 메시지가 content 에 그대로 담기고 isError 만 true 로 바뀌었다. 앞에 붙은 Error executing tool convert_currency: 는 SDK가 붙이는 접두사다.
여기서 볼 것은 정상 응답과 형태가 같다는 점이다. JSON-RPC 에러로 내려오는 것이 아니라 도구 실행 결과로 내려온다. 그래서 LLM이 이 문장을 읽고 통화 코드를 고쳐 다시 호출하거나 사용자에게 상황을 설명할 수 있다.
인증키를 넘기지 않고 호출해도 같은 형태로 온다. 메시지만 다르다.
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"text": "Error executing tool convert_currency: EXIM_API_KEY 환경 변수가 설정되어 있지 않다.",
"type": "text"
}
],
"isError": true
}
}2-3에서 정리한 다섯 가지 상황이 전부 이 형태로 나간다. 서버가 죽지 않고 에러 내용이 LLM까지 전달된다.
출처
4. Claude Desktop에 연결하기
서버가 정상으로 동작하는 것을 확인했으니 Claude Desktop에 환율 MCP 서버를 추가할 것이다. 추가하는 방법은 Claude Desktop 설정 파일(claude_desktop_config.json)에 서버를 실행하는 명령을 적어두는 것이다. Claude Desktop은 시작할 때 이 파일을 읽어서 적힌 명령을 실행한다.
설정 창에는 커넥터 추가 메뉴도 있는데 이것은 다른 용도다. 커넥터는 인터넷에 올라가 있는 원격 MCP 서버를 HTTPS 주소로 연결하는 기능이라 입력할 수 있는 값이 주소뿐이다. 지금 만든 서버는 내 PC에서 stdio로 도는 로컬 서버여서 주소가 없고, 그래서 커넥터로는 추가할 수 없다.
4-1 설정 파일 작성
설정 파일 열기
Claude Desktop에서 설정을 열고 왼쪽 목록의 데스크톱 앱 항목에서 개발자를 고르면 다음과 같은 화면이 나온다.

로컬 MCP 서버를 관리하는 화면이다. 아직 추가한 서버가 없어서 비어 있다. 여기서 구성 편집을 클릭하면 설정 파일이 만들어지고 파일이 있는 폴더가 열린다. 위치는 다음과 같다.
%APPDATA%\Claude\claude_desktop_config.json이미 파일이 있으면 새로 만들지 않고 폴더를 열어준다. macOS는 ~/Library/Application Support/Claude/claude_desktop_config.json 에 있다.
다만 Microsoft Store에서 설치했다면 위 경로에 파일이 생기지 않는다. Store 앱은 %APPDATA% 에 쓰는 내용을 패키지 전용 폴더로 돌려보내기 때문이다. 실제 위치는 다음과 같다.
%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json구성 편집 버튼을 누르면 어느 쪽이든 실제 파일이 있는 폴더가 열리기 때문에 경로를 직접 찾아갈 일은 없다.
설정 내용
열린 폴더에서 claude_desktop_config.json 을 메모장 같은 편집기로 열고 다음 내용을 넣는다.
{
"mcpServers": {
"exchange-rate": {
"command": "uv",
"args": [
"--directory",
"C:\\{프로젝트 경로}\\exchange-rate-server",
"run",
"server.py"
],
"env": {
"EXIM_API_KEY": "발급받은 인증키"
}
}
}
}파일을 통째로 덮어쓰면 안 된다. 구성 편집으로 만들어진 파일에는 mcpServers 말고도 preferences 같은 Claude Desktop 자체 설정이 들어 있어서 같이 날아간다. 이미 등록해둔 다른 MCP 서버가 있을 때도 마찬가지다.
채워야 할 곳은 mcpServers 안쪽뿐이다. 이미 다른 항목이 있으면 그 항목의 닫는 중괄호 뒤에 쉼표를 찍고 이어서 적는다.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\{사용자}\\Desktop"]
},
"exchange-rate": {
"command": "uv",
"args": ["--directory", "C:\\{프로젝트 경로}\\exchange-rate-server", "run", "server.py"],
"env": { "EXIM_API_KEY": "발급받은 인증키" }
}
}
}서버는 mcpServers 안에 이름을 키로 해서 나란히 적는다. 이름만 겹치지 않으면 개수 제한은 없다.
결국 이 설정은 uv --directory {프로젝트 경로} run server.py 를 실행하라는 뜻이다. 3장에서 Inspector 뒤에 붙였던 명령과 같고, 실행 위치를 명령에 직접 적어준다는 것만 다르다.
| 항목 | 설명 |
|---|---|
mcpServers | 연결할 서버들을 담는 곳. 서버가 여러 개면 여기에 나란히 적는다 |
exchange-rate | 서버를 부를 이름. 내가 정하면 되고 로그 파일 이름에도 사용된다 |
command | 실행할 프로그램 |
args | 프로그램에 넘길 인자를 순서대로 나눈 목록 |
env | 서버에 넘겨줄 환경 변수 |
경로를 적을 때 주의할 것
경로를 적는 곳은 두 군데다. args 에 적는 프로젝트 경로와 command 에 적는 실행 파일 경로다.
절대 경로를 적어야 한다. Claude Desktop은 자기 위치에서 서버를 실행하기 때문에 상대 경로를 적으면 파일을 찾지 못한다. 프로젝트 폴더에서 pwd 를 입력하면 현재 경로가 나온다.
역슬래시는 두 개씩 적는다. JSON에서 역슬래시 하나는 특수문자 표시로 해석된다. C:\\Users\\... 처럼 두 개를 적거나 C:/Users/... 처럼 슬래시를 사용한다.
uv 를 못 찾으면 전체 경로를 적는다. command 에 이름만 적으면 Claude Desktop이 실행 파일을 찾지 못해 서버가 아예 뜨지 않는 경우가 있다. 공식 문서에도 주의로 적혀 있다.
You may need to put the full path to theuvexecutable in thecommandfield. You can get this by runningwhich uvon macOS/Linux orwhere uvon Windows.
설치 위치는 PowerShell에서 확인할 수 있다.
where.exe uv나온 경로를 command 에 그대로 넣으면 된다. 이때도 역슬래시는 두 개씩 적는다.
"command": "C:\\Users\\{사용자}\\.local\\bin\\uv.exe"인증키는 env에 적는다
3장에서 Inspector에 -e 로 넘기던 값을 여기서는 env 에 적는다. Claude Desktop도 서버에 환경 변수를 그대로 넘기지 않기 때문에, 윈도우 환경 변수에 등록해둔 것만으로는 서버가 인증키를 받지 못한다.
env 에 적은 값은 서버 프로세스에만 전달되고, 2-2에서 작성한 os.environ.get("EXIM_API_KEY") 가 값을 꺼낸다.
여기서 짚고 넘어갈 점이 있다. 인증키가 설정 파일에 평문으로 저장된다. 코드에서만 빼낸 것이지 어딘가에는 적어야 하고, stdio 서버에서는 이 방식이 공식 권장이다. 다만 이 파일을 다른 사람과 공유하거나 저장소에 올리면 인증키가 그대로 따라간다.
저장하고 재시작
설정은 Claude Desktop이 시작할 때만 읽힌다. 저장한 다음 완전히 종료하고 다시 실행해야 한다. 창을 닫는 것만으로는 프로그램이 남아 있어서 반영되지 않는다. 작업 표시줄 오른쪽 아이콘에서 종료하면 된다.
연결 확인
다시 실행한 뒤 설정에서 개발자를 다시 열어보면 exchange-rate 가 목록에 올라와 있고 실행 중으로 표시된다. 설정 파일에 적어둔 명령어와 인수도 같이 보인다.

연결이 안 될 때
서버가 실행 중으로 표시되지 않으면 로그를 본다. 같은 화면의 로그 보기 버튼을 누르면 로그 폴더가 바로 열린다. 1-3에서 설명한 stderr 출력이 여기에 쌓인다.
%APPDATA%\Claude\logs파일은 두 종류다. mcp.log 는 연결 자체에 대한 기록이고, mcp-server-exchange-rate.log 는 서버가 stderr로 내보낸 내용이다. 뒤에 붙는 이름은 설정 파일에 적은 서버 이름이다.
폴더 위치도 설정 파일과 같은 규칙을 따른다. Store에서 설치했다면 %APPDATA%\Claude\logs 가 아니라 패키지 폴더 아래에 쌓인다. 로그 보기 버튼을 사용하면 경로를 직접 찾아갈 필요가 없다.
터미널에서 보고 싶다면 로그 보기로 열린 폴더 경로를 그대로 넣으면 된다.
Get-Content "{로그 폴더 경로}\mcp.log" -Tail 30자주 나오는 원인은 세 가지다. 경로를 상대 경로로 적은 경우, 역슬래시를 하나만 적어서 JSON이 깨진 경우, uv 를 찾지 못한 경우다.
4-2 실제로 물어본 결과
연결을 마쳤으니 그냥 물어보면 된다. 도구 이름이나 통화 코드를 말해줄 필요는 없다.
100달러 지금 원화로 얼마야?도구를 실행하기 전에 허가를 물어보는지는 권한 모드가 정한다. 기본값인 자동 모드에서는 호출마다 위험한 작업인지 프롬프트 인젝션인지를 먼저 확인하고, 위험도가 낮다고 판단한 것은 물어보지 않고 그대로 실행한다. 환율 조회처럼 값을 읽어오기만 하는 도구는 여기에 해당해서 허가 창이 뜨지 않는다.

여기서 봐야 할 것은 통화 코드를 직접 알려주지 않았는데도 제대로 채워서 호출했다는 점이다. "100달러"를 from_currency=USD 로, "원화"를 to_currency=KRW 로 바꿔서 보냈다. 이것을 판단한 근거가 3-2에서 본 tools/list 응답이다. 독스트링과 타입 힌트로 만들어진 그 JSON 말고는 서버에 대해 아는 것이 없다.
에러가 났을 때도 마찬가지다. 지원하지 않는 통화를 물어보면 2-3에서 ToolError 로 적어둔 메시지가 그대로 전달된다.
100루피는 원화로 얼마야?
도구 호출은 실패했지만 답은 돌아왔다. 화면 위에 사용한 도구 중 하나가 실패했다고 표시되어 있고, 실패한 이유를 읽고 웹 검색으로 방향을 바꿔 환율을 찾았다. 답변에도 연결된 환율 도구가 INR을 지원하지 않아서 웹 검색을 사용했다고 적혀 있다.
이 문장이 나온 근거가 2-3에서 코드에 적은 INR는 지원하지 않는 통화 코드다. 한 줄이다. 서버가 죽거나 아무 말도 없이 실패하는 것이 아니라, 적어둔 문장이 LLM에게 전달되고 LLM은 그것을 읽고 다음 행동을 정한다. 에러 메시지를 사람이 아니라 LLM이 읽는다는 것이 여기서 드러난다.
다만 이러한 동작은 웹 검색 같은 다른 수단이 있을 때 나온다. 수단이 없으면 적어둔 이유를 그대로 설명하고 끝난다.
출처