[AI] MCP 설정 가이드

1. MCP

MCP는 클라이언트(AI 도구)와 서버(도구 제공자) 사이를 잇는 JSON-RPC 기반 프로토콜이다.

[AI 도구] - [MCP Server] - [파일 / API / DB]

MCP 서버 하나가 "파일 읽기", "DB 조회", "GitHub PR 생성" 같은 툴(Tool)을 정의하면, AI가 작업 중에 그 툴을 자동으로 호출한다. 예를 들어 "이 프로젝트의 DB 스키마를 보고 마이그레이션 코드 짜줘"라고 하면 AI가 MCP를 통해 실제 DB에 접근한 뒤 코드를 작성한다.

방식	설명	주요 사용처
stdio	표준 입출력으로 통신. 로컬 프로세스를 직접 실행	npx, node, python 로컬 실행
HTTP (SSE / Streamable)	HTTP로 통신. 원격 서버 접속 가능	Docker 서버, 원격 배포

 

2. MCP 설정

MCP 서버는 각 도구의 설정 파일에 JSON 형식으로 등록한다.

도구별 전역 설정

전역 설정이란 특정 프로젝트가 아닌 내 PC 전체에 적용되는 설정이다. 특정 프로젝트에만 적용하고 싶다면 프로젝트 루트에 .mcp.json을 만들면 된다.

도구	전역 설정 파일 경로
Claude Code	~/.claude.json
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Copilot	OS 마다 다르고 servers 값으로 설정 필요

Windows에서 ~는 %HOMEPATH%(C:\Users\yourname)에 해당한다.

{
  "mcpServers": {
    "서버이름": {
      "command": "실행명령어",
      "args": ["인자1", "인자2"],
      "env": {
        "API_KEY": "your-key"
      }
    },
    "sse-서버이름": {
      "url": "http://localhost:3000/sse"
    }
  }
}

 

3. npx : 공식 서버를 즉시 붙이는 가장 빠른 방법

npx는 npm에 올라온 패키지를 설치 없이 즉시 실행해 주는 Node.js 도구이다.

공식 MCP 서버들이 대부분 npm에 배포되어 있어 가장 간편하게 시작할 수 있다.

# Node.js 18+ 설치 확인 (없으면 https://nodejs.org)
node -v

사용하려는 서버를 찾은 뒤, 해당 서버의 공식 문서에서 제공하는 설정 예시를 복사해서 설정 파일에 붙여넣으면 된다.

Windows 네이티브 환경(WSL 아님)에서는 npx를 직접 실행하면 "Connection closed" 오류가 발생할 수 있다.
cmd /c 래퍼로 감싸주면 해결된다.

{
  "mcpServers": {
    "my-server": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "패키지명", "추가인자..."]
    }
  }
}

 

4. Node.js : JS/TS로 커스텀 서버를 만드는 방법

사내 API 연동, 독자적인 비즈니스 로직과 같이 공식 서버에 없는 기능을 직접 만들 때 사용한다.

• 프로젝트 초기화 및 서버 코드

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "my-custom-server", version: "1.0.0" });

server.tool(
  "get_deployment_status",
  "서비스 배포 상태를 조회합니다",
  { service: z.string().describe("서비스 이름") },
  async ({ service }) => {
    const res = await fetch(`https://api.example.com/api/status/${service}`);
    const data = await res.json();
    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
  }
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}
main().catch(console.error);

• 빌드 후 설정 파일에 등록

npx tsc

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/dist/index.js"],
      "env": { "DEPLOY_API_KEY": "your-api-key" }
    }
  }
}

경로는 반드시 절대 경로를 사용한다. 상대 경로는 AI 도구 실행 위치에 따라 오동작할 수 있다.

 

5. Python/uvx : AI, 데이터 도구를 연동하는 방법

uv는 pip보다 빠른 Python 패키지 관리자이고, uvx는 Python 패키지를 설치 없이 즉시 실행해 주는 npx의 Python 버전이다.

크롤링, 데이터 분석, AI 라이브러리 기반 MCP 서버에 유용하다.

# uv 설치 (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell (관리자 권한으로 실행)
# PowerShell: Windows에 내장된 명령줄 셸로, macOS Terminal(zsh/bash)에 해당한다.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

• 설정 파일에 등록

{
  "mcpServers": {
    "playwright": {
      "command": "uvx",
      "args": ["mcp-playwright"]
    },
    "data-analysis": {
      "command": "python",
      "args": ["/absolute/path/server.py"]
    }
  }
}

