[MCP] MCP Server는 어떻게 연결할까? - 설정 파일과 연결 방식

STUDY/AI

[MCP] MCP Server는 어떻게 연결할까? - 설정 파일과 연결 방식

devmel 2026. 8. 17. 13:25

MCP Server를 연결한다는 것

MCP Host가 어떤 MCP Server를 사용하려면 해당 Server와 어떻게 연결할지에 대한 정보가 필요함.

구분	필요한 정보
Server 식별	어떤 MCP Server를 사용할 것인지
실행 또는 접속	Server를 직접 실행할지, 특정 주소로 접속할지
실행 옵션	필요한 Argument가 있는지
환경 변수	API Key 등의 값이 필요한지
인증	원격 Server에 인증이 필요한지

왜 연결정보가 필요한가?

MCP Server라고 해서 모두 같은 위치에서 실행되는 것은 아니다.

어떤 Server는 사용자의 컴퓨터에서 직접 실행될 수 있고, 어떤 Server는 인터넷에 배포된 원격 Server일 수 있음

따라서 Host가 알아야 하는 정보다 달라짐

결과적으로, MCP Server을 연결한다는 것

=> MCP Host에 Server의 실행 또는 접속 정보를 등록하고, MCP Client가 해당 정보를 이용해 MCP Server와 통신할 수 있도록 만드는 것.

Local MCP와 Remote MCP

구분	Local MCP Server	Remote MCP Server
개념	사용자의 로컬 머신에서 실행되는 Server => Host가 Server를 실행해야 함	인터넷에 호스팅되어 여러 Client가 접근할 수 있는 Server => MCP Host가 Server 프로그램을 직접 실행할 필요가 없음
핵심	Host에게 이 MCP Server를 어떤 명령어로 실행해야 하는지 알려줌
Server 위치	사용자 PC 등 로컬 환경	외부 Server / Cloud
Server 실행	Host/Client가 직접 실행하는 형태가 일반적	이미 Server가 실행 중
대표 Transport	stdio => Client가 MCP Server를 subprocess로 실행함 Client → Server :stdin Server → Client :stdout 을 통해 메세지를 주고받음	Streamable HTTP
연결에 필요한 핵심 정보	command, args, 환경변수 등	Server URL, 인증 정보 등
접근 범위	해당 로컬 환경 중심	네트워크를 통해 여러 Client에서 접근 가능
대표 예	로컬 File System, 개발 도구	SaaS, 사내 API, Cloud Service

Local MCP Server 설정

주요 설정값

{
  "servers": {
    // 등록할 MCP Server의 이름
    "<server-name>": {

      // Local Server를 표준 입출력 방식으로 연결
      "type": "stdio",

      // MCP Server를 실행할 명령어
      // ex) node, python, npx, docker 등
      "command": "<command>",

      // command 실행 시 전달할 인자
      "args": [
        "<arg1>",
        "<arg2>"
      ],

      // MCP Server Process에 전달할 환경변수
      // API Key, Token, 실행 환경값 등이 필요한 경우 사용
      "env": {
        "<ENV_NAME>": "<value>"
      },

      // Server가 실행될 기준 디렉터리
      // 필요하지 않은 경우 생략 가능
      "cwd": "<working-directory>"
    }
  }
}

설정	역할	예
command (필수)	MCP Server를 실행할 명령어	node, python, npx, docker
args	실행 명령에 전달할 인자	server.js, -y, package 이름
env	Server 실행 시 전달할 환경변수	API Key, DB 정보
cwd	Server가 실행될 작업 디렉터리	프로젝트 경로
envFile	환경변수를 읽어올 파일	.env

NPM Package 형태라면?

실제 MCP Server은 NPM이나 다른 Package Manager를 통해 배포되는 경우도 있음.

ex) VS Code 공식문서의 Local Server 예시

