Testing your FastMCP Server

How to test your FastMCP server.

The best way to ensure a reliable and maintainable FastMCP Server is to test it! The FastMCP Client combined with Pytest provides a simple and powerful way to test your FastMCP servers.

Prerequisites

Testing FastMCP servers requires pytest-asyncio to handle async test functions and fixtures. Install it as a development dependency:

pip install pytest-asyncio

We recommend configuring pytest to automatically handle async tests by setting the asyncio mode to auto in your pyproject.toml:

[tool.pytest.ini_options]
asyncio_mode = "auto"

This eliminates the need to decorate every async test with @pytest.mark.asyncio.

Testing with Pytest Fixtures

Using Pytest Fixtures, you can wrap your FastMCP Server in a Client instance that makes interacting with your server fast and easy. This is especially useful when building your own MCP Servers and enables a tight development loop by allowing you to avoid using a separate tool like MCP Inspector during development:

import pytest
from fastmcp.client import Client
from fastmcp.client.transports import FastMCPTransport

from my_project.main import mcp

@pytest.fixture
async def main_mcp_client():
    async with Client(transport=mcp) as mcp_client:
        yield mcp_client

async def test_list_tools(main_mcp_client: Client[FastMCPTransport]):
    list_tools = await main_mcp_client.list_tools()

    assert len(list_tools) == 5

We recommend the inline-snapshot library for asserting complex data structures coming from your MCP Server. This library allows you to write tests that are easy to read and understand, and are also easy to update when the data structure changes.

from inline_snapshot import snapshot

async def test_list_tools(main_mcp_client: Client[FastMCPTransport]):
    list_tools = await main_mcp_client.list_tools()

    assert list_tools == snapshot()

Simply run pytest --inline-snapshot=fix,create to fill in the snapshot() with actual data.

For values that change you can leverage the dirty-equals library to perform flexible equality assertions on dynamic or non-deterministic values.

Using the pytest parametrize decorator, you can easily test your tools with a wide variety of inputs.

import pytest
from my_project.main import mcp

from fastmcp.client import Client
from fastmcp.client.transports import FastMCPTransport
@pytest.fixture
async def main_mcp_client():
    async with Client(mcp) as client:
        yield client


@pytest.mark.parametrize(
    "first_number, second_number, expected",
    [
        (1, 2, 3),
        (2, 3, 5),
        (3, 4, 7),
    ],
)
async def test_add(
    first_number: int,
    second_number: int,
    expected: int,
    main_mcp_client: Client[FastMCPTransport],
):
    result = await main_mcp_client.call_tool(
        name="add", arguments={"x": first_number, "y": second_number}
    )
    assert result.data is not None
    assert isinstance(result.data, int)
    assert result.data == expected

The FastMCP Repository contains thousands of tests for the FastMCP Client and Server. Everything from connecting to remote MCP servers, to testing tools, resources, and prompts is covered, take a look for inspiration!

Testing with MCPJam Inspector

MCPJam Inspector is a browser-based developer tool for testing and debugging MCP servers locally. It supports all transport protocols (STDIO, HTTP, and SSE), provides protocol-level inspection, and includes an LLM Playground for testing your server with real AI models.

Getting Started

Install and run MCPJam Inspector locally:

npx @mcpjam/inspector@latest

The inspector runs at http://127.0.0.1:6274 and requires Node.js 20+. For detailed setup and usage instructions, see the official MCPJam documentation.

Key Features

• Protocol Support - Connect via STDIO, HTTP, or SSE transport
• Server Testing - Browse and execute tools, resources, and prompts
• LLM Playground - Test your server integrated with real AI models (Claude, GPT, Ollama)
• OAuth Debugging - Debug OAuth flows with detailed protocol inspection
• JSON-RPC Logs - View real-time protocol messages for debugging

Testing with Postman

Postman provides native support for the Model Context Protocol, allowing you to test MCP servers through its visual interface. Postman is particularly useful when integrating MCP servers into API workflows or collaborating with teams already using Postman for API testing.

Getting Started

1. Open Postman and create a new workspace
2. Select New > MCP
3. Choose your transport (STDIO or HTTP)
4. Enter your server connection details
5. Click Load Methods to discover available capabilities

For complete instructions, see Postman’s MCP documentation.

Key Features

• Interactive Testing - Browse and execute tools, resources, and prompts
• Collection Support - Save and organize MCP requests in collections
• Export Configurations - Export server configs for Claude Desktop, VS Code, or Cursor
• Team Collaboration - Share MCP requests and collections with your team

When to Use Each Tool

Use MCPJam Inspector when:

• Testing locally with protocol-level debugging
• Validating OAuth flows and authentication
• Testing with real LLM models in the playground
• Working with any transport (STDIO, HTTP, SSE)

Use Postman when:

• Integrating MCP testing into existing API workflows
• Collaborating with teams using Postman
• Managing MCP requests in collections
• Exporting configurations for MCP clients

Use Pytest when:

• Building automated test suites for CI/CD
• Testing multiple scenarios with parameterized inputs
• Writing regression tests for bug fixes
• Ensuring consistent behavior across code changes

All three approaches are complementary. Use MCPJam Inspector for local protocol-level testing, Postman for API workflow integration, and Pytest for automated testing.