Unit Test FastMCP Servers In Memory with Pytest

FastMCP in-memory pytest testing imports a FastMCP server and passes that instance directly to Client inside an async test. This article targets the stable FastMCP v2.14.5 documentation and v2 client API. The client and server exercise MCP calls in one process without ports, startup sleeps, or subprocess cleanup. Separate focused tests should still cover HTTP, stdio, authentication, and deployment behavior.

The stable FastMCP v2 server testing guide demonstrates this direct client pattern with pytest fixtures. It is a better fit for tool, resource, prompt, schema, result, and error contracts than launching a network service for every case. Removing network setup also makes it easier to place a debugger in either client or server code.

This does not replace general MCP server testing. Protocol negotiation, security, transport, client compatibility, and agent behavior remain separate concerns. The in-memory suite owns local server behavior through the same client-facing operations that a real MCP client uses.

What is FastMCP in-memory pytest testing?

An in-memory test connects the FastMCP client transport directly to a server object. The test still performs MCP operations such as listing tools, calling a tool, reading a resource, and retrieving a prompt. What disappears is the external process and network path: no host binding, port, readiness polling, TLS, or shell lifecycle is involved.

The repository scenario mcp-fastmcp-inmemory-harness-scenario in TECH_TOPUP_CHALLENGES, located at src/db/seed-data/challenges/expansion-tech-topups.ts, contrasts this pattern with a subprocess fixture that sleeps before sending raw HTTP and searches response text. Its core correction is Client(mcp): import the server, connect in memory, assert structured results, and reserve one focused smoke case for real transport.

In-memory is still an integration between FastMCP client and server components. It is often called a unit test because it is local, isolated, and aimed at one server behavior, but the label matters less than the boundary. State exactly what is real and what is replaced. FastMCP request handling is real; an external database adapter may be fake; HTTP networking is absent.

This boundary is useful for contract failures. If list_tools() omits a tool, a test can inspect registration immediately. If call_tool() returns a wrong data shape, the assertion sees the result object rather than a hand-built direct function call. If the only failure appears over HTTP, the transport suite has a smaller search area.

In-memory execution also supports negative protocol-facing cases that a direct function call cannot represent well. The client can submit a missing required argument, a wrong type, an unknown tool name, an unreadable resource URI, or an invalid prompt argument through public operations. The resulting error contract is what another MCP client observes. This makes the suite a useful bridge between plain Python unit tests and remote transport tests.

Stateful servers need an explicit isolation design. If a tool writes to an in-process store, construct a fresh store with the server fixture and inspect it after the call. If a resource depends on session identity, create separate clients or contexts according to the application contract. Never assume that closing the client resets application data unless the server owns and documents that cleanup.

Debugging MCP tools missing after capability negotiation covers problems between advertised and visible capabilities. An in-memory discovery test supplies an early regression for the server side of that contract.

Why pass a FastMCP server instance directly to Client?

Passing the instance removes failure modes unrelated to the contract under test. A subprocess can fail to start, bind the wrong port, retain state after a failed test, or become ready after an arbitrary sleep. Those are valid transport and lifecycle concerns, but they should not decide whether a pure addition tool returns the sum or whether a resource has the expected URI.

The direct client also preserves the caller's view. Tests invoke public operations instead of reaching into private server registries. This catches names, descriptions, schemas, resource URIs, prompt arguments, serialization, and errors that a direct Python function call can miss. It also keeps tests close to how other MCP clients interact.

The FastMCP v2 client guide documents client construction and operations. Pin the dependency to the v2 line, review upgrades, and do not combine these examples with the unversioned v4 alpha documentation because result fields and optional client behavior can differ.

Direct connection is especially effective for parameterized behavior. One client can call a tool with valid, boundary, and invalid inputs without restarting a service. A function-scoped server can expose a fake repository unique to the case, so parallel tests do not share records.

It also improves observability during development. A breakpoint in the tool, resource, prompt renderer, middleware, or adapter runs in the same process as the test. Logs do not need to be correlated across a child process. The test failure still needs a clear assertion; local debugging should not become a reason to accept vague checks.

How should the async pytest fixture be structured?

Create server state in a synchronous function-scoped fixture when possible. For the v2.14.5 public testing pattern used here, a function-scoped async fixture may open Client(mcp), yield it, and close it on the same event loop. Opening the client directly inside each async test is also valid. Avoid global or session-scoped clients because their connection and server state can cross test and event-loop boundaries.

Make teardown observable when the server starts background work or keeps per-client context. A test can register a fake cleanup callback, close the client context, and assert that the callback ran and no pending task remains. Keep this case separate from ordinary tool assertions. It proves lifecycle behavior rather than a business result, and it prevents a passing call from concealing resources that survive into the next test.

