Skip to main content

​
fastmcp.utilities.tests

​
Functions

​
temporary_settings

Temporarily override FastMCP setting values. Args:
  • **kwargs: The settings to override, including nested settings.

​
run_server_in_process

Context manager that runs a FastMCP server in a separate process and returns the server URL. When the context manager is exited, the server process is killed. Args:
  • server_fn: The function that runs a FastMCP server. FastMCP servers are not pickleable, so we need a function that creates and runs one.
  • *args: Arguments to pass to the server function.
  • provide_host_and_port: Whether to provide the host and port to the server function as kwargs.
  • host: Host to bind the server to (default: “127.0.0.1”).
  • port: Port to bind the server to (default: find available port).
  • **kwargs: Keyword arguments to pass to the server function.
Returns:
  • The server URL.

​
run_server_async

Start a FastMCP server on a real port as an asyncio task. This runs a real uvicorn server in the current process, bound to a real TCP port, and yields its URL. Use it when the behaviour under test is genuinely about the network — real sockets, TLS, or a server that must be reachable by something other than an in-process client. Otherwise prefer asgi_client or asgi_server, which exercise the same HTTP stack without binding a port. Args:
  • server: FastMCP server instance
  • port: Port to bind to (default: find available port)
  • transport: Transport type (“http”, “streamable-http”, or “sse”)
  • path: URL path for the server (default: “/mcp”)
  • host: Host to bind to (default: “127.0.0.1”)

​
asgi_server

Serve a FastMCP server’s HTTP app in-process, with no socket and no uvicorn. This is the fastest way to test a FastMCP server over HTTP. The server’s real Starlette app is built with http_app() and its lifespan is started, then every request is dispatched directly into the app on the current event loop. That skips port binding, uvicorn startup and connection setup entirely, while still exercising the full HTTP stack: middleware, authentication, session management and SSE streaming all run exactly as they do in production. Use this as a fixture when several tests share one server but each needs its own client. For a single test, asgi_client hands you a connected client in one step. Args:
  • server: FastMCP server instance.
  • transport: Transport type (“http”, “streamable-http”, or “sse”).
  • path: URL path for the server (defaults to “/mcp”, or “/sse” for SSE).
  • **http_app_kwargs: Additional arguments forwarded to server.http_app().

​
asgi_client

Serve a FastMCP server over HTTP in-process and yield a connected Client. This is the shortest path to testing a server over a real HTTP stack. The server’s Starlette app is built and started, and requests are dispatched straight into it on the current event loop — no port, no uvicorn, no subprocess — but middleware, authentication, session management and SSE streaming all behave as in production. Reach for asgi_server instead when a fixture must serve several tests that each build their own client, or when a test needs raw HTTP access to the app. Args:
  • server: FastMCP server instance.
  • transport: Transport type (“http”, “streamable-http”, or “sse”).
  • path: URL path for the server (defaults to “/mcp”, or “/sse” for SSE).
  • headers: HTTP headers to send with every request.
  • auth: Client authentication, as accepted by the HTTP transports.
  • **client_kwargs: Additional arguments forwarded to Client.

​
Classes

​
ASGIServer

A FastMCP server’s real HTTP app, reachable in-process with no sockets. Yielded by asgi_server. The url looks like an ordinary server URL and the app behind it is the genuine article — auth middleware, session manager, SSE framing and redirects all run — but every request is dispatched straight into the ASGI application on the current event loop. Because nothing is listening on the network, a plain httpx2.AsyncClient() cannot reach this server. Use client() for a FastMCP client, http_client() for raw HTTP assertions, and transport() when you need to build the client transport yourself. Methods:

​
http_client

An httpx2.AsyncClient bound to the in-process app, for raw HTTP assertions. Relative URLs resolve against the server’s base URL, and absolute URLs on the same origin work too, so client.get(f"{server.url}/health") reads the same as it would against a real server. The signature matches McpHttpClientFactory, so this method can also be handed to anything that takes an httpx_client_factory.

​
transport

A FastMCP client transport wired to the in-process app. Accepts the same keyword arguments as the underlying transport (headers, auth, …); httpx_client_factory is supplied automatically.

​
client

An unconnected FastMCP Client pointed at the in-process app. headers and auth configure the underlying HTTP transport; every other keyword argument is passed to Client (timeout, elicitation_handler, …). Use it as a context manager, exactly like any other client. Args:
  • headers: HTTP headers to send with every request.
  • auth: Client authentication, as accepted by the HTTP transports.
  • **client_kwargs: Additional arguments forwarded to Client.

​
HeadlessOAuth

OAuth provider that bypasses browser interaction for testing. This simulates the complete OAuth flow programmatically by making HTTP requests instead of opening a browser and running a callback server. Useful for automated testing. Methods:

​
redirect_handler

Make HTTP request to authorization URL and store response for callback handler.

​
callback_handler

Parse stored response and return the authorization code result.