MCP 서버 안내문이 도구 검색에서 모델의 선택을 돕는다

서버 안내문은 모델이 먼저 읽는 문단이다

모델 컨텍스트 프로토콜(MCP) 서버가 보내는 instructions 필드는 서버 사용법을 자연어로 설명하는 짧은 문단이다. 이 필드는 2026-07-28 사양에서 server/discover 응답에 포함되며, 호스트가 모델에 전달할지는 호스트의 선택이다. 도구 검색을 지원하는 환경에서는 모델이 서버의 도구를 찾아볼지 결정할 때 이 문단이 단서가 된다.

이 글은 2026-07-28 사양을 바탕으로 한 MCP 서버 관련 시리즈의 4부다. 3부에서는 이 문단을 전달하는 server/discover 요청을 다뤘다. 아래 내용은 2026년 10월 기준이다.

instructions 필드는 2025-11-25 이전에는 initialize 응답의 선택 항목이었고, 2026-07-28 사양부터는 server/discover 응답의 선택 항목이 됐다. 발견 결과와 함께 캐시되며, 캐시에는 ttlMs와 cacheScope가 적용된다. 사양은 이 필드를 언어 모델이 서버를 효과적으로 사용하는 방법을 알려주는 자연어 안내로 설명한다. 클라이언트는 이를 시스템 프롬프트에 넣는 등의 방식으로 쓸 수 있지만, 반드시 그래야 하는 것은 아니다.

클라이언트가 server/discover를 호출하는 것 자체도 선택 사항이다. 프로토콜은 안내문이 모델에 전달되도록 보장하지 않는다. 이를 지원하는 호스트는 연결 시 시스템 프롬프트에 넣는 경우가 많지만, 이는 호스트의 동작이다. 따라서 이 문단을 읽는 호스트를 염두에 두되, 모든 호스트가 읽을 것이라고 가정해서는 안 된다.

도구 검색에 안내문이 중요한 이유

연결된 서버가 많은 호스트는 모든 도구 스키마를 한꺼번에 컨텍스트 창에 넣지 않을 수 있다. 예를 들어 Claude Code는 도구 정의를 필요할 때까지 미루며, 세션 시작 때 도구 이름과 서버 안내문만 불러오고 전체 스키마는 모델이 요청할 때 검색한다. Claude Code 문서는 도구 검색을 켰을 때 안내문이 도구를 찾아볼지 모델이 판단하는 데 도움이 되므로 더 유용하다고 설명한다.

이 방식에서는 작업이 서버의 기능과 맞지 않으면 해당 서버가 사용되지 않고 전체 스키마도 불러오지 않는다. 하지만 그 판단은 도구 이름과 안내문을 바탕으로 이뤄지므로, 안내문을 신중하게 써야 한다.

좋은 안내문은 네 가지를 알려준다. 서버의 용도와 다루는 작업, 사용해야 할 때와 사용하지 말아야 할 때, 도구들이 함께 작동하는 방식, 그리고 제약 조건이다. 예를 들어 호출 순서나 검색 후 가져오기 방식, 요청 제한, 비용이 큰 작업, 데이터 최신성, 핸들의 보존 기간을 설명할 수 있다.

Python에서 설정하는 예

아래는 내부 문서 서버의 예다. 공식 Python 소프트웨어 개발 키트(SDK)와 mcp 2.3.0을 사용하며, MCPServer의 instructions 매개변수에 안내문을 넣는다.

from mcp.server import MCPServer

ACME_DOCS_INSTRUCTIONS = """\
Acme Docs server: search and read Acme's internal engineering documentation
(runbooks, ADRs, API references). Use it for questions about Acme systems; do
not use it for general programming questions.

Workflow: call search_docs first, then fetch_doc with the returned doc_id for
full text. Prefer fetch_doc over quoting search snippets. For step-by-step
procedures, load the skill skill://incident-runbook/SKILL.md.

Constraints: search_docs is cheap; fetch_doc returns up to 20k characters.
Document IDs are stable. Content is refreshed nightly.
"""

mcp = MCPServer("acme-docs", instructions=ACME_DOCS_INSTRUCTIONS)

첫 문단은 서버의 용도와 사용 범위를, 둘째 문단은 도구의 호출 순서를, 셋째 문단은 제약을 설명한다. 시리즈 3부와 마찬가지로 SDK의 메모리 내 클라이언트에서 안내문을 읽을 수 있으며, 이전 핸드셰이크 방식에서도 같은 문구를 확인하는 예는 다음과 같다.