{
  "servers": {
    "memory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

=> 실행되는 명령 : npx -y @modelcontextprotocol/server-memory

Remote MCP Server 설정

{
  "servers": {
    // Host에서 MCP Server를 구분하기 위한 이름
    "<server-name>": {

      // Remote Server와 HTTP 기반으로 연결
      "type": "http",

      // 접속할 MCP Server Endpoint
      "url": "https://example.com/mcp",

      // 인증 Header 등이 필요한 경우
      // 지원 방식과 필드명은 Host에 따라 다를 수 있음
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

설정	역할	예
Server 이름	Host에서 Server를 구분	github, my-api
type	사용할 연결 방식	http
url	Remote MCP Server의 Endpoint	https://example.com/mcp
인증 정보	인증이 필요한 Server에 사용	Token, OAuth 등

MCP 설정 파일

모두 MCP Protocol을 사용하지만 Server 등록 정보를 관리하는 방법은 다를 수 있음

API Key와 인증 정보는 어떻게 관리할까?

구분	인증 대상	대표적인 방식
MCP Client → MCP Server	Remote MCP Server 접근	OAuth / Access Token
MCP Server → 외부 서비스	GitHub, API, DB 등 접근	API Key, Token, DB Credential
Local MCP Server 실행	Server Process에 Credential 전달	환경변수, Secret Store 등

설정 파일에는 Secret 자체보다 참조값을 두는 편이 좋음

설정 파일
↓
환경변수 / Secret Store 참조
↓
실제 Credential

{
  "<server-name>": {
    "command": "<command>",

    "env": {
      // 실제 값이 아니라 외부 환경변수 등을 참조
      "API_TOKEN": "${ENV_API_TOKEN}"
    }
  }
}

Remote MCP Server 인증 - Authorization 사용 권장

Server가 사용자 데이터나 중요한 기능을 제공한다면 아무 Client나 접근하도록 둘 수 없다.

따라서 MCP Client → 인증/권한 확인 → Remote MCP Server

현재 MCP의 HTTP 기반 Authorization은 OAuth 2.1 기반 흐름을 사용

보호된 MCP Server가 Protected Resource Metadata를 통해 어떤 Authorization Server를 사용하는지 Client가 발견할 수 있도록 정의함. Client는 이후 적절한 Authorization Server에서 Token을 얻어 Server에 접에 접근함.

MCP 인증과 외부 API 인증은 서로 다르다

MCP Protocol의 Authorization은 Client가 MCP Server에 접근하는 권한에 대한 것.

MCP Server가 내부적으로 사용하는 Github, Slack, Database 등의 Credential 관리는 별도의 문제.

Credential은 어디에 두는 게 좋은가?

방식	추천 정도	용도
설정 파일에 직접 작성	낮음	테스트 외에는 피하는 편이 좋음
환경변수	높음	Local Server, API Key
.env / envFile	높음	Local 개발 환경
Host의 Secret Store	높음	사용자 Credential
OAuth	높음	Remote MCP 사용자 인증
Server-side Secret Manager	높음	운영 환경의 API/DB Credential

최소 권한도 중요하다

Least Privilege를 적용하는 편이 좋음.

필요한 기능 확인 → 필요한 Scope 확인 → 최소권한 Credential

MCP Server가 제대로 연결됐는지 어떻게 확인할까?

구분	설명
1. Sever가 실제로 실행되는지 확인	환경] - Local MCP Server 가장 먼저 실행 명령 자체가 정상인지 확인 : command 실행 가능? → 필요한 Runtime 설치됨? → 파일 경로가 맞음? → 필요한 환경변수 존재? ex) { command" : "node", "args" : ["server.js"] } => node server.js - Remote MCP Server Process를 직접 실행하는 대신 MCP Endpoint에 접속할 수 있어야 함 : URL이 정확한가? → Server가 실제로 실행 중인가? → Network에서 접근 가능한가? → 인증이 필요한가? → 현재 계정에 권한이 있는가?
2. Server가 제공하는 기능을 확인	Client가 Tool목록을 확인할 수 있으며, tools/list 요청으로 현재 사용할 수 있는 Tool을 조회한다. 현재 사양에서는 Server가 Tools Capaility를 제공한다면 tools/list 요청에 응답해야 함
3. 실제 기능을 한번 호출해봄	MCP Tool은 tools/call 요청을 통해 실행할 수 있다. 단순 성공 여부뿐만 아니라 - 입력 Schema가 맞는가? - 실제 외부 API가 호출되는가? - 결과 구조가 예상과 같은가? - Error가 적절하게 반환되는가?
4. 문제가 있다면 Log를 확인	연결에 실패했다면 어느 단계에서 실패했는지를 먼저 구분 - Local stdio Sever의 경우엔, 로그 처리에 주의 => 일반 Log를 stdout에 출력하면 MCP Protocol 메세지를 깨뜨릴 수 있음. MCP 사양에서는 stdout에는 유효한 MCP 메세지 외의 내용을 출력하면 안되며, 로그는 stderr에 작성할 수 있도록 정의.

MCP Inspector

MCP에서는 Server 테스트와 디버깅을 위한 공식 도구로 제공함.

Local/Remote MCP Server에 연결해서 Tool, Resource, Prompt 등을 직접 확인하고 호출할 수 있음.

실행방법

공식 Inspector는 Node.js 22.19.0 이상에서 npx로 바로 실행 가능

npx @modelcontextprotocol/inspector

확인방법

Local MCP Server 확인

Local Server 직접 지정 가능

npx @modelcontextprotocol/inspector node path/to/server.js

구조 : Inspector → node path/to/server.js 실행 → Local MCP Server → Tools / Resources / Prompts 확인

Remote MCP Server 확인

npx @modelcontextprotocol/inspector \
  --server-url https://example.com/mcp \
  --transport http

연결할 때 자주 발생하는 문제

증상	주요 원인	확인할 것
Server가 시작되지 않음	command 오류, Runtime 미설치	명령어 직접 실행
Server 파일을 찾지 못함	args 경로 오류, cwd 문제	절대/상대 경로
연결 직후 종료	Server 내부 예외, 환경변수 누락	stderr, Server Log
Tool 목록이 안 보임	Server 기능 등록 오류	tools/list, Capability
Tool 호출 실패	입력 Schema 오류, 내부 API 실패	arguments, Server Error
Local MCP 메시지 오류	stdout에 일반 Log 출력	Log를 stderr로 이동
Remote MCP 연결 실패	잘못된 URL, Network 문제	Endpoint 접근 여부
401 / 403	인증·권한 문제	Token, OAuth, Scope
설정은 맞는데 Host에서 안 보임	설정 파일 위치/Scope 오류	Host별 설정 위치
특정 PC에서만 실패	Runtime·환경변수·경로 차이	실행 환경 비교