OpenAI Docs MCP,
공식 점검 도구로 연결부터 설정 제거까지 통과

모델 가중치 외에도 컨텍스트의 KV 캐시, 실행 버퍼, 운영체제와 다른 앱에 메모리가 필요하다. 파일 크기를 총 RAM에서 빼는 계산만으로 실행 가능 여부를 정할 수 없다. CPU와 GPU가 통합 메모리를 사용하는 장치에서는 같은 메모리를 각각의 여유 공간으로 중복 계산하지 않아야 한다.

다음은 9월 24일 Ollama 공식 레지스트리에서 확인한 정확한 태그의 파일 크기다. 같은 계열도 태그와 양자화가 바뀌면 크기가 달라진다.

모델 태그	레지스트리 파일 크기	표시된 양자화
qwen3:4b	2.5GB	Q4_K_M
gemma3:4b	3.3GB	Q4_K_M
qwen3:8b	5.2GB	Q4_K_M
gpt-oss:20b	14GB	MXFP4
devstral-small-2:24b	15GB	Q4_K_M
qwen3-coder:30b	19GB	Q4_K_M

예를 들어 3.3GB 모델을 골라도 “RAM 4GB면 충분하다”는 결론은 나오지 않는다. 표는 다운로드 공간과 후보 크기를 파악하는 자료다. 장비 구매 기준이나 최저 메모리 보증으로 사용하지 않는다.

실제로 Qwen3 4B와 Gemma3 4B의 Q4_K_M을 Ollama 0.34.3에서 실행했다. 같은 공개용 한국어 회의록을 요약하게 하고, 긴 입력에는 새 결정이 없는 합성 부록을 붙였다. 모델마다 짧은 입력과 긴 입력을 각각 4회씩, 총 16회 측정했다. 기존 브라우저와 개발 서버는 켜져 있었다.

Chat API에 출력 상한 1024, temperature 0, seed 42를 지정했고 Qwen에는 think:false를 요청했다. 별도 1토큰 진단으로 실제 입력량을 먼저 확인했다. Qwen은 짧은/긴 입력이 909/2096토큰, Gemma는 767/1708토큰으로, 출력 상한을 더해도 각각의 설정 문맥 안에 들어왔다. 원문·조건·응답은 재현 자료 ZIP에 담았다.

모델·입력 / 설정 문맥	미로드 첫 요청	유지한 3회 중앙값	OS RSS 표본 최대	종료 상태
Qwen3 4B 짧음 / 4096	18.03초	15.28초	3380.6 MiB	4회 모두 출력 상한
Qwen3 4B 부록 포함 / 8192	20.68초	16.66초	3729.2 MiB	4회 모두 출력 상한
Gemma3 4B 짧음 / 4096	10.12초	6.27초	4338.1 MiB	4회 모두 stop
Gemma3 4B 부록 포함 / 8192	9.62초	5.87초	4942.8 MiB	4회 모두 stop

첫 요청은 모델을 메모리에서 내린 뒤 시작했으며 OS 디스크 캐시까지 비우지는 않았다. 유지한 반복에는 같은 프롬프트의 캐시가 재사용됐다. 입력 길이와 설정 문맥을 함께 바꿨으므로 시간 차이의 원인을 어느 하나로 단정할 수 없다.

Qwen은 think:false 요청에도 영문 검토 문장이 답변에 섞였고, 요약을 완결하지 못한 채 1024토큰에서 잘렸다. Gemma는 짧은/긴 입력에서 420/395토큰을 생성하고 종료했다. 출력량과 완결 상태가 다르므로 이 표를 같은 일을 끝낸 속도의 우열로 읽으면 안 된다. 원인도 런타임·템플릿·모델 중 하나로 확정하지 않았다. 종료된 요약의 정확성은 한국어 회의록 비교 결과에서 별도로 대조한다.

1GiB는 1,024MiB다. 여기서 48 GiB는 기기 전체 메모리, 2.5/3.3GB는 모델 파일 규모다. 실행 모델 API의 size_vram은 런타임 할당 보고치이고, 표의 RSS는 0.2초마다 읽은 서버와 자식 프로세스의 합계 중 해당 조건 4회의 최고 표본이다. Gemma의 짧은 입력에서 할당 보고치는 약 3552.9 MiB, RSS 최고 표본은 4338.1 MiB로 서로 달랐다.

RSS에는 공유 페이지가 중복될 수 있고 표본 사이의 최고점을 놓칠 수 있다. Metal을 포함한 전체 장치 사용량으로 단정하거나 할당 보고치와 더해서 총 RAM으로 계산하지 않는다. 이 한 장치의 결과로 필요한 최소 RAM을 보증할 수도 없다. 유료 API 호출은 0회였지만 전력·기기·저장 공간 비용을 측정한 것은 아니다.

Ollama 빠른 시작에 따라 앱을 설치하고 실행한 상태에서 터미널을 연다. 다음 명령은 모델이 없으면 다운로드하므로 먼저 저장 공간을 확인한다. 이 예제의 목적은 설치와 상태 확인이며, 모델 품질 비교가 아니다.

