You add an MCP server with the npx line from its README and it connects in your terminal. On a
teammate’s machine, where only a shell profile puts a version manager’s node on PATH, the entry
fails to start. The tools are missing from the session. The config file is the same on both machines, so the cause
lies somewhere it does not show.
What you get
You will end up with a reviewed .mcp.json of stdio servers and a script that starts each entry
and lists its tools. You also get a fix for the PATH failure. This is for you
if your team shares one Claude Code project.
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.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Docker-run memory server | 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 | 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 | 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 | 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 | 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 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:
{
"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. Its
stdio section 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 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
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:
node launch.mjs memory jsonplaceholder-orval jsonplaceholder-fetch
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 forbids for go install. So
go/go.mod builds it as a tool of a module of your own, pinned to the main branch:
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:
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 says works only in single mode:
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:
node --test mcp.test.mjs
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:
node profile.mjs
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 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 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
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.
Footnotes
-
The page also times a stdio server’s exit. On macOS and Linux, Claude Code sends SIGINT, 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. ↩︎ Back to text