MCP Inspector: 127.0.0.1로 접속해야 하는 이유

---

MCP Inspector: 127.0.0.1로 접속해야 하는 이유

Model Context Protocol (MCP) 서버를 개발하고 MCP Inspector로 테스트할 때, localhost 대신 127.0.0.1을 사용해야 하는 이유에 대해 알아보겠다. 이 작은 설정 차이가 통신 실패의 원인이 될 수 있다.

---

문제의 원인: localhost와 127.0.0.1의 차이

많은 개발자들이 로컬 환경에서 테스트할 때 localhost를 사용한다. localhost는 시스템의 로컬 호스트를 가리키는 편리한 이름이지만, 운영 체제에 따라 IPv4 주소인 127.0.0.1로 해석될 수도 있고 IPv6 주소인 ::1로 해석될 수도 있다.

Error from MCP server: FetchError: request to http://localhost:8000/mcp failed, reason: connect ECONNREFUSED ::1:8000
    at ClientRequest.<anonymous> (file:///C:/Users/dandycode/AppData/Local/npm-cache/_npx/5a9d879542beca3a/node_modules/node-fetch/src/index.js:108:11)
    at ClientRequest.emit (node:events:529:35)
    at Socket.socketErrorListener (node:_http_client:501:9)
    at Socket.emit (node:events:517:28)
    at emitErrorNT (node:internal/streams/destroy:151:8)
    at emitErrorCloseNT (node:internal/streams/destroy:116:3)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21) {
  type: 'system',
  errno: 'ECONNREFUSED',
  code: 'ECONNREFUSED',
  erroredSysCall: 'connect'
}

대부분의 MCP 서버는 uvicorn을 통해 IPv4 주소인 127.0.0.1에서만 기본적으로 연결을 수신하도록 설정된다. 만약 MCP Inspector가 localhost를 IPv6 주소인 ::1로 해석하고 연결을 시도하면, 서버는 이 요청을 인식하지 못해 ECONNREFUSED (연결 거부) 오류를 반환하게 된다. 따라서 서버와 클라이언트의 주소 체계를 일치시키는 것이 중요하다.

---

MCP 서버 예시 코드

먼저 간단한 MCP 서버 코드를 작성해 보겠다. 이 예시는 fastmcp 라이브러리를 사용하며, 두 개의 간단한 도구를 포함하고 있다.

# mcp_server.py
from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field

# FastMCP 인스턴스를 생성한다.
mcp = FastMCP("Simple MCP Server")

@mcp.tool()
def hello(name: str = "아무개") -> str:
    """간단한 인사말을 반환하는 도구"""
    return f"안녕하세요, {name}님!"

class StockHistoryInput(BaseModel):
    ticker: str = Field(..., title="주식 코드")
    period: str = Field(..., title="조회 기간 (예: 1d, 1mo)")

@mcp.tool()
def get_stock_history(stock_history_input: StockHistoryInput) -> str:
    """주식 종목의 가상 데이터를 조회하는 함수"""
    # 실제 yfinance 라이브러리 대신 간단한 예시 데이터를 반환한다.
    return f"티커: {stock_history_input.ticker}, 기간: {stock_history_input.period}의 가상 주식 데이터"

if __name__ == "__main__":
    # mcp.run(transport="streamable-http") # 이 코드는 (uv로 python 관리하고 있다면) uv run 명령어로 구동한다.
    # 위 코드를 적용하지 않는다면 fastmcp run 명령어로 구동하면 된다.
    pass

---

서버 구동 및 접속 방법

위 코드를 mcp_server.py 파일로 저장한 후, 터미널에서 아래와 같이 서버를 구동할 수 있다. fastmcp는 uvicorn을 기반으로 서버를 구동하며, 별도의 설정이 없다면 127.0.0.1 주소의 8000번 포트에서 실행된다.

1. 명령어 실행

# fastmcp 라이브러리를 사용해 서버를 구동한다.
fastmcp run mcp_server.py

명령어를 실행하면 Uvicorn running on http://127.0.0.1:8000와 같은 로그가 출력된다. 이 로그는 서버가 127.0.0.1에서 정상적으로 실행 중임을 보여준다.

2. MCP Inspector 설정

# MCP Inspector 구동
npx @modelcontextprotocol/inspector

MCP Inspector를 사용하여 서버에 접속할 때, URL 설정은 반드시 127.0.0.1로 명시해야 한다.

• 올바른 URL: http://127.0.0.1:8000/mcp
• 잘못된 URL: http://localhost:8000/mcp

MCP Inspector의 설정 화면에서 URL을 http://127.0.0.1:8000/mcp로 변경하고 연결하면, 서버와 클라이언트 간의 통신이 성공적으로 이루어지는 것을 확인할 수 있다.

이와 같이 localhost와 127.0.0.1의 미묘한 차이를 이해하는 것이 로컬 MCP 서버 개발 및 테스트 과정에서 발생하는 연결 문제를 해결하는 핵심이다.

---