ollama run gemma3:4b

대화 화면에서 다음을 차례로 입력한다. 첫 줄은 이 대화의 컨텍스트를 지정하는 명령이다.

/set parameter num_ctx 4096
메모리와 저장 공간의 차이를 세 문장으로 설명해 줘.

모델이 떠 있는 동안 다른 터미널에서 상태를 읽는다.

ollama ps

공식 FAQ와 컨텍스트 안내를 기준으로 다음을 확인한다.

확인값	읽는 방법	다음 조치
NAME	요청한 태그가 실제 실행 중인지 확인	다른 모델이면 먼저 실행 대상을 맞춘다
CONTEXT	현재 할당된 컨텍스트 확인	설정한 4096과 다르면 적용 상태를 확인한다
PROCESSOR	100% GPU, 100% CPU 또는 혼합 비율 확인	GPU 실행을 기대했는데 CPU 비중이 높으면 모델 크기와 장치 지원을 점검한다
운영체제 메모리 지표	macOS 메모리 압력, Windows 작업 관리자 등의 변화 확인	스왑과 지연이 커지면 컨텍스트나 모델 크기를 줄인다

ollama ps만으로 전체 시스템의 최고 RAM 사용량을 측정했다고 할 수는 없다. 같은 입력을 반복하면서 모델 태그, 컨텍스트, 다른 앱의 실행 상태와 운영체제 지표를 함께 기록해야 한다. CPU로 일부 넘어간다는 사실만으로 오류라고 단정할 수도 없다. 작업 지연이 허용 범위인지 함께 판단한다.

짧은 문답이 동작하면 실제 업무에 필요한 길이로 컨텍스트를 올려 다시 확인한다. Ollama 문서는 에이전트·코딩 작업에 64K 이상을 권하지만, 모든 장비가 그 길이를 여유 있게 처리한다는 뜻은 아니다. 처음부터 최대 컨텍스트를 할당하지 않는다. 앱으로 서버가 이미 실행 중이라면 별도 ollama serve를 중복 실행하기보다 현재 서버에 적용되는 설정을 공식 문서에서 확인한다.

모델이 목록에 없거나 로딩에 실패하면 문제 해결 문서의 서버 로그를 본다. macOS는 ~/.ollama/logs/server.log, Linux 서비스는 journalctl -u ollama가 출발점이다.

실행할 서버는 OpenAI의 Docs MCP이며 주소는 https://developers.openai.com/mcp다. 공식 안내상 문서 검색과 본문 읽기용이고, 사용자를 대신해 OpenAI API를 호출하지 않는다. 이 확인에서는 API 키나 계정 로그인이 필요하지 않았다.

클라이언트는 MCP 프로젝트가 제공하는 Inspector CLI다. LLM 없이도 도구 목록과 호출 결과를 확인할 수 있어 모델의 응답과 연결 문제를 분리하기 좋다. 이 절차는 인터넷의 문서 서버에 요청을 보낸다. Ollama를 사용한다는 이유로 MCP까지 오프라인이 되는 것은 아니다.

아래는 macOS·Linux 또는 WSL의 셸 예제다. Node.js 22.19.0 이상을 준비하고, 기존 설정과 구분되는 새 폴더에서 실행한다. Inspector는 확인에 사용한 2.8.0으로 고정한다.

mkdir mcp-docs-check
cd mcp-docs-check
npm init -y
npm install --ignore-scripts --save-exact @modelcontextprotocol/inspector@2.8.0

cat > client.json <<'JSON'
{}
JSON

cat > mcp.json <<'JSON'
{
  "mcpServers": {
    "openaiDocs": {
      "type": "http",
      "url": "https://developers.openai.com/mcp"
    }
  }
}
JSON

docs_mcp() {
  MCP_STORAGE_DIR="$PWD/storage" ./node_modules/.bin/mcp-inspector --cli \
    --client-config ./client.json --config ./mcp.json \
    --stored-auth-only --format json "$@"
}

--client-config는 이 폴더의 클라이언트 설정을, --config는 이 폴더의 서버 목록을 읽도록 지정한다. MCP_STORAGE_DIR도 같은 폴더에 둔다. --stored-auth-only는 새 로그인 창을 열지 않도록 한다. 인증이 필요한 다른 서버로 주소를 바꾸면 같은 결과가 나오지 않을 수 있다. 옵션의 기준은 Inspector 공식 CLI 문서다.

1. 연결과 도구 목록을 각각 확인한다

docs_mcp --server openaiDocs --method initialize
docs_mcp --server openaiDocs --method tools/list

실제 초기화 응답의 result.serverInfo는 다음과 같았다.

{"name":"openai-docs-mcp","version":"1.0.0"}

목록에서는 search_openai_docs, list_openai_docs, fetch_openai_doc, list_api_endpoints, get_openapi_spec 다섯 도구를 확인했다. 당시 다섯 도구 모두 readOnlyHint: true, destructiveHint: false를 반환했다. 이 표시는 서버가 제공하는 설명이므로 다른 서버를 검토할 때는 배포 주체와 실제 기능도 함께 확인한다.

