Testing MCP servers

Who this is for and what you will be able to do

You have built an MCP server and want to confirm that its tools are listed and run correctly, and that later code changes do not quietly break them. By the end of this guide you will be able to test a server three ways: look at what it exposes with MCP Inspector, call it directly with curl, and write unit tests for its tools with pytest ^[1].

Three ways to test

The testing lesson of the mcp-for-beginners course names three approaches ^[1]:

• MCP Inspector, a tool built in Node.js that runs as a command-line tool or as a visual tool ^[1][3].
• Manual testing, where any tool that can run HTTP requests, such as curl, will do ^[1].
• Unit testing, where you use your preferred testing framework to test the features of both the server and the client ^[1].

Test with MCP Inspector

MCP Inspector is started with npx. This downloads and installs the tool temporarily and cleans it up once the request has run ^[1]. It helps you discover a server's resources, tools and prompts, try tool execution with different parameters, and view server metadata, schemas and configurations ^[1].

To start the visual interface, run ^[1]:

npx @modelcontextprotocol/inspector node build/index.js

This launches a local web interface in your browser. The dashboard shows the registered servers and their tools, resources and prompts, and you can run tools there and see the responses as they arrive ^[1].

Add --cli to run the inspector in command-line mode. The example below lists all the tools on the server ^[1]:

npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

Test with curl

If your server exposes HTTP endpoints, curl can call them directly. The examples use port 3000 and two paths, /v1/metadata and /v1/tools/execute, and are labeled as examples ^[1]:

# Example: Test server metadata
curl http://localhost:3000/v1/metadata

# Example: Execute a tool
curl -X POST http://localhost:3000/v1/tools/execute \
  -H "Content-Type: application/json" \
  -d '{"name": "calculator", "parameters": {"expression": "2+2"}}'

To execute a tool, send a POST request whose payload contains the tool's name and its parameters ^[1]. CLI tools are generally faster to use and can be scripted, which makes them useful in a CI/CD environment ^[1].

Unit tests in Python

Unit tests check each tool and resource on its own ^[1]. The Python example uses pytest, which lets you write tests as functions with assert statements. It marks the whole module for async tests and imports FastMCP from mcp.server.fastmcp ^[1]:

import pytest

from mcp.server.fastmcp import FastMCP
from mcp.shared.memory import (
    create_connected_server_and_client_session as create_session,
)

# Mark the whole module for async tests
pytestmark = pytest.mark.anyio


async def test_list_tools_cursor_parameter():
    """Test that the cursor parameter is accepted for list_tools.

    Note: FastMCP doesn't currently implement pagination, so this test
    only verifies that the cursor parameter is accepted by the client.
    """

The example builds a server named test with two tools, test_tool_1 and test_tool_2, which return fixed strings ^[1]. It then calls list_tools four ways: with no cursor, with cursor=None, with a string cursor, and with an empty-string cursor. Each time it asserts that two tools come back ^[1].

Limits and common questions

• The docstring in the example notes that FastMCP does not implement pagination yet, so this test only confirms that the client accepts the cursor parameter ^[1].
• The example's HTTP addresses are examples. Use the addresses your own server actually serves ^[1].
• Sample calculator servers are available in Java, .NET, JavaScript, TypeScript and Python ^[1]. All major SDKs have similar testing sections, so you can adapt the approach to your runtime ^[1].
• The full version of the example test file is in the MCP Python SDK repository ^[4], and the SDK itself is published at ^[2].

Next step

The next part covers deployment ^[1]. For the SDK's own documentation and tests, start from the repositories above ^[2][4].

Adapted from the testing lesson of Microsoft's open-source course *mcp-for-beginners*^[1], released under the MIT License.