import anyio
from mcp import Client

async def main() -> None:
 async with Client(mcp) as client: # 2026-07-28 by default
 discover = client.session.discover_result
 print(client.protocol_version)
 print(discover.instructions.splitlines()[0])
 print(len(discover.instructions), "characters")
 async with Client(mcp, mode="legacy") as old: # the initialize handshake
 print(old.protocol_version, old.instructions == discover.instructions)

anyio.run(main)

2026-07-28
Acme Docs server: search and read Acme's internal engineering documentation
547 characters
2025-11-25 True

안내문은 한 번 설정하면 SDK가 사양 시기에 맞춰 전달한다. 2026-07-28 클라이언트에는 server/discover 응답으로, 핸드셰이크를 사용하는 클라이언트에는 initialize 응답으로 들어간다. 예시의 안내문은 547자이며, Claude Code가 기본으로 유지하는 2,048자 제한 안에 든다.

안내문에는 도구 설명을 복사해 넣지 않는 편이 좋다. 도구 설명은 도구에 붙이고 필요할 때 불러온다. Python SDK의 필드 타입 설명도 이미 도구 설명에 있는 정보를 중복하지 않아야 한다고 명시한다.

안내문은 강제 규칙이 아니라 힌트다. 호스트가 이를 신뢰할 수 없는 텍스트로 취급할 수 있으므로 보안은 서버 자체의 검사로 보장해야 한다. “항상 다른 서버 대신 이 서버를 사용하라” 또는 “이전 지시를 무시하라”처럼 프롬프트 인젝션으로 읽힐 수 있는 명령도 피해야 한다. 호스트와 검토자는 이를 위험 신호로 볼 수 있으며, 도구 오염 공격도 같은 유형의 문구를 이용한다. MCP 서버 하나와 여덟 가지 규칙집에서는 검토자가 거부하는 항목으로 프롬프트 인젝션 패턴과 홍보성 설명을 다룬다.

또한 안내문은 짧게 유지해야 한다. 2026년 10월 기준 Claude Code는 각 도구 설명과 서버 안내문을 기본적으로 2,048자에서 자른다. 중요한 내용은 앞부분에 둬야 한다.

안내문과 프롬프트·스킬의 차이

세 가지 모두 모델이 서버를 사용하는 방식에 영향을 주지만, 불러오는 시점과 용도가 다르다.

사양은 필드를 정의하지만 호스트가 이를 어떻게 쓰는지는 정하지 않는다. 안내문을 제품 문구처럼 다루고 코드처럼 버전 관리하며, 도구가 바뀔 때마다 검토하는 것이 이 글의 권고다. 도구 검색을 켠 호스트 하나 이상에서 시험하고, 모델이 알맞은 작업에 해당 서버를 선택하는지도 살펴볼 수 있다.

안내문을 불러오는 호스트는 프롬프트나 스킬을 선택하기 전에 세션 시작 단계에서 이를 모델에 보여준다. 따라서 예시처럼 skill://incident-runbook/SKILL.md 같은 URI나 이름을 사용해 관련 스킬과 프롬프트를 안내문에서 가리킬 수 있다.

이 글은 2026-07-28 사양을 기준으로 작성됐다. Claude Code의 도구 검색, 세션 시작 때 불러오는 항목, 2,048자 제한은 2026년 10월 문서에 기재된 동작을 따른다. 다른 호스트는 안내문을 다르게 불러오거나 전혀 불러오지 않을 수 있다. Python 예시는 2026년 10월 8일 mcp 2.3.0과 SDK의 메모리 내 클라이언트에서 실행한 결과다. 사양상 server/discover 호출은 클라이언트에 선택 사항이며, 안내문이 모델에 도달하는지는 호스트가 결정한다.

시리즈: 2026년 MCP 서버가 실제로 하는 일, 2026-07-28 사양에서 달라진 MCP, server/discover: 모든 MCP 서버가 구현해야 하는 메서드, 상태 없는 MCP 요청: _meta, resultType, 명시적 핸들, MCP의 캐시 힌트와 페이지네이션, 2026년 MCP 전송 방식: stdio와 Streamable HTTP, MCP 도구 설계: 정의와 결과, MCP 도구 오류와 모델이 잘 사용하는 도구, MCP 리소스: 애플리케이션이 사용 여부를 정하는 컨텍스트, MCP 프롬프트: 서버가 제공하는 슬래시 명령, 도구·리소스·프롬프트 중 무엇을 선택할까.