fastmcp/docs/patterns/testing.mdx

---
title: Testing your FastMCP Server
sidebarTitle: Testing
description: How to test your FastMCP server.
icon: vial
---

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:

```bash
pip install pytest-asyncio
```

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

```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:

```python
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](https://github.com/15r10nk/inline-snapshot) 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. 

```python
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.

<Tip>
For values that change you can leverage the [dirty-equals](https://github.com/samuelcolvin/dirty-equals) library to perform flexible equality assertions on dynamic or non-deterministic values.
</Tip>

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

```python
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
```

<Tip>
The [FastMCP Repository contains thousands of tests](https://github.com/jlowin/fastmcp/tree/main/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!
</Tip>

## Testing with MCPJam Inspector

[MCPJam Inspector](https://www.mcpjam.com/) 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:

```bash
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](https://docs.mcpjam.com/).

### 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](https://www.postman.com/) 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](https://learning.postman.com/docs/postman-ai/mcp-requests/overview).

### 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.