목적별 가이드

하려는 일 가이드
CLI 설치·인증과 첫 파일 작업 Gemini CLI 첫 사용
CLI·API 비용과 현재 한도 확인 인증별 한도·요금
명령·인증·모델 요청에서 실패함 실행·로그인 오류
OpenCode에서 MCP를 연결함 OpenCode MCP 설정

서버와 전송 방식부터 고르기

MCP 서버는 CLI에 도구나 자료를 제공하는 프로그램입니다. 서버마다 필요한 실행 환경과 인증·접근 범위가 다릅니다.

연결 방식 먼저 확인할 것
stdio CLI가 실행할 로컬 명령·인자·파일 경로·런타임
원격 HTTP·SSE 서버의 공식 주소·지원 전송·인증·노출 도구

처음에는 무엇을 실행하는지 읽을 수 있는 작은 예제로 시작하면 연결 단계를 이해하기 쉽습니다. 이 글의 서버는 숫자 두 개를 더하는 도구 하나만 제공합니다. 서버 실행 뒤 제공하는 덧셈 도구는 파일이나 외부 API에 접근하지 않습니다. 의존성을 설치할 때는 npm 네트워크 접속이 필요합니다.

실제 GitHub·데이터베이스 서버를 연결한다면 그 서버의 공식 절차와 권한을 따로 확인해야 합니다. 특정 튜토리얼이 Docker를 쓴다고 모든 MCP 서버에 Docker가 필요한 것은 아닙니다.

새 폴더에 자체 예제 준비하기

Gemini CLI와 Node가 준비된 상태에서, 본인의 작업 위치에 새 폴더를 만듭니다. 같은 이름의 폴더가 있다면 다른 이름을 선택하세요.

New-Item -ItemType Directory -Path .\bmt-gemini-mcp
Set-Location .\bmt-gemini-mcp
npm.cmd init -y
npm.cmd install @modelcontextprotocol/sdk@1.23.0 zod@3.25.76 --ignore-scripts

예제는 확인한 Gemini CLI 0.65.0 코어의 SDK 의존성과 같은 1.23.0을 사용합니다. 이것을 모든 미래 CLI·MCP 버전의 조합으로 보장하지는 않습니다. 아래 코드를 math-server.mjs로 저장합니다.

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: 'bmt-math', version: '1.0.0' });
server.registerTool('add_numbers', {
  description: 'Add two numbers. No files or network are used.',
  inputSchema: {
    a: z.number().min(-1000000).max(1000000),
    b: z.number().min(-1000000).max(1000000)
  },
  outputSchema: { sum: z.number() },
  annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
}, async ({ a, b }) => {
  const result = { sum: a + b };
  return {
    content: [{ type: 'text', text: JSON.stringify(result) }],
    structuredContent: result
  };
});
await server.connect(new StdioServerTransport());

이는 자체 학습용 예제이며 읽기 전용 표시는 도구의 성격을 설명하는 힌트입니다. 임의의 외부 서버에 같은 표시가 있다고 실제 동작까지 보장되는 것은 아니므로, 서버의 출처와 코드·접근 권한을 함께 확인해야 합니다.

프로젝트 범위로 서버 등록하기

PowerShell에서 저장한 파일의 실제 경로를 확인합니다.

(Resolve-Path .\math-server.mjs).Path

아래 가상 경로를 본인의 경로로 바꿔 프로젝트 범위에 등록합니다.

gemini.cmd mcp add --scope project bmt-math node "C:/work/bmt-gemini-mcp/math-server.mjs"
gemini.cmd mcp list

공식 문서는 프로젝트의 .gemini/settings.json과 사용자의 ~/.gemini/settings.json을 구분합니다. 이 예제는 현재 시험 폴더의 프로젝트 범위를 사용합니다. 기존 설정이 있다면 아래 문서를 통째로 덮어쓰지 말고 mcpServers 안의 해당 서버 항목만 합쳐야 합니다.

