# Write Unit Tests for an MCP Server

Yes. An agent adds unit tests that call an MCP server's tools in process with the upstream API stubbed, covering schemas, error results and odd payloads.

[Run this on Rush](https://cloud.getrush.ai/run/write-unit-tests/mcp-server/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts by finding what the existing tests can and cannot see. In an MCP server like the TypeScript weather server in modelcontextprotocol/quickstart-resources, `weather-server-typescript/package.json` has one script, `build`, and no test runner. The only tests are `tests/smoke-test.sh`, which builds the server and drives it over stdio with `tests/helpers/mcp-test-client.ts`. That helper lists the tools, checks their annotations and calls each tool that declares an `outputSchema` once, `get-alerts` for CA and `get-forecast` for one pair of coordinates, against the live National Weather Service API. When that API is unreachable the tool returns an error result and the helper skips it. So the code that turns an NWS payload into a tool result is exercised with whatever the weather is that day, or not at all.

Next it lists the branches in `src/index.ts` that a fixed payload can reach. `get-alerts` upper-cases the state, maps each feature with `??` defaults because NWS sends explicit nulls, and returns an empty array with the text `No active alerts for CA` when there are no features. `get-forecast` formats both coordinates with `toFixed(4)` for the points URL, throws when the points response has no `forecast` URL, throws on an empty `periods` list, keeps only the first five periods and turns a missing temperature into `null`, which `formatPeriod` prints as `Temperature: Unknown`. `makeNWSRequest` catches a failed `fetch` or a non-2xx status and returns `null`, and each tool turns that into a thrown error. The input schemas refuse a state that is not two characters and a latitude outside -90 to 90.

Reaching those branches needs two things: a server the test can call without a subprocess, and a `fetch` that answers from a fixture. The file calls `serveStdio(buildServer, …)` at the top level, so importing it starts a stdio server. For a server you own, the agent moves `buildServer` into `src/server.ts`, exports it and leaves the entry file with only the `serveStdio` call. Each test then builds a fresh server, joins it to a `Client` with `InMemoryTransport.createLinkedPair()`, which `@modelcontextprotocol/server` 2.4.0 exports, and replaces `globalThis.fetch` with `mock.method` from `node:test`. Where the entry file has to stay as it is, as in this repository, whose `AGENTS.md` says the tutorials quote the code line by line, the agent leaves it untouched and starts the built server over stdio with `node --import ./test/stub-fetch.mjs build/index.js`, a preload that swaps `fetch` before the server loads.

It uses Node's built-in runner, because `engines` already requires Node 24 and the repository keeps its dependencies to the SDK. The one addition is `@modelcontextprotocol/client` as a dev dependency, at the version `tests/helpers` already locks. Tests compile through a `tsconfig.test.json` into a directory outside `build`, since `files` publishes `build`, and `npm test` runs them with `node --test`. The agent adds a `test-typescript` target to the `Makefile` and makes `test` depend on it, so the `make test` step in `.github/workflows/ci.yml` runs the unit tests with no workflow edit. It runs `npx tsc --noEmit`, `npm test` and `make test`, then breaks the five-period slice once to show a failing test and restores it.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Write unit tests for this MCP server's tools. Read package.json, tsconfig.json, the server entry file, the Makefile, the CI workflow, AGENTS.md and any existing tests first, and say what the existing tests cover and what they skip. Test each tool through the protocol, not by calling handlers directly: build the server from its factory, connect it to a Client over InMemoryTransport.createLinkedPair, and replace globalThis.fetch with fixtures so no test reaches the network. If importing the entry file starts the stdio server, move the factory into its own module and export it; if the repository's contributor notes say the entry file must not change, leave it and start the built server over stdio with a node --import preload that stubs fetch. Cover: tools/list returns each tool with its input schema, output schema and annotations; a normal upstream payload; null and missing fields in the payload; an empty list; more items than the tool returns; a non-2xx status and a rejected fetch, asserting the result is an error result with the tool's message; arguments the input schema rejects; and that structuredContent matches the declared output schema, array root or object root. Assert the exact upstream URLs requested. Use node --test with no new runtime dependency, compile tests outside the published build directory, add an npm test script and wire it into the existing make test target. Run the type check, the unit tests and the existing smoke tests, break one mapping to show a failing test, restore it, and open a pull request with the output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds the test file, the fixtures as small JSON payloads beside it, `tsconfig.test.json`, a `test` script in `package.json`, the dev dependency with its lockfile change, and the `Makefile` target. When the factory was moved, the diff also shows `src/server.ts` and a shorter entry file, with no change inside either tool. The description lists each test name with the branch it reaches, the output of the type check, the unit tests and the smoke tests, and the red run from the deliberate break followed by the green one.

It also reports what the tests found and did not fix. In this repository that would include how an argument the input schema refuses comes back, as an error result or as a protocol error, since the test records whichever the SDK does. It would also include any place the five language versions disagree on the same payload: the TypeScript server maps a missing temperature to `null`, while `weather-server-python/weather.py` declares `temperature: int` and reads `period["temperature"]` directly. A reviewer checks that no test opens a socket, that every fixture is a payload shape the upstream API really sends, and that the assertions name exact text and URLs and not just truthiness.

## Run it on every GitHub issue labelled needs-tests

Create an automation in the Project that holds the server's repository with a `github` trigger on `issues.labeled` and `needs-tests` in its `labels`. The trigger puts the issue after the saved prompt and fills in nothing, so the prompt is this page's request with one more sentence: write tests for the tool the issue names, and mention the issue in the pull request. It fires only when the label is added by an owner, member or collaborator of the repository.

A team that keeps several MCP servers sends this body once per repository from its own script, each with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so running the script twice returns the runs already started. An API key runs four at once by default and the rest wait as `queued`, so the script needs no retry loop.

## Why run it on Rush?

A tool that wraps someone else's API is tested against that API's good days unless someone writes the bad ones down. The agent does the tedious part: it reads every branch, builds a payload for each, and runs the suite in a sandbox that starts with nothing but the repository, so a test that passes only because of a stale build or a local environment variable fails there. Every command and its output stays in the run's record, and the pull request quotes it.

It also tests at the layer a client sees. Calling a handler function directly skips input validation, the output schema check and the way an exception becomes an error result, which are the parts an MCP host depends on. Going through a linked in-memory transport keeps all of that in the test and needs no subprocess and no network.

## Frequently asked questions

### Do the tests call the real upstream API?

No. `fetch` is replaced before each test and restored after, and the assertions include the URLs the tool asked for. The existing smoke tests keep calling the live API once per tool. The unit tests cover the cases a live call cannot produce on demand, such as a null field or an empty list.

### Why go through a client instead of calling the tool function?

Because a tool's contract is what arrives over the protocol. The SDK checks arguments against the input schema, checks `structuredContent` against the output schema and converts a thrown error into an error result. A direct call tests none of those, and in this server the handlers are inline closures inside `buildServer`, so nothing exports them.

### Does it work for a Python MCP server?

Yes, with different tools. For a server like `weather-server-python/weather.py` the agent adds `pytest` to the `dev` dependency group next to `ruff`, stubs `make_nws_request`, and runs the tests with `uv run pytest`. The cases are the same list: normal payload, nulls, empty list, upstream failure, invalid arguments.

### Will it add a test framework to my package?

Only when the repository already has one. On Node 24 the built-in `node:test` runner and its `mock` helpers cover everything here, so the default adds no runtime dependency and one dev dependency, the MCP client package. A repository that already uses Vitest or Jest gets tests for that runner.

## More MCP server jobs

- [Add Streamable HTTP to a stdio MCP Server](https://getrush.ai/run/add-streamable-http-transport/mcp-server/)
- [Review Pull Requests on an MCP Server](https://getrush.ai/run/review-pull-requests/mcp-server/)

## The same job on other stacks

- [Write Unit Tests for a Medusa Backend](https://getrush.ai/run/write-unit-tests/medusa/)
- [Write Unit Tests for a Node.js App](https://getrush.ai/run/write-unit-tests/nodejs/)
- [Write Unit Tests for an Obsidian Plugin](https://getrush.ai/run/write-unit-tests/obsidian-plugin/)
- [Write Unit Tests for a Payload CMS App](https://getrush.ai/run/write-unit-tests/payload/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
