Test before you trust it.

Five methods. One sequence.

Don't start with Claude Desktop. Start with MCP Inspector, which removes the LLM from the loop entirely. Work through the stack in order — each layer catches a different class of bug.

See the raw JSON-RPC.

MCP Inspector is the official visual testing tool — maintained by Anthropic at github.com/modelcontextprotocol/inspector. No permanent install required. Two ports: 6274 for the browser UI, 6277 for the local proxy.

Connect to a local stdio server

Pass your server launch command directly to the Inspector. It launches the server as a child process and connects via stdio.

npx @modelcontextprotocol/inspector uv run server.py

# With environment variables injected
npx @modelcontextprotocol/inspector \
  -e DATABASE_URL=postgresql://localhost/mydb \
  -e API_KEY=sk-test-placeholder \
  uv run server.py

npx @modelcontextprotocol/inspector python server.py

The browser opens automatically at http://localhost:6274 with a session token pre-filled in the URL. Go to the Tools tab and confirm your tools appear with their names, descriptions, and input schemas.

What a passing result looks like

• The Tools tab populates with your registered tools, each showing its schema and description
• Clicking a tool, filling its inputs, and hitting Run Tool returns a JSON result in the right panel
• The Notifications pane shows server logs in real time
• The Ping tab shows a successful round-trip response

What a failing result looks like

Test the deployed server.

Once your server is on Vercel, point Inspector at the live URL. No local server running. No guessing whether the deployment is healthy.

npx @modelcontextprotocol/inspector https://your-project.vercel.app/mcp

npx @modelcontextprotocol/inspector https://your-project.vercel.app/mcp \
  --header "X-API-Key: your-key-here"

# List tools from the remote server
npx @modelcontextprotocol/inspector \
  --cli https://your-project.vercel.app/mcp \
  --transport http \
  --method tools/list

# Call a specific tool on the remote server
npx @modelcontextprotocol/inspector \
  --cli https://your-project.vercel.app/mcp \
  --transport http \
  --method tools/call \
  --tool-name search_products \
  --tool-arg query=laptop

http://localhost:6274/?transport=streamable-http&serverUrl=https://your-project.vercel.app/mcp

The config file, both options.

Claude Desktop reads claude_desktop_config.json only at startup. After any edit, fully quit — not just close the window — and relaunch. Success is confirmed by the MCP slider icon appearing in the chat input area.

Config file locations

If the file doesn't exist, enable it via Settings → Developer → Edit Config in the Claude Desktop app.

Option A: Local stdio — direct Python subprocess

Use when your FastMCP server runs locally. Claude Desktop spawns the process and communicates over stdio. Always use absolute paths — relative paths fail because Claude Desktop does not run from your project directory.

