Errors, Debugging, and Observability in MCP

Recall Module 14’s own closing promise — understanding exactly what a connected MCP system is doing matters for more than convenience; it’s directly how you’d actually catch a real, developing security issue before it becomes a genuine incident. This module builds the real, systematic discipline for finding out.

The real, systematic debugging funnel

When something breaks, the honest question isn’t “why is MCP broken” — it’s “which specific, real layer actually failed.”

flowchart TD
    A[Connection problem?] --> B[Initialization?]
    B --> C[Capability negotiation?]
    C --> D[Tool discovery?]
    D --> E[Tool schema?]
    E --> F[Invocation?]
    F --> G[Downstream service?]
    G --> H[Result formatting?]

Recall Module 4’s own real lifecycle — every one of these stages maps directly onto something this course has already built. Working through them in order, rather than guessing, is genuinely the fastest real path to a fix.

Diagnosing a real connection failure

Recall Module 8’s own real transport distinction — a connection failure often means something genuinely specific about how the Client is trying to reach the Server.

We’ll build a small, real, deliberate check, distinguishing a connection failure from every later, real stage.

from fastmcp import Client
from fastmcp.exceptions import ClientError

async def diagnose_connection(server_path: str):
    try:
        async with Client(server_path) as client:
            print("Connection succeeded.")
    except ClientError as e:
        print(f"Connection-level failure: {e}")  # recall Module 8 — check the real transport first

Diagnosing a real capability mismatch

Recall Module 4’s own real negotiation — a genuine, common failure is calling something a Server never actually reported supporting.

async def diagnose_capabilities(client) -> None:
    tools = await client.list_tools()
    tool_names = {t.name for t in tools}
    if "get_order_status" not in tool_names:
        print("This server genuinely doesn't expose get_order_status — check what it actually reported.")

Recall Module 4’s own real, deliberate absence of a "prompts" key as an honest example — a genuine mismatch here almost always traces back to negotiation, not a bug in your own, calling code.

Diagnosing a real schema or argument failure

Recall Module 5’s own real Pydantic validation — this failure genuinely happens before your actual tool logic ever runs.

from fastmcp.exceptions import ToolError

async def diagnose_tool_call(client, tool_name: str, arguments: dict):
    try:
        result = await client.call_tool(tool_name, arguments)
        return result.data
    except ToolError as e:
        print(f"Tool-level failure: {e}")  # recall Module 5 — likely a real, invalid argument

Diagnosing a real downstream failure

Recall Module 5’s own real weather and order-status tools — a genuine failure here means the MCP layer itself worked correctly, but the actual, external service it called did not.

import logging

logger = logging.getLogger("mcp-diagnostics")

async def call_with_downstream_logging(client, tool_name: str, arguments: dict):
    logger.info(f"Calling {tool_name} with {arguments}")  # a real, genuine record of the attempt
    result = await client.call_tool(tool_name, arguments)
    if isinstance(result.data, dict) and "error" in result.data:
        logger.warning(f"Downstream error from {tool_name}: {result.data['error']}")  # recall Module 5's own honest errors
    return result.data

What genuinely deserves logging, and what never should

It’s worth being precise here, since real observability and real security intersect directly. Genuinely worth logging: the real server connection and its outcome, real tool invocations and their arguments, real latency, real errors, and real result sizes. Genuinely worth never logging: real credentials, real API keys, or unredacted, sensitive real data passed as tool arguments — recall Module 14’s own real Supabase incident directly; a log file containing sensitive, real tokens is itself a genuine, real exposure risk, structurally similar to the incident that already happened for real.

Common mistakes worth avoiding

Assuming every failure is a “real MCP bug.” Recall this module’s own real funnel — the overwhelming majority of genuine failures trace back to one, specific, identifiable stage, often something you can fix directly, like an invalid argument or a missing negotiated capability.

Logging full, real tool arguments without checking what they might contain. Recall this module’s own direct warning — an argument might genuinely include sensitive, real data; always consider what a log line could expose before writing it.

Debugging by guessing rather than working through the real funnel in order. Recall this module’s own real, ordered sequence — connection, then initialization, then negotiation, then discovery, then schema, then invocation, then the downstream service. Skipping ahead risks missing the actual, real root cause.

What you should take away from this module

• A real, systematic debugging funnel — connection, initialization, negotiation, discovery, schema, invocation, downstream, formatting — gives you an actual, ordered path to a root cause.
• ClientError and ToolError genuinely distinguish connection-level failures from tool-level ones, worth catching separately.
• Real, structured logging should capture attempts, arguments, and errors — but never real credentials or unredacted sensitive data, recalling Module 14’s own real, documented incident directly.

Where this goes next

The next module covers Real-World MCP Applications — genuine, verified companies and platforms actually using MCP today, and precisely what capability, client role, and trade-off each real deployment represents.