MCP Academy · 강의

프로토콜 오류와 도구 실패

전송 오류와 비즈니스 로직 오류를 구분합니다.

프로토콜 오류와 도구 실패은(는) CoddyKit의 무료 MCP Academy 강의입니다. 이것은 4개 중 2번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 MCP Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. MCP Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

이 강의의 일부는 아직 번역되지 않았으며 영어로 표시됩니다.

Two Very Different Failures

MCP has two kinds of failure: a protocol error in the wire itself, and a tool failure inside your business logic. They are handled differently.

Protocol Errors Live in JSON-RPC

A protocol error means the message could not be processed at all, like an unknown method or malformed params. It rides in the JSON-RPC error field.

{"jsonrpc": "2.0", "id": 7,
 "error": {"code": -32601,
           "message": "Method not found"}}

Tool Failures Live in the Result

A tool failure means the call reached your function but the work went wrong. It returns a normal result marked with isError true.

Why the Split Matters

The model should see and react to tool failures, but protocol errors usually signal a bug the client must handle, not something the AI can retry.

Standard JSON-RPC Codes

Protocol codes are negative and standardized: -32601 is method not found, -32602 is invalid params, -32700 is a parse error.

Tool Failures Reach the Model

Because a tool failure is just a result, the model reads it as context and can decide to retry, adjust input, or explain it. 🔁

Raising Inside a Tool

When you raise an exception in a tool, FastMCP turns it into a tool failure result, not a protocol error. Your server keeps running.

@mcp.tool()
def fetch(url: str) -> str:
    if not url.startswith("http"):
        raise ValueError("url must be http")

Unknown Tool Is Protocol-Level

If a client asks for a tool that does not exist, that is a protocol error. The request never reaches any function of yours.

Bad Arguments Can Be Either

Schema-level type mismatches surface as a protocol invalid-params error, while a valid type with a bad value is best a tool failure.

Match Failure to Audience

Ask who should react. If the model can fix it, make it a tool failure. If only the developer can, a protocol error is right.

Keep Transport Healthy

Never let business problems leak out as protocol errors. Doing so confuses clients and can tear down a session that should keep going.

Quick Check

Where does a failure inside your tool function get reported?

Recap

Protocol errors mean the message itself failed; tool failures mean your logic failed. Route each to who can act on it and keep transport healthy. ✅

자주 묻는 질문

“프로토콜 오류와 도구 실패” 강의는 무료인가요?

네 — “프로토콜 오류와 도구 실패” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 MCP Academy 강의 전체를 잠금 해제할 수 있습니다. MCP Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

“프로토콜 오류와 도구 실패”에서 뭘 배우나요?

전송 오류와 비즈니스 로직 오류를 구분합니다. 브라우저에서 직접 실행하는 실습 코드로 MCP Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

MCP Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 MCP Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 2번째 강의입니다.

“프로토콜 오류와 도구 실패” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 MCP Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 MCP Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← MCP Academy(으)로 돌아가기