{
  "mcpServers": {
    "bmt-math": {
      "command": "node",
      "args": ["C:/work/bmt-gemini-mcp/math-server.mjs"],
      "includeTools": ["add_numbers"],
      "trust": false
    }
  }
}

includeTools는 이 서버에서 사용할 도구를 좁히는 항목입니다. trust: false는 서버의 모든 도구 호출 승인을 건너뛰는 설정을 켜지 않는다는 뜻입니다. 다른 전역 정책·권한·도구 특성에 따라 실제 승인 동작은 달라질 수 있습니다.

파일 경로는 절대 경로를 쓰면 CLI를 어디서 시작했는지에 따른 혼동을 줄일 수 있습니다. Windows 경로를 JSON에 쓸 때는 위처럼 /를 쓰거나 역슬래시를 올바르게 이스케이프해야 합니다.

연결·도구 목록·호출을 나눠 확인하기

설정을 저장한 뒤 CLI를 시작하거나 다시 시작하고 다음을 확인합니다.

/mcp list
/mcp desc
확인 단계 이 예제의 확인 기준
설정 범위 현재 시험 폴더의 bmt-math 항목이 사용됨
서버 연결 서버가 연결 상태로 표시됨
도구 노출 add_numbers 설명과 입력 항목이 보임
호출 숫자 2와 3을 전달해 합계 5를 확인

CLI에 다음처럼 요청할 수 있습니다.

bmt-math 서버의 add_numbers 도구를 사용해서 a=2, b=3을 더해줘.
다른 도구를 쓰거나 파일을 수정하지 마.

승인 안내가 나오면 서버·도구·입력값을 확인합니다. 답변이 5라고 해서 반드시 MCP를 쓴 것은 아닙니다. 실제 도구 호출 표시와 입력·결과를 함께 봐야 합니다.

이 예제의 기준 결과는 {"sum":5}입니다. 자체 검수에서는 SDK 클라이언트로 서버 초기화·도구 목록·정수/소수 호출·잘못된 입력 거부를 확인했습니다. 이 값은 실제 Gemini 대화 출력이나 Gemini CLI의 연결 성공을 대신하는 증거는 아닙니다.

연결 실패를 단계별로 확인하기

증상 먼저 확인할 부분
서버 명령을 실행할 수 없음 node 경로·실제 파일명·파일의 절대 경로
모듈을 찾지 못함 예제 폴더의 의존성 설치·설치한 폴더와 서버 위치
설정이 적용되지 않음 사용자/프로젝트 범위·실행한 폴더·JSON 형식
연결은 됐지만 도구가 없음 서버의 도구 목록·includeTools·excludeTools
도구 이름은 보이나 호출 실패 실제 입력의 숫자/문자열 구분·서버 오류

stdio에서는 표준 출력이 프로토콜 통신에 사용됩니다. 서버 코드에 일반 console.log로 시작 메시지를 추가하지 마세요. 확인용 로그가 필요하면 표준 오류를 사용하되 비밀값을 남기지 않습니다.

원격 서버의 로그인·토큰·권한 문제는 이 로컬 덧셈 예제와 다릅니다. CLI 로그인이나 모델 요청 자체가 실패했다면 실행·인증 오류로 이동합니다.

사용 중지와 설정 제거 구분하기

CLI 안에서 서버 사용을 끄려면 다음 명령을 사용할 수 있습니다.

/mcp disable bmt-math

다시 쓰려면 /mcp enable bmt-math를 확인합니다. 프로젝트 설정에서 항목을 제거하려면 PowerShell에서 범위를 지정합니다.

gemini.cmd mcp remove --scope project bmt-math

서버 항목 제거와 예제 폴더·다른 프로젝트 파일 삭제는 별개입니다. 외부 서비스의 키나 OAuth를 사용한 서버라면 CLI 항목 제거와 서비스 쪽 권한 회수도 구분해야 합니다.

참고자료