{
  "mcpServers": {
    "my-shop-server": {
      "command": "uv",
      "args": [
        "run",
        "--project", "/absolute/path/to/your/project",
        "python",
        "server.py"
      ],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host/db",
        "API_KEY": "sk-your-actual-key-here",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Option B: Remote HTTP via mcp-remote

For a Vercel-deployed server. mcp-remote runs as a local stdio subprocess that Claude Desktop spawns, then proxies to your remote HTTP endpoint. The package name is mcp-remote on npm — there is no @anthropic-ai/mcp-remote.

{
  "mcpServers": {
    "my-shop-server-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://your-project.vercel.app/mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "my-shop-server-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://your-project.vercel.app/mcp",
        "--header",
        "X-API-Key:${API_KEY}"
      ],
      "env": {
        "API_KEY": "your-secret-key"
      }
    }
  }
}

Checking Claude Desktop MCP logs

If tools don't appear, check the logs that Claude Desktop writes for every MCP subprocess:

tail -n 50 -f ~/Library/Logs/Claude/mcp.log
tail -n 50 -f ~/Library/Logs/Claude/mcp-server-my-shop-server.log

Get-Content "$env:APPDATA\Claude\logs\mcp.log" -Wait -Tail 50

These logs show stdout/stderr of every MCP subprocess Claude Desktop spawned, including Python tracebacks, missing module errors, and mcp-remote OAuth output.

Deterministic assertions, no LLM guessing.

The Python MCP SDK's ClientSession lets you call tools programmatically and assert on the response shape. This catches serialization bugs that the Inspector UI masks because it shows raw JSON.

pip install "mcp[cli]"
# or with uv:
uv add "mcp[cli]"

"""
Test script for your FastMCP server.

Usage:
  # Against a local server:
  python test_server.py

  # Against your deployed Vercel server:
  MCP_SERVER_URL=https://your-project.vercel.app/mcp python test_server.py
"""

import asyncio
import os
import sys
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from mcp.client.streamable_http import streamable_http_client
from mcp import types

SERVER_SCRIPT = "/absolute/path/to/your/server.py"
SERVER_URL = os.environ.get("MCP_SERVER_URL")
API_KEY = os.environ.get("API_KEY", "")


async def test_server():
    if SERVER_URL:
        # Test against deployed server
        print(f"Testing remote server: {SERVER_URL}")
        headers = {"X-API-Key": API_KEY} if API_KEY else {}
        async with streamable_http_client(SERVER_URL, headers=headers) as (read, write, _):
            async with ClientSession(read, write) as session:
                await session.initialize()
                await run_tests(session)
    else:
        # Test against local stdio server
        print(f"Testing local server: {SERVER_SCRIPT}")
        server_params = StdioServerParameters(
            command="python",
            args=[SERVER_SCRIPT],
            env={"PYTHONUNBUFFERED": "1"},
        )
        async with stdio_client(server_params) as (read, write):
            async with ClientSession(read, write) as session:
                await session.initialize()
                await run_tests(session)


async def run_tests(session: ClientSession):
    # 1. Verify expected tools are registered
    tools_response = await session.list_tools()
    tool_names = [t.name for t in tools_response.tools]
    assert "search_products" in tool_names, \
        f"search_products not found. Available: {tool_names}"
    assert "initiate_checkout" in tool_names, \
        f"initiate_checkout not found. Available: {tool_names}"
    print(f"✓ Tools registered: {tool_names}")

    # 2. Call search_products and assert shape
    search_result = await session.call_tool(
        "search_products",
        arguments={"query": "widget", "limit": 5},
    )
    assert len(search_result.content) > 0, "search_products returned no content"
    result_text = search_result.content[0]
    assert isinstance(result_text, types.TextContent), \
        f"Expected TextContent, got {type(result_text)}"
    print(f"✓ search_products returned content")

    # 3. Call initiate_checkout
    checkout_result = await session.call_tool(
        "initiate_checkout",
        arguments={"sku": "WIDGET-001", "quantity": 1},
    )
    assert len(checkout_result.content) > 0, "initiate_checkout returned no content"
    print(f"✓ initiate_checkout returned content")

    print("\nAll assertions passed.")


if __name__ == "__main__":
    asyncio.run(test_server())

python test_server.py

MCP_SERVER_URL=https://your-project.vercel.app/mcp \
API_KEY=your-secret-key \
python test_server.py

Production errors, decoded.

Every POST to /mcp generates a log entry. The Vercel Logs tab shows status code, response time, and the full stderr output from your Python function — including tracebacks.

Dashboard navigation

1. Open your project in the Vercel dashboard
2. Click Logs in the left sidebar (under the project name)
3. Filter by Status Code → 5xx to isolate all errors immediately
4. Click any log row to open the detail panel: function metadata, log messages, and event timeline
5. Toggle Live mode to stream logs in real time during manual testing

Log retention by plan

CLI tailing

vercel logs --follow

# Filter by error status only
vercel logs --status-code 500 --follow

# JSON output for piping to jq
vercel logs --json --status-code 5xx | \
  python3 -c "import sys,json; [print(json.loads(l).get('message','')) for l in sys.stdin]"

Three log patterns you will see

Successful invocation

[INFO]  POST /mcp  200  142ms
[INFO]  Tool called: search_products {"query":"laptop","limit":10}
[INFO]  Tool returned 8 results

Status 200, your print() output appears as INFO lines, response time in the tens to hundreds of milliseconds after warmup.

Cold-start crash (500, no app logs)

[ERROR] POST /mcp  500  3241ms
[ERROR] ModuleNotFoundError: No module named 'pydantic_settings'
Traceback (most recent call last):
  File "/var/task/server.py", line 3, in <module>
    from pydantic_settings import BaseSettings

Key signals: high response time (2–5 seconds), error fires before any of your handler code runs (no tool-name log lines), and the message references module resolution. The 500 is generated by the Vercel runtime before your request handler gains control. Fix: add the missing package to requirements.txt and redeploy.

Runtime bug (500, app logs present)

[INFO]  POST /mcp  200  4100ms   ← first call, cold start
[INFO]  POST /mcp  200  38ms     ← warm, fast
[ERROR] POST /mcp  500  41ms
[INFO]  Tool called: initiate_checkout
[ERROR] KeyError: 'sku'

Normal response time, your log output appears up to the point of the error. This is a bug in your tool handler, not a cold-start issue.

Every error, exact fix.

These are the most common failures when testing FastMCP servers — from local Inspector debugging through Vercel production. Each one has a specific cause and a one-step fix.

@asynccontextmanager
async def lifespan(server):
    http_client = httpx.AsyncClient(timeout=10.0)
    yield {"http_client": http_client}
    await http_client.aclose()

mcp = FastMCP("MyServer", lifespan=lifespan)

The complete testing sequence.

Follow these steps in order. Each one must pass before you proceed to the next — skipping ahead is how bugs get deployed to production.

1. Run MCP Inspector against your local server

   Run npx @modelcontextprotocol/inspector uv run server.py and open http://localhost:6274. In the Tools tab, confirm your expected tools appear with correct schemas. Click each tool, enter test inputs, and confirm they return non-error responses. Check the Notifications pane for any stderr output. Fix all issues before deploying.

2. Run Inspector against your deployed Vercel server

   Run npx @modelcontextprotocol/inspector https://your-project.vercel.app/mcp. The same tools that passed locally should appear here. If you see a 401, add --header "X-API-Key: your-key". A 404 means your server isn't handling /mcp — check your vercel.json rewrite rules. A 405 means a transport mismatch — see the errors section.

3. Run the Python test script against the deployed URL

   Execute MCP_SERVER_URL=https://your-project.vercel.app/mcp python test_server.py. Every assertion must pass. A failing tool list assertion means the server is up but not advertising tools correctly. A failing response-shape assertion means your tool handler has a serialization bug. Fix and redeploy until all assertions pass.

4. Wire Claude Desktop and verify tools appear

   Edit claude_desktop_config.json with Option A (local) or Option B (mcp-remote) config. Fully quit Claude Desktop (Cmd+Q on macOS) and relaunch. Confirm the MCP slider icon appears in the chat input area. Click it to see your tool names listed.

5. Execute a real tool call through Claude and check Vercel logs

   Type a prompt that should trigger one of your tools. Watch for the tool-call approval dialog. After it executes, open your Vercel project → Logs and filter by your /mcp route. Confirm you see 200 responses with your application log output. If you see any 500s, click the row to see the full Python traceback in the Log Messages panel.

Questions from the real install.