Starter kit for an MCP server for your own service

What you get

Left to you, because no check can do it: Put the real API's base URL and key into .env and try the server from your agent on real data: decide then whether the tool descriptions make the agent pick the right tool.

Server

Installed along with them: MCP TypeScript SDK (client) 2.3.1, @types/node 26.6.5.

Checks

For your agent

The plan your agent follows

The agent works one step at a time and does not start a step until the previous one meets its "Done when" lines. The full instructions, with code, are in AGENTS.md.

1. Scaffold · done when:
   • npm run build and npm test run (no tests yet is fine).
   • The kit files listed under "Before you start" are still there.
2. API client and fake API · done when:
   • A test starts the fake API on a free port and the client gets, searches and fails as expected.
3. Tools · done when:
   • In-memory tests (InMemoryTransport.createLinkedPair() from @modelcontextprotocol/server, Client from @modelcontextprotocol/client) cover every tool: a hit, no hit, invalid arguments, a 500 from the fake API, and a check that no result text contains the key or the API's base URL.
   • Calling a tool that is not registered throws (ProtocolError: Tool ... not found) instead of returning isError: test that case with rejects.
4. Stdio entry · done when:
   • A test spawns node dist/index.js, writes an initialize request to its stdin and reads one JSON-RPC response from stdout, with nothing before it.
   • The Inspector CLI lists and calls the tools (see Definition of done).
5. Connect it to the agent · done when:
   • The README lines use /absolute/path/to/dist/index.js as a placeholder, say how to print the real one (realpath dist/index.js), and name every variable the server reads.
6. Verify · done when:
   • Every line under Definition of done is true, and anything that could not be verified is named in PROGRESS.md.

Known traps

What test builds and the official docs showed going wrong with these parts. Each one is in the brief, so the agent reads it before it gets there.

