# .mcp.json Example: Free Template for Claude Code Teams

> A free .mcp.json example for Claude Code: one stdio and one HTTP MCP server, with environment variable expansion so no secret or local path gets committed.

URL: https://www.matthewswong.com/en/toolkit/mcp-json-template/

- Author: Matthews Wong (https://www.matthewswong.com/en/about/)
- Updated: 13 November 2026
- Checked against: Claude Code 2.1.323 docs

> **Key takeaway:** A .mcp.json you can commit. It declares one local stdio server and one remote HTTP server, and uses environment variable expansion for the token and the path, so the file holds no secret and works on every teammate's machine. The README explains each field, the approval prompt and what never to commit.

- Type: Template
- Works with: Claude Code
- Download: [mcp-json-template.zip](https://www.matthewswong.com/downloads/toolkit/mcp-json-template.zip) (5.1 KB)
- License: Free to use, change and share, at work too.

## The files

Exactly what the download contains. Read it first, then copy or download.

### .mcp.json

```json
{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["${NOTES_SERVER_PATH:-./tools/notes-server/dist/index.js}"],
      "env": {
        "NOTES_API_TOKEN": "${NOTES_API_TOKEN}"
      }
    },
    "docs": {
      "type": "http",
      "url": "${DOCS_MCP_URL:-https://mcp.example.com/mcp}",
      "headers": {
        "Authorization": "Bearer ${DOCS_MCP_TOKEN}"
      }
    }
  }
}
```

### README.md

````markdown
# .mcp.json template

A starter `.mcp.json` for sharing MCP servers with a team through a
repository. It declares one local stdio server and one remote HTTP server, and
keeps every secret and every machine-specific path out of the file with
environment variable expansion.

Checked against the Claude Code MCP documentation on 2026-11-13.

## Use it

1. Copy `.mcp.json` to the root of your repository.
2. Rename the two servers, then point `command`, `args` and `url` at your own
   servers. The names and URLs in the template are placeholders.
3. Set the environment variables (see below) and start `claude` in the
   repository.
4. Approve the project servers when Claude Code asks, then run `/mcp` to see
   each server's status.
5. Commit `.mcp.json`. Teammates get the same servers when they pull.

`claude mcp add --scope project` writes to this same file, so you can also let
the CLI add entries for you.

## What each field is

| Field        | Used by | What it does                                        |
| ------------ | ------- | --------------------------------------------------- |
| `mcpServers` | both    | The top-level object. Each key is a server name.    |
| `command`    | stdio   | The program Claude Code starts as a child process.  |
| `args`       | stdio   | The arguments passed to that program.               |
| `env`        | stdio   | Environment variables handed to the server process. |
| `type`       | HTTP    | `"http"` for a remote server.                       |
| `url`        | HTTP    | The server's MCP endpoint.                          |
| `headers`    | HTTP    | HTTP headers sent with requests, such as a token.   |

An entry with a `url` but no `type` is read as a stdio server and skipped with
a configuration error, so keep `"type": "http"` on remote servers.

## Environment variables

Two forms work in `command`, `args`, `env`, `url` and `headers`:

- `${VAR}` expands to the value of `VAR`.
- `${VAR:-default}` expands to `VAR` if it is set, or to `default` if not.

The template uses four variables:

| Variable            | Needed | What to set it to                            |
| ------------------- | ------ | -------------------------------------------- |
| `NOTES_API_TOKEN`   | yes    | The token the local server uses.             |
| `DOCS_MCP_TOKEN`    | yes    | The bearer token for the remote server.      |
| `NOTES_SERVER_PATH` | no     | Where the local server's entry file lives.   |
| `DOCS_MCP_URL`      | no     | A different endpoint, for example a staging. |

Each teammate exports them in the shell that starts Claude Code, for example
in a shell profile or through a secrets manager:

```bash
export NOTES_API_TOKEN="..."
export DOCS_MCP_TOKEN="..."
claude
```

Three behaviors to know:

- A variable that is unset and has no default does not stop the file from
  loading. `claude mcp list` shows a missing-variable warning for that server,
  and the literal `${VAR}` text is used as is.
- A variable set to an empty string counts as set, so the default is not used.
- In a remote server's `url` and `headers`, Claude Code reads some credential
  variables as empty, for example `ANTHROPIC_API_KEY` and `NPM_TOKEN`. Give
  each server token its own name, as the template does.

If the local server does not start with the default relative path, set
`NOTES_SERVER_PATH` to an absolute path on your machine.

## The approval prompt

A project file can start a process on your machine, so Claude Code asks for
approval in interactive sessions before it uses a server from `.mcp.json`.

- `claude mcp reset-project-choices` clears those answers.
- `claude -p` cannot show the prompt, so project servers load without asking.
  In a repository you did not write, read `.mcp.json` before a headless run.
- To block one server in every mode, list it in `disabledMcpjsonServers`.

## When the same name exists twice

Claude Code uses the whole entry from the highest-precedence source and does
not merge fields: local scope, then project scope (this file), then user scope.
A teammate can override a shared server for themselves by adding one with the
same name at local scope.

## Never commit

- A token, password or API key as a literal value. Use `${VAR}`.
- A path that only exists on your machine. Use `${VAR:-default}`.
- A server you have not read or do not trust. Servers that fetch external
  content can expose the whole team to prompt injection.
- An internal hostname you would not publish. Put it behind a variable.

## License

MIT. Use it, change it and share it.
````

## Use it when

- Your team should get the same MCP servers when they clone the repository.
- A server needs a token and you do not want it in version control.
- You are not sure which fields a stdio entry and an HTTP entry take.
- You are reviewing a .mcp.json someone else wrote and want a known-good shape to compare it with.

## From download to working

1. **Copy the file to the repository root.** Project-scoped servers live in a .mcp.json file at the root of the project. Copy the template there, next to your package or build files.
2. **Point the entries at your servers.** Rename notes and docs, then change command, args and url. The names and the mcp.example.com address are placeholders. Keep type set to http on the remote entry.
3. **Set the environment variables.** Export NOTES_API_TOKEN and DOCS_MCP_TOKEN in the shell that starts Claude Code. NOTES_SERVER_PATH and DOCS_MCP_URL have defaults in the file, so set them only to override.
4. **Start Claude Code and approve the servers.** Claude Code asks for approval before it uses a server from .mcp.json. Approve, then run /mcp to see each server's status. claude mcp list reports a missing-variable warning if you forgot one.
5. **Commit it and tell the team.** Commit .mcp.json and list the variable names in your project README. Teammates set the variables, pull, and get the same approval prompt.

## Why it is written this way

- **One stdio entry and one HTTP entry.** The stdio entry uses command, args and env: Claude Code starts that program as a child process. The HTTP entry uses type, url and headers. An entry with a url but no type is read as a stdio server and skipped with a configuration error.
- **Secrets come from the environment.** The token appears only as ${DOCS_MCP_TOKEN} and ${NOTES_API_TOKEN}. Claude Code expands ${VAR} in command, args, env, url and headers, so the committed file never holds the value.
- **Defaults for what differs per machine.** The server path and the endpoint use ${VAR:-default}. Most of the team needs to set nothing, and one person can point at a staging endpoint without editing the shared file.
- **A README that covers approval and precedence.** The README has a table of the fields, the variables to set, how the approval prompt behaves in interactive and headless runs, and which entry wins when the same server name exists at local, project and user scope.

## What goes wrong

- An unset variable with no default does not stop the file from loading. The literal ${VAR} text is used as is, so the server fails later with a confusing error. Check claude mcp list for the missing-variable warning.
- A variable set to an empty string counts as set, so ${VAR:-default} expands to an empty string, not to the default.
- claude -p cannot show the approval prompt, so every server in a repository's .mcp.json loads without asking. Read the file before a headless run in a repository you did not write.
- In a remote server's url and headers, Claude Code reads some credential variables as empty, such as ANTHROPIC_API_KEY and NPM_TOKEN. Give each server token its own variable name.

## FAQ

### Where does .mcp.json go, and who sees it?

It goes at the root of the project. That is project scope: the servers load in that project only and are shared with the team through version control. Local and user scope are stored in your own Claude Code configuration instead and are not shared.

### Can I use environment variables in .mcp.json?

Yes. Claude Code expands ${VAR} and ${VAR:-default} in a server's command, args, env, url and headers. The first form expands to the variable's value, and the second falls back to the default when the variable is unset.

### Why does Claude Code ask me to approve servers from .mcp.json?

For security. A project file can start a process on your machine, so Claude Code prompts for approval in interactive sessions before it uses a project-scoped server. Running claude mcp reset-project-choices clears your earlier answers.

### What happens if the same server name is defined in two scopes?

Claude Code uses the definition from the highest-precedence source: local scope first, then project scope, then user scope. It takes the entire entry from that source and does not merge fields across scopes.

### Should I still use an SSE server entry?

Prefer HTTP. The Claude Code documentation marks the SSE transport as deprecated and says to use HTTP servers where available. The template's remote entry therefore uses type http.

## Learn what this file packages

- Free lesson: [Add an MCP Server to Claude Code: Scopes and Permissions](https://www.matthewswong.com/en/learn/claude-code-tips/add-mcp-server-claude-code/)
- Free lesson: [Claude Code Settings Scopes: Which File Wins, What Is Shared](https://www.matthewswong.com/en/learn/claude-code-tips/claude-code-settings-scopes-precedence/)
- Free lesson: [MCP Server Least Privilege: Read-Only Mode and Toolsets](https://www.matthewswong.com/en/learn/ai-agents-mcp/scope-an-mcp-server-read-only-toolsets/)
- [Claude Code MCP Server Setup: Scopes, Auth, Tool Budget](https://www.matthewswong.com/en/blog/claude-code-mcp-server-setup-governance/)
- [MCP Transports: stdio vs Streamable HTTP](https://www.matthewswong.com/en/blog/mcp-transports-stdio-vs-http/)
- [MCP Server Security Checklist for Developers](https://www.matthewswong.com/en/blog/mcp-server-security-checklist/)

## Sources

- [Claude Code docs: connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp)
- [Claude Code docs: project server approvals and workspace trust](https://code.claude.com/docs/en/mcp#project-server-approvals-and-workspace-trust)

[All toolkit items](https://www.matthewswong.com/en/toolkit/)

---

- HTML version: https://www.matthewswong.com/en/toolkit/mcp-json-template/
- Bahasa Indonesia: https://www.matthewswong.com/id/toolkit/mcp-json-template/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
