CLAUDE.md Template for Any Repository
A 70-line starter CLAUDE.md: project, stack, commands, hard rules, how to verify work and what not to do.
- Claude Code
1 file2.1 KB.md
A project .mcp.json with one stdio server and one HTTP server, with secrets and paths kept in environment variables.
By Matthews WongUpdated 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.
Exactly what the download contains. Read it first, then copy or download.
{
"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}"
}
}
}
}
# .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.
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.
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.
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.
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.
Commit .mcp.json and list the variable names in your project README. Teammates set the variables, pull, and get the same approval prompt.
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.
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.
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.
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.
Short answers before you download it.
Free lessons and articles on this site that explain the ideas behind it.
Primary sources checked on the research date. Follow them for the current version.
A 70-line starter CLAUDE.md: project, stack, commands, hard rules, how to verify work and what not to do.
1 file2.1 KB.md
A planning prompt that covers business, domain, tech design and steps, then lists the decisions it needs from you.
1 file2.3 KB.md
A stdio MCP server with two tools, a resource, a prompt and a smoke test, on the v2 SDK.
9 files11.1 KB.zip