# How to add a stdio MCP server to Claude Code

> Register a local stdio MCP server for Claude Code in a project file your team reviews, and start each entry the way a client would to list its tools.

Source: https://voxgig.com/howto/add-a-stdio-mcp-server-to-claude-code

- Audience: api-consumer
- Level: beginner
- Languages: typescript, go
- Verified: 2026-11-22
- Published: 2026-11-22

## Short answer

Run claude mcp add --scope project with the server's name, then -- and its command, or write the same entry into .mcp.json at the project root and commit it. Give the command as an absolute path, or one every machine's PATH resolves, with an explicit `env` block, because a bare npx fails where the client's PATH has no node. Start the entry yourself and list its tools, then check /mcp in a session.

---
## You will need

Claude Code installed, and Node 22.18 or later, which runs a TypeScript file by stripping its
types. The sample needs no Claude Code: `launch.mjs` stands in for the client, and no script calls
a model. Its TypeScript runs in the gate, and its Go runs only in `record.sh`. The memory server
2.2.1 declares Node 24 or later, so `npm ci` warns `EBADENGINE`, and it ran on Node 22 here. The
remote case is the prerequisite on
[connecting a remote MCP server to Claude Desktop](/howto/connect-a-remote-mcp-server-to-claude-desktop).

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Docker-run memory server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) | Every machine already runs Docker and you want one image | Docker on every machine, and the README's image name carries no tag | Some machines have no Docker |
| [Go MCP server from the Voxgig SDK Catalog](https://github.com/voxgig-sdk/jsonplaceholder-sdk/blob/a21ce5a97d8ed4c85e02123b61a67a3a408d60a9/go-mcp/README.md) | The API is in the catalog and two read-only tools are enough | Its README names no binary to download, so every machine builds it with Go | You need write tools or an API the catalog lacks |
| [Node server launched with `npx`](https://code.claude.com/docs/en/mcp#option-3-add-a-local-stdio-server) | The server is an npm package and node is on every PATH | Needs node and `npx` on the client's PATH, which a version-manager shim can leave out | Machines install node in different ways |
| [openapi-typescript and openapi-fetch](https://openapi-ts.dev/openapi-fetch/) | You want each tool written and named by hand | No server generation, so every tool is code you write around a typed client | You want the tools generated from the document |
| [orval](https://orval.dev/docs/guides/mcp/) | You already generate a TypeScript client with orval | Generates TypeScript you compile yourself, one tool per operation | You want tools that group operations by entity |

Voxgig maintains the SDK Catalog and the generator that wrote its Go server. It is one of five
options here, not the recommendation.

A Go binary needs nothing at run time, but it has to be built on each machine first. `npx` needs
only node, and inherits every quirk of where node is installed. Docker trades both for an image
pull and a daemon. orval and openapi-fetch are for an API no ready-made server covers.

## Write the entry into the project file

The [Claude Code MCP page](https://code.claude.com/docs/en/mcp#mcp-installation-scopes) names three
scopes. Local, the default, and user are stored in `~/.claude.json`. Project writes `.mcp.json`
at the project root, which `claude mcp add --scope project <name> -- <command> [args...]` creates.
An entry with no `type` is read as stdio. The sample's file:

```json title=".mcp.json"
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory@2.2.1"],
      "env": { "MEMORY_FILE_PATH": "${HOME}/print-shop-memory.jsonl" }
    },
    "jsonplaceholder": {
      "command": "${CLAUDE_PROJECT_DIR:-.}/bin/jp-mcp",
      "args": ["-transport", "stdio"],
      "env": { "JSONPLACEHOLDER_BASE": "${JSONPLACEHOLDER_BASE:-https://jsonplaceholder.typicode.com}" }
    },
```

Review that file in pull requests, because it starts processes on every teammate's machine.[^1] The
page says an interactive session asks before using a project server, and `claude -p` runs load
them [without asking](https://code.claude.com/docs/en/mcp#project-scope). Its
[stdio section](https://code.claude.com/docs/en/mcp#option-3-add-a-local-stdio-server) says
`CLAUDE_PROJECT_DIR` is set in the server's environment and not in Claude Code's, so in `command`
or `args` it needs the `:-.` default. That default is a relative path, which the
[debugging page](https://code.claude.com/docs/en/debug-your-config) says resolves against the
directory you launched Claude Code from.

## Start each entry the way a client would

`launch.mjs` expands `${VAR}` and `${VAR:-default}` as the page's
[expansion rules](https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcp-json)
describe. It starts each entry with its `env` block, `CLAUDE_PROJECT_DIR` and a PATH, sends
`initialize` and `tools/list` over stdio, and stops the server with the signals the page lists.
Each signal goes to the server's process group, and the launch returns once that group is empty,
or 1.5 seconds after the first signal:

```bash
node launch.mjs memory jsonplaceholder-orval jsonplaceholder-fetch
```

```text output
memory: npx -y @modelcontextprotocol/server-memory@2.2.1
  env: MEMORY_FILE_PATH=~/print-shop-memory.jsonl
  connected: memory-server 2.2.1, protocol 2025-06-18
  tools (9): add_observations, create_entities, create_relations, delete_entities, delete_observations, delete_relations, open_nodes, read_graph, search_nodes
jsonplaceholder-orval: node ./orval/compiled/server.js
  connected: jSONPlaceholderPostsServer 1.0.0, protocol 2025-06-18
  tools (2): getPost, listPosts
jsonplaceholder-fetch: node ./openapi-fetch/server.ts
  env: JSONPLACEHOLDER_BASE=https://jsonplaceholder.typicode.com
  connected: jsonplaceholder-fetch 1.0.0, protocol 2025-06-18
  tools (2): get_post, list_posts
```

The npm package ran from the lockfile, because `npx` found the pinned version installed locally.

## Build the catalog's Go server

The server's README builds it with `make build` and names no binary to download. Its
module at v0.0.7 holds a `replace` directive, which the
[Go module reference](https://go.dev/ref/mod#go-install) forbids for `go install`. So
`go/go.mod` builds it as a tool of a module of your own, pinned to the main branch:

```go title="go/go.mod"
module example.com/jpmcp

go 1.25.0

replace github.com/voxgig-sdk/jsonplaceholder-sdk/go => github.com/voxgig-sdk/jsonplaceholder-sdk/go v0.0.8-0.20261103055737-a21ce5a97d8e

tool github.com/voxgig-sdk/jsonplaceholder-sdk/go-mcp
```

`record.sh` built it with `go build`, ran `launch.mjs` on the entry, and tried `go install` at
v0.0.7:

```text title="records/launch-jsonplaceholder.txt"
jsonplaceholder: ./bin/jp-mcp -transport stdio
  env: JSONPLACEHOLDER_BASE=https://jsonplaceholder.typicode.com
  connected: jsonplaceholder 0.0.1, protocol 2025-06-18
  tools (2): jsonplaceholder_list, jsonplaceholder_load
```

`records/go-install.txt` holds the refusal. It exited 1 with the message "contains one or more
replace directives" and wrote no binary.

## Serve the same API from orval and openapi-fetch

orval generates an MCP server with `client: 'mcp'`, which its
[MCP guide](https://orval.dev/docs/guides/mcp/) says works only in `single` mode:

```js title="orval/orval.config.mjs"
export default {
  jsonplaceholder: {
    input: { target: './jsonplaceholder.json' },
    output: { mode: 'single', client: 'mcp', baseUrl: 'https://jsonplaceholder.typicode.com', target: 'src/handlers.ts', schemas: 'src/http-schemas' },
  },
}
```

orval 8.48.0 wrote a `server.ts` on version 2 of the official TypeScript SDK, one tool per
operation. `record.sh` compiled it with `tsc --strict`. The guide's agent example runs the server
in Docker for Cline. The same `command` and `args` go into `.mcp.json` unchanged.

`openapi-typescript` generates types and `openapi-fetch` is the client, so neither writes a server. A
search of the 26 English pages in the `openapi-ts.dev` sitemap found no mention of MCP. The substitute
is a server written by hand, `openapi-fetch/server.ts`, whose call the suite checks against a
stand-in on 127.0.0.1.

## Check it worked

The suite starts the three Node entries and calls both tools of the hand-written server against a
stand-in. It refuses a server that writes anything but JSON-RPC to stdout, and kills one that
ignores SIGTERM. It also starts a wrapper that exits at SIGINT and leaves a child process that
ignores SIGINT and SIGTERM, then checks that no process of the group is left:

```bash
node --test mcp.test.mjs
```

```text output
1..12
# tests 12
# suites 0
# pass 12
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 9098.196593
```

Then open Claude Code in the project, approve the project servers, and run `/mcp`. The page says
`claude mcp list` shows ``⏸ Pending approval (run `claude` to approve)`` until you do.

## When it goes wrong

The server never starts on one machine. Its node sits behind a shim that a shell profile adds to
PATH, and the client's PATH lacks it. `profile.mjs` builds that machine:

```bash
node profile.mjs
```

```text output
client PATH: a directory with no node in it
memory-npx: npx -y @modelcontextprotocol/server-memory@2.2.1
  failed: spawn npx ENOENT
bash -ic 'command -v npx' with that HOME: ~/.shims/bin/npx
memory-absolute: <absolute node> ./node_modules/@modelcontextprotocol/server-memory/dist/index.js
  env: MEMORY_FILE_PATH=~/memory.jsonl
  connected: memory-server 2.2.1, protocol 2025-06-18
  tools (9): add_observations, create_entities, create_relations, delete_entities, delete_observations, delete_relations, open_nodes, read_graph, search_nodes
```

A process started directly reads no profile, and only the interactive shell found the shim. That
shows the mechanism with processes `profile.mjs` starts itself. How Claude Code builds a server's
environment was not tested, and its MCP page says nothing about profiles. The debugging page says
executables on your PATH work as they are. Fix one machine with a local entry of the same name,
which [takes precedence](https://code.claude.com/docs/en/mcp#scope-hierarchy-and-precedence) over
the project one: an absolute node path, the server's absolute script path, and the `env` block.

The server starts and lists nothing. A server that prints to stdout breaks the protocol, which the
[stdio transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio)
forbids. Log to stderr.

## When not to do this

Do not commit a project server with a secret in its `env` block. Use `${VAR}` and let each machine
set it.

Do not build the catalog's Go server for one API call. Its two read-only tools cover list and
load, and the build needs a Go toolchain on every machine. A single `npx` package, or the
generated server from orval, is less to install.

Choose orval when your TypeScript client already comes from it and one tool per operation suits
the agent. Choose `openapi-fetch` when each tool needs a name, a description, and an argument shape of
your own. Docker suits a team that already runs it everywhere.

## Related how-tos

- [Connect a remote MCP server to Claude Desktop](/howto/connect-a-remote-mcp-server-to-claude-desktop)

- [Choose between stdio and Streamable HTTP for an MCP server](/howto/choose-an-mcp-transport)

- [Health check your MCP server connections](/howto/health-check-mcp-server-connections)

- [Decide whether to generate or hand-write an MCP server](/howto/generate-or-hand-write-an-mcp-server)

- [Share one MCP server config across several editors](/howto/share-one-mcp-config-across-editors)

## Last verified

Verified 2026-11-22 against Node 22.23.5, `@modelcontextprotocol/server-memory` 2.2.1,
openapi-fetch 0.17.0, and the catalog's JSONPlaceholder Go server at its main-branch commit.
orval 8.48.0, openapi-typescript 7.13.0 and Go 1.25.0 ran once in `record.sh`. Claude Code was not
run, and every statement about it comes from its documentation. Docker was not run either, and its
row comes from the memory server's README.

[^1]: The page also times a stdio server's exit. On macOS and Linux,
[Claude Code sends SIGINT](https://code.claude.com/docs/en/mcp#how-claude-code-stops-a-stdio-server),
then SIGTERM 100 milliseconds later, then SIGKILL after a further 400. A server that saves state at
shutdown has half a second, and the page asks it to finish within that time.