If tests run in parallel, give each fixture unique repository state, session IDs, and temporary paths. In-memory communication removes port collisions, but it does not isolate application globals automatically. A parallel-safe suite either avoids global mutation or restores it in a guaranteed teardown path.

The first example creates a server per test and opens the client in the test. It verifies discovery and structured data using supported public operations.

# app/mcp_server.py
from fastmcp import FastMCP

mcp = FastMCP("Catalog")


@mcp.tool
def add_stock(sku: str, units: int) -> dict[str, object]:
    """Return a proposed stock adjustment without committing it."""
    if units == 0:
        raise ValueError("units must not be zero")
    return {"sku": sku, "units": units, "status": "proposed"}


@mcp.resource("catalog://policy/adjustments")
def adjustment_policy() -> str:
    return "Adjustments require an approved inventory request."


@mcp.prompt
def review_adjustment(sku: str, units: int) -> str:
    return f"Review adjustment for {sku}: {units} units."

# tests/test_mcp_server.py
import pytest
import pytest_asyncio
from fastmcp import Client

from app.mcp_server import mcp


@pytest_asyncio.fixture
async def client():
    async with Client(mcp) as connected_client:
        yield connected_client


@pytest.mark.asyncio
async def test_add_stock_contract(client: Client):
    tools = await client.list_tools()
    add_stock = next(tool for tool in tools if tool.name == "add_stock")

    assert "sku" in add_stock.inputSchema["properties"]
    assert "units" in add_stock.inputSchema["properties"]

    result = await client.call_tool(
        "add_stock",
        {"sku": "SKU-17", "units": 4},
    )

    assert result.data == {
        "sku": "SKU-17",
        "units": 4,
        "status": "proposed",
    }

If the project uses pytest's automatic asyncio mode, the marker may not be required. Follow project configuration instead of mixing conventions. Keep one behavior per test: a schema snapshot, one successful call, one invalid input, one resource read, or one prompt render. Shared setup is useful; oversized tests are not.

How do you test tool discovery and input schemas?

Discovery is a client contract. Assert expected names, non-empty descriptions, and input schemas for tools that external hosts depend on. A renamed tool, removed required field, widened type, or stale description can break agent behavior before the Python implementation is reached.

Do not snapshot the entire capability response without review. Dynamic ordering or metadata can create noise. Select the tool by name and compare stable schema fields. For a larger catalog, create a normalized map of name to description and input schema, then store an approved fixture. When the fixture changes, reviewers should decide whether the change is compatible.

The official MCP tools specification defines discovery and invocation contracts. FastMCP generates tool schemas from Python signatures and annotations, but generation does not prove the schema expresses product intent. Test constraints that matter, such as required identifiers, enums, minimum lengths, and whether unknown properties are accepted.

Pair schema tests with behavior. A schema can advertise an integer while implementation code treats it as a string, or the schema can omit a required business rule. Parameterized calls should cover valid values at the boundary and invalid values just outside it. Contract testing schema evolution across agent releases adds compatibility analysis when existing clients depend on older contracts.

Descriptions deserve a basic assertion because models and human operators use them to choose capabilities. Ensure a write tool names its side effect and required authorization. Do not attempt to prove model selection from text alone; that belongs in an agent evaluation. The in-memory test protects the published metadata.

How do you assert tool data and failure results?

Inspect structured result fields exposed by the pinned FastMCP client instead of searching raw JSON text. Text search can pass on an error message containing the expected word, and it can fail when harmless serialization order changes. Structured assertions make type, field, and semantic errors visible.

For every tool, cover a successful result, one or more boundaries, invalid arguments, dependency failure, and authorization or policy denial where applicable. For side-effecting tools, assert both the client-visible result and the fake repository or service state. Include idempotency behavior when retries can repeat an operation.

FastMCP client versions can either expose errors in the call result or raise when configured to do so. Choose a project policy and test it consistently. Do not write a case that accepts either outcome; that erases the contract. Error content should include a stable category and useful message without leaking server internals.

Add a matrix for errors that originate at different layers. Schema validation should fail before the tool body runs. A business rejection should identify the denied operation without looking like a protocol parsing failure. A dependency outage should retain a stable category while hiding credentials and provider internals. An unknown tool should remain distinct from a known tool that failed during execution. Assert the fake dependency call count to prove where processing stopped.

When a tool returns both text content and structured data, name which representation clients should treat as authoritative. Assert both only when both are part of the published contract. If text is a human summary of structured fields, verify that it does not contradict them. A test that checks only friendly text can miss a broken data object consumed by an application.

from unittest.mock import AsyncMock