• SDK version 2 is a different package set: import from @modelcontextprotocol/server (and .../server/stdio), not from @modelcontextprotocol/sdk/server/mcp.js; use registerTool with a z.object schema instead of server.tool(); start stdio with serveStdio(factory) instead of new StdioServerTransport() plus connect. SDK v2 docs
• TypeScript 6 and newer no longer include @types/* automatically; the SDK's published types reference Buffer, so tsc fails until "types": ["node"] is in tsconfig. SDK README, and measured with @modelcontextprotocol/server 2.3.1, TypeScript 7.0.2 and Node 22.22, Oct 12, 2026
• Anything printed to stdout in a stdio server breaks the protocol: the host parses every stdout line as a JSON-RPC message. SDK v2 docs
• The SDK turns an exception thrown in a tool handler into the result text the model reads, word for word: an error that contains a URL with a key in its query string hands the key to the model. SDK v2 docs, and measured with @modelcontextprotocol/server 2.3.1, TypeScript 7.0.2 and Node 22.22, Oct 12, 2026
• Invalid arguments do not throw on the client: they come back as a normal result with isError: true and "Input validation error: ...". Tests that wait for an exception pass when they should fail. measured with @modelcontextprotocol/server 2.3.1, TypeScript 7.0.2 and Node 22.22, Oct 12, 2026
• With an outputSchema, a result without structuredContent (or with the wrong shape) is turned into an error result. measured with @modelcontextprotocol/server 2.3.1, TypeScript 7.0.2 and Node 22.22, Oct 12, 2026
• The MCP Inspector 2.10.1 needs Node 22.19 or newer; mode flags (--cli, --web, --tui) must come before the server command, and -e KEY=VALUE after it (--cli node dist/index.js -e API_KEY=fake-key --method tools/list). Put before the command, -e fails with "No servers found in config file". The CLI exits with code 5 when a tool result has isError: true, though it prints the result: scripts must not read that as the Inspector failing. npm registry, `--help`, and measured with Inspector 2.10.1, Oct 12, 2026
• TypeScript 7 does not export typescript/bin/tsc: require.resolve('typescript/bin/tsc') fails with ERR_PACKAGE_PATH_NOT_EXPORTED. Run tsc through npm scripts (pretest), or resolve typescript/package.json and join bin/tsc. measured with @modelcontextprotocol/server 2.3.1, TypeScript 7.0.2 and Node 22.22, Oct 12, 2026
• Vitest 5 writes a small token file, vitest/.vitest-secret-token, into the user's data folder on the first npm test: $XDG_DATA_HOME or ~/.local/share on Linux, ~/Library/Application Support on macOS, %LOCALAPPDATA% on Windows. If you may not write outside the project, on Linux point XDG_DATA_HOME at a git-ignored folder inside it when you run the tests. Vitest 5.0.4 package source, `getUserDataDir()`

Checks on this kit

• Note The kit uses SDK version 2 (2.3.1). Version 1 (@modelcontextprotocol/sdk) still installs and has the most examples online; do not mix the two in one project. Source

What happened when an agent built from it

The recipe was given to a fresh coding agent in a clean sandbox, twice. The agent got only the kit files. It had to build the project and write down everything in the brief that was wrong, missing or unclear.

Result of the last build. A TypeScript MCP server with search, get and create tools over a fake notes API, served over stdio and over HTTP with a bearer token; 36 tests pass, the MCP Inspector CLI lists and calls the tools, and Claude Code connects to it. Its findings went back into the recipe, which is now at v0.3. That version has not been built again as a whole.

Checked again on Oct 19, 2026. AgentGid checks every recipe each week, without a model: 7 pinned packages all still exist on their registries, 1 of them has a newer release than the tested pin; 18 links in the brief: all open (2 refused automated requests, which some sites do). npm lines are checked pin by pin, not installed.

Not checked by anyone yet

• A real API, and how well the tool descriptions steer a real agent
• Loading the config lines in Cursor, VS Code and Codex
• macOS and Windows

The kit files

Put them in an empty project folder, open your coding agent there and paste the first prompt (Claude Code first asks you to approve the MCP servers in .mcp.json). These are the files for Claude Code with the default answers; the kit builder writes them for Cursor, Codex, Copilot or another agent, and for other choices. Full guide: how to use a kit.

Download all (.zip)

Read AGENTS.md from top to bottom before you do anything else. The kit files it lists are already in this folder.

Then do step 1 of the plan and stop. Report back with:
1. the commands you ran,
2. what each "Done when" check showed (a screenshot or the output),
3. anything in AGENTS.md that turned out to be wrong, missing or out of date.

Do not start step 2 until I reply.

Read AGENTS.md from top to bottom before you do anything else. The kit files it lists are already in this folder.

Then work through the plan in order. After each step, run its "Done when" checks yourself and write one line in PROGRESS.md: the step, what you checked, and the result.
You may install the packages and download the files that AGENTS.md lists without asking. Stop and ask me only for what its "Before you start" section says needs a person.
When a check fails, fix the cause and run it again. If it still fails after two real fixes, stop and tell me what you tried.
Keep a list in PROGRESS.md of anything in AGENTS.md that turned out to be wrong, missing or out of date.
When every line of the Definition of done is true, stop and show me how to run it.

node --version   # must print v22.19 or newer
npm init -y && npm pkg set type=module
npm install --save-exact @modelcontextprotocol/server@2.3.1 zod@4.6.7
npm install -D --save-exact typescript@7.0.2 vitest@5.0.4 @modelcontextprotocol/client@2.3.1 @types/node@26.6.5

Other versions of this kit

Other versions were not test-built as a whole: the kit says which parts differ from the tested one.

Ask for this kit from your agent

Agents connected to the AgentGid MCP server get the same kit without this page: list_recipes(), then plan_project({"recipe": "mcp-server", "answers": {"agent": "cursor"}, "files": true}). Every brief also tells the agent to ask AgentGid before it adds a part that is not listed.

Recipe mcp-server v0.3. Data snapshot Oct 12, 2026: versions, licenses and prices change, so check the linked pages before you ship.

Comments

Other kits