Sharing an MCP server

The file is shared, the value is not

An MCP server is a separate program that offers tools to an agent over a standard protocol. A project .mcp.json file lists the servers Claude Code starts, and it is committed, so every teammate gets the same ones. That is the point of it. It also means anything written in it is shared.

Claude Code reads ${NAME} in that file from the environment. The file holds the name and each machine holds the value.

A variable name in the file gives a working server

The file names the variable. Claude Code fills in the value from the environment when it starts the server. The agent calls the tool and answers.

The call list also shows Bash, Read and ToolSearch. The agent asked for Bash and Read too, but this run allows only the stock tool. Claude Code defers MCP tool definitions until they are needed, so the agent calls ToolSearch to load the stock tool's definition before it calls the tool.

Open the agent card to read the committed file. It holds no token.

The environment block as written

The env block tells Claude Code which variables to give the stock server. The starting file writes the token itself into the block, so the committed file holds the secret. A leaked token also stays in history after the file is fixed, so the old value must be rotated.

What does the committed file hold?

Take the stock question. The starting .mcp.json has the token written in its env block, and the team commits the file.

The token is written into the file

This is the same question with the starting code. The server answers, so nothing looks wrong at runtime. The committed file holds the token, and the result card is red.

This is a real Claude Haiku 5.5 run through the Claude Code CLI, recorded once and replayed here.

Write the name of the variable, not the value

The fix writes the name in the form ${STOCK_TOKEN} and never the value. Each teammate sets the variable on their own machine.

The server still gets its token. The repository never holds it. A token that was already committed stays readable in history, so rotate it: revoke the old value and issue a new one.

A server only one person needs stays in that person's own user file. Before writing a custom server, check whether a maintained community one fits. The run shows both files active: two servers connected, and the stock tool answers.

Descriptions decide which tool is called

A shared server only helps if the model picks the right tool from it, and it picks from each tool's description. A description that says "gets data" gives the model nothing to choose by, so a question can go to the wrong tool. State the inputs, give an example of one, and say what the tool does not return.

The stock server, shown below, says that get_stock reads units for a product id from P-1 to P-30 and returns no price. Two tools with overlapping descriptions are the same fault, so give each its own inputs and limits.

Split a catch-all tool, one that takes a mode field, into narrow tools. Prompt wording pulls too: "always check the policy first" makes the policy tool run on every question, even a greeting. Word it for the case that needs it.

The same question, two committed files

Use the switch to run the question with the token inline, then with the name of the variable. The card marked "This is where the runs split" shows where the token lives.

Try the price question too. Both files reach the server the same way.

Try it: token and questions

Change one setting at a time. Pick a question, then switch between the inline token and the variable name.

Every combination is a recorded run, so this works with no internet.

The same file in the Agent SDK

The Agent SDK takes the path of the same .mcp.json, so the file you committed serves both the command line and code. Built-in tools are turned off here, so the model has only the server's tools.

This server is a local process that talks over stdio. A remote server uses streamable HTTP, and SSE is deprecated. Every connected server's tools are available to the agent, though Claude Code may defer loading their definitions behind tool search. A resource is content the agent reads, such as a catalogue of what exists, while a tool acts.

You do: take the token out

Copy the starting file and open work/mcp-integration/.mcp.json. The stock server's token is written into the file, so every clone of the repository carries it.

./workshop start mcp-integration
./workshop check mcp-integration
./workshop watch mcp-integration

The checks want no token in the file and the variable name in its place. The server must still receive STOCK_TOKEN, and the options must point at the committed file.

Check your understanding

Answer each question, then read why every option is right or wrong. The wrong options are the mistakes engineers make on the job.

Play: predict the output

The committed file now holds a variable in place of the token.

{
  "mcpServers": {
    "stock": {
      "command": "python",
      "args": ["stock_server.py"],
      "env": { "STOCK_TOKEN": "${STOCK_TOKEN}" }
    }
  }
}

References

• MCP in Claude Code: project scope, .mcp.json and where variables are expanded.
• MCP resources specification: how a server exposes data as resources beside its tools.
• Agent SDK MCP: the same server config passed to an SDK agent.
• MCP security best practices: token handling and the other risks of running a server.

Conclusions

• A committed .mcp.json is shared, so it names variables and never holds values.
• Each machine sets the variable, so the secret stays out of git.
• A personal server lives in the user's own file, and both are active at once.

You can now write a shared MCP config that a whole team can commit safely.