All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Write the missing tests.

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

The same job on other stacks

Keep reading