# Contoh .mcp.json: Template Gratis untuk Tim Claude Code

> Contoh .mcp.json gratis untuk Claude Code: satu MCP server stdio dan satu HTTP, dengan environment variable agar secret dan path lokal tidak ter-commit.

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

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Diperbarui: 13 November 2026
- Diperiksa terhadap: 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.

- Jenis: Template
- Bisa dipakai di: Claude Code
- Unduh: [mcp-json-template.zip](https://www.matthewswong.com/downloads/toolkit/mcp-json-template.zip) (5.1 KB)
- Lisensi: Bebas dipakai, diubah, dan dibagikan, termasuk untuk pekerjaan.

## File-filenya

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

### .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.
````

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

## Dari unduh sampai jalan

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.

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

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

## FAQ

### 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 apa yang dikemas file ini

- Pelajaran gratis: [Menambah MCP Server di Claude Code: Scope dan Izin](https://www.matthewswong.com/id/learn/claude-code-tips/add-mcp-server-claude-code/)
- Pelajaran gratis: [Scope Settings Claude Code: File Mana Menang, Mana Dibagikan](https://www.matthewswong.com/id/learn/claude-code-tips/claude-code-settings-scopes-precedence/)
- Pelajaran gratis: [Cara Membatasi Akses MCP Server: Read-Only dan Toolset](https://www.matthewswong.com/id/learn/ai-agents-mcp/scope-an-mcp-server-read-only-toolsets/)
- [Setup MCP Server Claude Code: Scope, Auth, Budget Tool](https://www.matthewswong.com/id/blog/claude-code-mcp-server-setup-governance/)
- [Transport MCP: stdio vs Streamable HTTP](https://www.matthewswong.com/id/blog/mcp-transports-stdio-vs-http/)
- [Checklist Keamanan MCP Server untuk Developer](https://www.matthewswong.com/id/blog/mcp-server-security-checklist/)

## Sumber

- [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)

[Semua item toolkit](https://www.matthewswong.com/id/toolkit/)

---

- HTML version: https://www.matthewswong.com/id/toolkit/mcp-json-template/
- English: https://www.matthewswong.com/en/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