import pytest
from fastmcp import Client, FastMCP


@pytest.mark.asyncio
async def test_lookup_returns_structured_data():
    repository = AsyncMock()
    repository.find.return_value = {
        "sku": "SKU-21",
        "available": False,
    }
    server = FastMCP("Test Catalog")

    @server.tool
    async def lookup_stock(sku: str) -> dict[str, object]:
        return await repository.find(sku)

    async with Client(server) as client:
        result = await client.call_tool("lookup_stock", {"sku": "SKU-21"})

    assert result.data == {"sku": "SKU-21", "available": False}
    repository.find.assert_awaited_once_with("SKU-21")

The fake dependency makes the input and output exact while the FastMCP request path remains real. Add separate cases where find raises the application's timeout and not-found errors. Assert the agreed MCP-visible result and that no secret fields from the exception appear.

MCP server evaluation for tool safety and compliance tests higher-level policy outcomes. The in-memory suite should prove local denials and result shapes that those evaluations assume.

How do you test FastMCP resources and prompts?

Resources and prompts are capabilities with their own discovery and access contracts. For resources, assert URI, name, media type where defined, returned content, unknown URI behavior, and authorization. For templates, parameterize valid and invalid URIs. A resource test should also catch cross-tenant reads and path traversal if the server maps user input to storage.

Prompt tests should assert registration, required arguments, rendered message roles and content, and treatment of unsafe or missing values. A prompt is not only a string helper once published through MCP. Its name and argument contract are discoverable by clients, and rendering errors need a consistent result.

Use the same in-memory client but separate tests. A resource failure should not be hidden inside a test that also checks two tools and a prompt. This organization mirrors FastMCP's own recommendation that each test demonstrate one behavior.

The v2 client returns read_resource() content as a list of MCP resource content objects. Text entries expose .text. get_prompt() returns an MCP GetPromptResult; its .messages entries expose .role and a content object whose text form exposes .text. These tests use the function-scoped client fixture from the first example and exercise those v2 return structures directly.

@pytest.mark.asyncio
async def test_reads_adjustment_policy(client: Client):
    resources = await client.list_resources()
    assert any(
        str(resource.uri) == "catalog://policy/adjustments"
        for resource in resources
    )

    content = await client.read_resource(
        "catalog://policy/adjustments"
    )

    assert len(content) == 1
    assert content[0].text == (
        "Adjustments require an approved inventory request."
    )


@pytest.mark.asyncio
async def test_renders_review_adjustment_prompt(client: Client):
    prompts = await client.list_prompts()
    assert any(
        prompt.name == "review_adjustment"
        for prompt in prompts
    )

    result = await client.get_prompt(
        "review_adjustment",
        {"sku": "SKU-17", "units": 4},
    )

    assert len(result.messages) == 1
    assert result.messages[0].role == "user"
    assert result.messages[0].content.text == (
        "Review adjustment for SKU-17: 4 units."
    )

Resource change notifications and subscriptions require additional state and client observation. Testing MCP list-changed notifications and resource subscriptions covers those asynchronous contracts. A basic in-memory resource read proves content and access, not notification delivery across a remote transport.

Prompt and resource content can carry untrusted text. Tests should verify that policy metadata and escaping are applied where the application promises them. They should not claim that reading content automatically prevents prompt injection. Security needs host policy, least privilege, and agent-level cases in addition to server contracts.

How do you mock dependencies and parameterize edge cases?

Construct the server around injected adapters when feasible. A repository, clock, identity provider, or HTTP client passed into a server factory is easier to fake than a module global. If production code imports a global adapter, patch the name in the module where the tool resolves it.

Parameterize inputs that share one expected behavior: blank IDs, illegal characters, values just outside a range, or unsupported enum members. Keep expected errors explicit in the table. Do not combine unrelated failure categories into one list merely to reduce test count.

For a downstream client, use Mock or AsyncMock and assert the exact call. A successful tool response is insufficient if the adapter received the wrong tenant ID or omitted an idempotency key. For a database fake, expose committed state so the test can distinguish a returned receipt from a real write.

Keep nondeterministic values controllable. Inject a clock for expiry, a deterministic ID source for receipts, and a fake queue for published events. Flexible matchers are appropriate only for values whose exact content is intentionally outside the contract. Do not normalize away a timestamp or ID if clients depend on its format.

MCP OAuth audience and scope testing requires token and server configuration beyond a simple tool fake. Local authorization functions can be unit-tested in memory, while real bearer handling and gateway policy need focused HTTP coverage.

What does in-memory transport leave untested?

