Skip to main content
Template

Template .mcp.json untuk MCP Server Tim

File .mcp.json proyek dengan satu server stdio dan satu server HTTP, dengan secret dan path disimpan di environment variable.

Oleh Matthews WongDiperbarui Dicek dengan Claude Code 2.1.323 docs

Poin utama

File .mcp.json yang aman di-commit. Ia mendeklarasikan satu server stdio lokal dan satu server HTTP remote, serta memakai ekspansi environment variable untuk token dan path, sehingga file ini tidak menyimpan secret dan tetap jalan di mesin setiap anggota tim. README-nya menjelaskan tiap field, prompt persetujuan, dan apa yang tidak boleh di-commit.

2 file

File-filenya

Persis isi unduhannya. Baca dulu, lalu salin atau unduh.

.mcp.json402 B
.mcp.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.md4.4 KB
README.md
# .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.
Cara memakainya

Dari unduh sampai jalan

Pakai saat

  • Tim Anda perlu mendapat MCP server yang sama saat meng-clone repositori.
  • Sebuah server butuh token dan Anda tidak ingin token itu masuk version control.
  • Anda belum yakin field apa saja yang dipakai entri stdio dan entri HTTP.
  • Anda sedang me-review .mcp.json buatan orang lain dan ingin bentuk yang benar sebagai pembanding.
  1. Salin file ke root repositori

    Server dengan scope project disimpan di file .mcp.json pada root proyek. Salin template ke sana, di samping file package atau build Anda.

  2. Arahkan entri ke server Anda

    Ubah nama notes dan docs, lalu ganti command, args, dan url. Nama dan alamat mcp.example.com hanyalah placeholder. Biarkan type bernilai http pada entri remote.

  3. Atur environment variable

    Export NOTES_API_TOKEN dan DOCS_MCP_TOKEN di shell yang menjalankan Claude Code. NOTES_SERVER_PATH dan DOCS_MCP_URL sudah punya default di dalam file, jadi atur hanya bila ingin menimpanya.

  4. Jalankan Claude Code dan setujui servernya

    Claude Code meminta persetujuan sebelum memakai server dari .mcp.json. Setujui, lalu jalankan /mcp untuk melihat status tiap server. claude mcp list menampilkan peringatan missing-variable bila ada yang terlupa.

  5. Commit lalu beri tahu tim

    Commit .mcp.json dan tuliskan nama variabelnya di README proyek. Anggota tim mengatur variabelnya, melakukan pull, lalu mendapat prompt persetujuan yang sama.

Isinya

Kenapa ditulis seperti ini

Satu entri stdio dan satu entri HTTP

Entri stdio memakai command, args, dan env: Claude Code menjalankan program itu sebagai child process. Entri HTTP memakai type, url, dan headers. Entri yang punya url tanpa type dibaca sebagai server stdio dan dilewati dengan error konfigurasi.

Secret diambil dari environment

Token hanya muncul sebagai ${DOCS_MCP_TOKEN} dan ${NOTES_API_TOKEN}. Claude Code mengekspansi ${VAR} di command, args, env, url, dan headers, sehingga file yang di-commit tidak pernah menyimpan nilainya.

Default untuk hal yang berbeda di tiap mesin

Path server dan endpoint memakai ${VAR:-default}. Sebagian besar anggota tim tidak perlu mengatur apa pun, dan satu orang bisa menunjuk ke endpoint staging tanpa menyunting file bersama.

README yang membahas persetujuan dan prioritas

README berisi tabel field, variabel yang perlu diatur, perilaku prompt persetujuan pada sesi interaktif dan headless, serta entri mana yang menang saat nama server yang sama ada di scope local, project, dan user.

Perhatikan

Yang sering salah

  • Variabel yang belum diatur dan tanpa default tidak menghentikan pemuatan file. Teks ${VAR} dipakai apa adanya, sehingga server gagal belakangan dengan error yang membingungkan. Periksa peringatan missing-variable di claude mcp list.
  • Variabel yang diisi string kosong dianggap sudah diatur, sehingga ${VAR:-default} menjadi string kosong, bukan default-nya.
  • claude -p tidak bisa menampilkan prompt persetujuan, sehingga setiap server di .mcp.json sebuah repositori dimuat tanpa bertanya. Baca file itu sebelum menjalankan mode headless di repositori yang bukan buatan Anda.
  • Pada url dan headers server remote, Claude Code membaca beberapa variabel kredensial sebagai kosong, misalnya ANTHROPIC_API_KEY dan NPM_TOKEN. Beri setiap token server nama variabelnya sendiri.
Pertanyaan

Yang sering ditanyakan

Jawaban singkat sebelum Anda mengunduhnya.

Di mana .mcp.json diletakkan, dan siapa yang melihatnya?

File ini diletakkan di root proyek. Itulah scope project: servernya hanya dimuat di proyek tersebut dan dibagikan ke tim lewat version control. Scope local dan user disimpan di konfigurasi Claude Code milik Anda sendiri dan tidak dibagikan.

Bisakah memakai environment variable di .mcp.json?

Bisa. Claude Code mengekspansi ${VAR} dan ${VAR:-default} pada command, args, env, url, dan headers sebuah server. Bentuk pertama menjadi nilai variabelnya, dan bentuk kedua memakai default saat variabel belum diatur.

Kenapa Claude Code meminta saya menyetujui server dari .mcp.json?

Demi keamanan. File proyek bisa menjalankan proses di mesin Anda, jadi Claude Code meminta persetujuan pada sesi interaktif sebelum memakai server dengan scope project. Menjalankan claude mcp reset-project-choices menghapus jawaban Anda sebelumnya.

Apa yang terjadi bila nama server yang sama didefinisikan di dua scope?

Claude Code memakai definisi dari sumber dengan prioritas tertinggi: scope local lebih dulu, lalu scope project, lalu scope user. Seluruh entri diambil dari sumber itu, dan field tidak digabung antar scope.

Apakah entri server SSE masih perlu dipakai?

Utamakan HTTP. Dokumentasi Claude Code menandai transport SSE sebagai deprecated dan menyarankan server HTTP bila tersedia. Karena itu entri remote di template ini memakai type http.

Pelajari lebih dalam

Pelajari apa yang dikemas file ini

Pelajaran dan artikel gratis di situs ini yang menjelaskan gagasan di baliknya.

Sumber

Sumber primer yang diperiksa pada tanggal riset. Ikuti tautannya untuk versi terbaru.

Lainnya dari toolkit

Ambil ini juga

TemplateGratis

Template CLAUDE.md untuk Repository Apa Pun

CLAUDE.md awal 70 baris: proyek, stack, perintah, aturan keras, cara memverifikasi pekerjaan, dan yang tidak boleh dilakukan.

  • Claude Code

1 file2.1 KB.md

PromptGratis

Prompt Rencana Sebelum Coding

Prompt perencanaan yang mencakup bisnis, domain, tech design, dan langkah kerja, lalu mendaftar keputusan yang perlu Anda ambil.

  • Claude Code
  • Cursor
  • Claude.ai

1 file2.3 KB.md

Starter MCPGratis

Starter MCP Server dengan TypeScript

MCP server stdio dengan dua tool, satu resource, satu prompt, dan smoke test, memakai SDK v2.

  • Claude Code
  • Claude Desktop
  • Any MCP client

9 file11.1 KB.zip

Semua item toolkit