• Python으로 직접 서버 작성

# server.py
from mcp.server.fastmcp import FastMCP
import pandas as pd

mcp = FastMCP("data-analysis-server")

@mcp.tool()
def analyze_csv(filepath: str) -> str:
    """CSV 파일을 읽어 기본 통계를 반환합니다"""
    df = pd.read_csv(filepath)
    return df.describe().to_string()

if __name__ == "__main__":
    mcp.run()

# uvx로 실행하는 경우: 별도 설치 불필요
# python server.py로 직접 실행하는 경우: 아래 패키지 설치 필요
pip install mcp pandas

 

6. HTTP 방식 (Docker, 원격 URL) : 원격으로 운영하는 방법

stdio 방식이 로컬 프로세스를 직접 실행하는 것이라면, HTTP 방식은 어딘가에 떠있는 서버에 연결하는 방식이다.

• Docker 이미지를 실행해서 MCP 서버로 사용하는 경우
• 이미 배포된 서버에 URL로 연결하는 경우

Docker로 MCP 서버 실행하기

Docker는 누군가 미리 만들어 배포한 프로그램(이미지)을 내 PC에서 그대로 실행할 수 있게 해주는 도구다. Docker 이미지는 Ubuntu, Debian, Alpine Linux 등 다양한 Linux 베이스를 사용한다. 누군가 Docker 이미지로 배포해둔 MCP 서버가 있다면 환경을 그대로 포장해서 어디서든 동일하게 실행할 수 있다.

[내 맥북]   →  [Docker 컨테이너 (Linux 내부)]
[팀원 PC]   →  [동일한 컨테이너] ← 항상 동일한 환경
[회사 서버] →  [동일한 컨테이너]

설치 후 설정 파일에 아래처럼 등록하면 된다. command로 Docker를 직접 실행하는 stdio 방식이다.

• run: 이미지를 실행
• -i: stdio로 통신 (AI 도구와 입출력 연결)
• --rm: 종료 시 컨테이너 자동 삭제
• -e MY_API_KEY: 환경변수를 컨테이너 안으로 전달
• 마지막 줄: 실행할 Docker 이미지 이름 (사용하는 MCP 서버에 따라 다름)

{
  "mcpServers": {
    "my-docker-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MY_API_KEY",
        "some-org/some-mcp-server:latest"
      ],
      "env": {
        "MY_API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

Windows에서 WSL을 거치는 경우, Docker 명령어를 WSL을 통해 실행하는 패턴도 자주 쓰인다.

{
  "mcpServers": {
    "my-docker-mcp": {
      "command": "C:\\Windows\\System32\\wsl.exe",
      "args": [
        "-d", "Ubuntu", "--", "bash", "-lc",
        "docker run -i --rm -e MY_API_KEY some-org/some-mcp-server:latest"
      ],
      "env": {
        "MY_API_KEY": "${MY_API_KEY}",
        "WSLENV": "MY_API_KEY/u"
      }
    }
  }
}

이미 있는 서버에 URL로 연결하기

Docker 없이 이미 배포된 외부 MCP 서버나 SaaS 형태의 서비스에 접속할 때는 command 없이 url만으로 등록할 수 있다.

인증이 필요하면 headers를 추가한다.

{
  "mcpServers": {
    "remote-server": {
      "url": "https://example.com/mcp/sse",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

 

7. 보안, 디버깅

API 키 노출 주의

.mcp.json을 git에 커밋할 때 API 키를 직접 쓰면 키가 그대로 올라간다. 반드시 환경변수로 분리해야 한다.

// 위험
"env": { "GITHUB_TOKEN": "your_github_token" }

// 안전
"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }

// 환경 변수 등록
# macOS/Linux (~/.zshrc 또는 ~/.bashrc)
export GITHUB_TOKEN="ghp_xxxx"
# Windows PowerShell
[System.Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_xxxx", "User")

팀과 .mcp.json을 공유하면서 키를 직접 써야 할 경우엔 .gitignore에 추가한다.

.mcp.json
.env

MCP Inspector 공식 디버깅 도구

서버가 AI 도구에서 인식이 안 될 때, Inspector로 서버 자체가 정상인지 먼저 확인한다. 브라우저에서 http://localhost:6274 접속 → Transport / Command / Arguments 입력 → Connect → 툴 목록 확인 및 직접 호출 테스트가 가능하다.

npx @modelcontextprotocol/inspector