2. 검색한 뒤 해당 문서 본문을 읽는다

docs_mcp --server openaiDocs --method tools/call \
  --tool-name search_openai_docs \
  --tool-args-json '{"query":"Docs MCP read-only","limit":3}'

docs_mcp --server openaiDocs --method tools/call \
  --tool-name fetch_openai_doc \
  --tool-args-json '{"url":"https://developers.openai.com/learn/docs-mcp"}'

검색 응답은 result.content의 텍스트 안에 검색 결과 JSON을 담는다. 확인 당시 세 결과 가운데 Docs MCP의 what-it-provides 절이 포함됐다. 본문 조회는 Docs MCP 문서와 위 서버 주소를 반환했다. 검색 결과의 순서와 개수만 보지 말고, 원하는 문서 URL과 본문이 실제로 들어 있는지 확인한다. 서버 문서와 검색 인덱스가 바뀌면 결과는 달라질 수 있다.

연결만 성공하고 tools/list가 실패하면 도구 조회 단계의 오류다. 목록은 보이는데 호출이 실패하면 도구 이름과 필수 인자를 확인한다. HTTP 연결 실패, 인증 오류, 도구 실행 오류를 같은 “MCP 오류”로 묶지 않아야 원인을 좁힐 수 있다.

3. 이 폴더의 연결 설정을 제거하고 다시 읽는다

호출이 끝나면 지금 만든 mcp.json만 빈 서버 목록으로 바꾼다.

cat > mcp.json <<'JSON'
{"mcpServers":{}}
JSON

docs_mcp --method servers/list

실제 결과는 {"result":{"servers":[]}}였다. 이 확인은 해당 파일에서 서버 항목이 제거됐다는 뜻이다. 다른 앱의 MCP 설정이나 원격 계정을 지우는 작업은 아니다. 이 예제에서는 로그인과 토큰 발급을 하지 않아 해제할 OAuth 연결도 없었다.

실행 명령·버전·응답 확인 기록 ZIP에는 재현용 설정, 고정 버전 의존성 파일, 실행 스크립트와 결과 발췌가 들어 있다. 개인 경로·키·설치 패키지 폴더와 외부 문서 전문은 제외했다. MCP 연결 확인 결과이며, Ollama 추론이나 코딩 성능을 검증한 기록은 아니다.

Inspector 확인은 Codex의 로그인·승인 설정까지 검증한 것이 아니다. 실제 Codex에서 이 문서 서버를 쓰려면 공식 Docs MCP 안내의 명령을 적용한다. 다음은 공식 문서와 설치된 CLI 도움말로 확인한 예시이며, 이번 재현에서는 기존 Codex 설정을 바꾸지 않았다.

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
codex mcp list

Codex 대화형 세션의 /mcp에서 연결 상태를 확인하고, “OpenAI Docs MCP로 Docs MCP의 읽기 전용 범위를 검색하고 해당 문서를 읽어 줘”처럼 요청한다. 답변 문구뿐 아니라 도구 호출 표시에서 검색·본문 조회 도구와 반환 URL을 확인한다. 제거할 때는 다음 명령을 사용하고 목록을 다시 읽는다.

codex mcp remove openaiDeveloperDocs
codex mcp list

Codex MCP 문서는 전역 ~/.codex/config.toml과 신뢰한 프로젝트의 .codex/config.toml을 구분한다. 다른 서버를 추가할 때는 enabled_tools로 필요한 도구를 제한하고, 서버별 default_tools_approval_mode 등 승인 설정이 전체 실행 정책과 어떻게 함께 적용되는지 확인한다. Claude Code·Cursor 등 다른 클라이언트의 설정 파일을 이 예제에 그대로 혼용하지 않는다.

Ollama 쪽에서 완료해야 할 일은 선택한 모델과 컨텍스트가 장비에서 감당되는지 기록하는 것이다. MCP 쪽에서는 도구 목록, 실제 반환 내용, 제거 후 설정을 확인한다. 이후 로컬 모델에 도구 호출을 맡기려면 그 모델과 클라이언트 조합이 도구 호출을 지원하는지 별도로 검증해야 한다.

2026년 9월 24일 보완: 제목의 RAM·VRAM 계산을 메모리 확인으로 좁히고, 태그별 파일 크기를 재확인했다. 장비 등급별 권장 표를 제거하고 Inspector에서 실제 재현한 읽기 전용 MCP 연결·검색·조회·제거 절차를 추가했다. 기존 보완에서 삭제한 미공개 비교 결과는 되살리지 않았다.

2026년 9월 24일 추가 측정: Qwen3 4B·Gemma3 4B를 실제 실행한 입력·출력·시간·OS RSS 기록을 보완했다. 앞선 MCP 재현과 별도 실험이며, Qwen의 출력 상한 종료도 포함했다. 미공개 코딩 비교나 장비별 최소 RAM 결과를 복원한 것은 아니다.