How-to › Use AI to do the integration

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.

Audience
API consumer
Level
beginner
Topic
Connect MCP clients to servers
Languages
TypeScript and Go
Verified

Read first: Connect a remote MCP server to Claude Desktop

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Docker-run memory serverEvery machine already runs Docker and you want one imageDocker on every machine, and the README’s image name carries no tagSome machines have no Docker
Go MCP server from the Voxgig SDK CatalogThe API is in the catalog and two read-only tools are enoughIts README names no binary to download, so every machine builds it with GoYou need write tools or an API the catalog lacks
Node server launched with npxThe server is an npm package and node is on every PATHNeeds node and npx on the client’s PATH, which a version-manager shim can leave outMachines install node in different ways
openapi-typescript and openapi-fetchYou want each tool written and named by handNo server generation, so every tool is code you write around a typed clientYou want the tools generated from the document
orvalYou already generate a TypeScript client with orvalGenerates TypeScript you compile yourself, one tool per operationYou 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.

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

  1. 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

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.