In-memory tests do not prove network routing, HTTP path configuration, authentication headers, TLS, proxies, gateway limits, socket cancellation, or remote deployment. They also do not prove stdio process startup, environment variables, standard-output framing, or child-process shutdown. Those absences are the reason the local suite is focused, not evidence that transport is irrelevant.

Use a layered plan:

Do not repeat every business case in every row. Select cases that can fail only at that boundary. One authorized HTTP call and one denied call may prove middleware wiring; the larger input matrix remains in memory. One stdio initialize and tool call can prove clean framing; every catalog lookup does not need a subprocess.

Cancellation deserves a split as well. An in-memory case can prove that the server handler observes cancellation and releases a local fake dependency. An HTTP case proves cancellation through the network transport. A subprocess case proves process-owned cleanup only when process isolation is part of the contract. Record which layer initiated cancellation and whether a late tool result was discarded, returned, or logged according to policy.

Authentication tests should follow the same rule. Test pure authorization decisions with controlled identity in memory where the server supports that injection. Test bearer extraction, audience, scope propagation, and gateway rejection over the real HTTP middleware. A green local authorization function does not prove that deployment forwards the intended identity, while an HTTP denial does not cover every resource and tool permission combination economically.

Performance observations from in-memory execution should not be presented as network service performance. The direct transport omits deployment latency and infrastructure. Use it to catch accidental blocking or hanging local behavior with bounded synchronization, then measure service objectives only in an environment that includes the relevant transport and dependencies.

MCP capability negotiation across protocol versions belongs in a client-server compatibility suite. MCP testing interview scenarios can help explain the layer choices, but the implementation should name exact risks and proof for this server.

How do you build the FastMCP test workflow?

Apply this workflow to a new or changed FastMCP server:

1. Inventory tools, resources, prompts, authorization rules, and external dependencies.
2. Build a function-scoped server fixture with fakes for dependencies that are outside the test.
3. Open Client(server) in an async context managed by the test.
4. List capabilities and assert stable names, descriptions, URIs, and schemas.
5. Call each tool with representative valid and boundary inputs and inspect structured data.
6. Exercise invalid arguments, dependency errors, policy denials, and side-effect reconciliation.
7. Read resources and retrieve prompts through the same client in focused tests.
8. Parameterize edge cases and assert exact fake dependency interactions.
9. Close the client and verify state cleanup when the server maintains sessions.
10. Add only the HTTP, stdio, and deployed smoke cases needed for omitted boundaries.

Run the in-memory suite on ordinary changes. Route network and process cases according to their setup and environment needs. A transport failure should preserve request identity, sanitized server error, and lifecycle logs. A local tool failure should preserve the fixture and structured result.

When capabilities change, review related clients and agent hosts before approving schema snapshots. Secure agent tool execution policy is relevant when a new tool expands authority. Discovery success alone is not approval to expose a dangerous action.

FAQ

Does in-memory testing use the real MCP protocol?

Yes. The FastMCP client and server still exchange protocol operations through an in-memory transport. The absent layers are network and process infrastructure. That makes the pattern suitable for capability and behavior contracts, while dedicated tests cover wire and deployment concerns.

Does an in-memory test need a port?

No. Pass the server object directly to Client. There is no listener, port selection, readiness sleep, or orphan process. If a case requires a URL, headers, TLS, or gateway behavior, move that case to the HTTP suite.

Should the client fixture be session-scoped?

Prefer function scope unless shared session state is the explicit subject. Function scope prevents one test's registrations, data, connection state, or event loop from affecting another. A shared fixture needs an intentional reset and concurrency policy.

How should structured tool results be asserted?

Inspect the result's structured data field for the pinned FastMCP version. Assert values, types, and stable fields, then verify the dependency call or side effect. Avoid searching serialized response text because formatting is not the business contract.

Can resources and prompts use the same client?

Yes. A connected client can call all advertised server capabilities. Keep each test focused even when setup is shared. Separate discovery, resource content, prompt rendering, and tool behavior so the failure identifies one broken contract.

Which cases still need HTTP or stdio?

HTTP covers routes, auth headers, network cancellation, TLS, and gateway behavior. Stdio covers process startup, environment, framing, and shutdown. Keep a small set of boundary-specific cases there and leave the larger functional matrix in memory.

Conclusion: Make transport a deliberate test boundary

FastMCP's direct client-to-server connection gives pytest a precise way to exercise tools, resources, prompts, schemas, results, and errors without process noise. The suite remains client-facing, so it catches registration and serialization defects that direct function calls could miss.

Treat HTTP, stdio, and deployment as additional boundaries with their own proof. When each behavior sits at the lowest layer that can demonstrate it, failures are easier to reproduce and the slower smoke cases stay focused on risks that only a real transport can expose.