Skip to main content
Tips Claude Code · Pelajaran 7 dari 13 · 12 menit

Menambah MCP Server di Claude Code: Scope dan Izin

Cara menambah MCP server ke Claude Code dengan claude mcp add: http vs stdio, scope local, project, user, .mcp.json, aturan izin tool MCP, dan risikonya.

Oleh Matthews WongDitinjau pada Dicek dengan Claude Code v2.1.301

Poin utama

MCP server adalah program atau layanan web terpisah yang memberi Claude Code tool tambahan, misalnya query database atau pencarian tiket, lewat Model Context Protocol. Anda menambahkannya dengan claude mcp add, memilih lokasi konfigurasinya lewat scope, dan mengatur apa yang boleh dipanggil Claude dengan aturan izin berformat mcp__server__tool.

Setelah pelajaran ini, Anda bisa

  • Menambah MCP server http atau stdio dengan flag yang benar, dan memilih scope local, project, atau user secara sengaja.
  • Menulis aturan izin yang menyebut tool MCP, dan tahu mengapa aturan deny selalu menang.
  • Mengenali risiko keamanan dari server yang tidak Anda tulis sendiri.
Lihat cara kerjanya

Ikuti diagramnya langkah demi langkah

Tekan Putar, atau melangkah dengan panah. Setiap langkah juga ditulis di bawah diagram.

Dari claude mcp add sampai satu tool call

claude mcp add menulis entri server ke file konfigurasi; Claude Code terhubung ke server, mendaftar nama tool mcp__server__tool, dan memeriksa aturan izin sebelum setiap pemanggilan.

Ditinjau pada 17 Oktober 2026 · Claude Code v2.1.301

Langkah 1 dari 6. MCP server adalah proses atau layanan web terpisah yang menyediakan tool. Claude Code adalah kliennya: membaca entri konfigurasi, terhubung, lalu menyodorkan tool server itu ke Claude.

Tombol: ← → langkah · Home / End · K putar atau jeda

  1. MCP server adalah proses atau layanan web terpisah yang menyediakan tool. Claude Code adalah kliennya: membaca entri konfigurasi, terhubung, lalu menyodorkan tool server itu ke Claude.

  2. claude mcp add menulis entrinya. Scope menentukan lokasinya: local adalah default dan hanya untuk Anda, project menulis .mcp.json di repo untuk semua orang, user berlaku di semua proyek Anda.

    claude mcp add --transport http docs https://example.com/mcp --scope projectTebak langkah berikutnya Rekan Anda menarik repo yang berisi server ber-scope project, lalu menjalankan Claude Code. Apa yang terjadi? (Langsung terhubung tanpa bertanya · Meminta persetujuan mereka dulu · File diabaikan sampai mereka menjalankan /mcp)

  3. Di sesi interaktif, Claude Code meminta persetujuan sebelum memakai server project dari .mcp.json. Setelah itu Claude Code terhubung, dan claude mcp list menampilkan kesehatan tiap server.

    claude mcp list

  4. Server mendaftar tool-nya. Setiap tool tampil di Claude sebagai mcp__server__tool. Dengan tool search, hanya namanya yang dimuat di awal; definisi lengkap diambil saat dibutuhkan.

    mcp__docs__search

  5. Sebelum call berjalan, aturan izin diperiksa berurutan: deny, lalu ask, lalu allow. Kecocokan pertama menang, seberapa spesifik pun aturan sesudahnya. Tanpa kecocokan, muncul prompt.

    mcp__docs__* (allow) mcp__docs__search (deny)Tebak langkah berikutnya Satu aturan allow dan satu aturan deny sama-sama cocok dengan satu tool call MCP. Mana yang berlaku? (Allow, karena lebih spesifik · Deny, karena deny diperiksa lebih dulu · Mana pun yang tertulis lebih dulu di file)

  6. Hasilnya masuk ke context window. Output lebih dari 10.000 token memicu peringatan, dan batas default-nya 25.000. Server yang mengambil konten dari luar bisa membawa prompt injection.

    MAX_MCP_OUTPUT_TOKENS=50000

Apa itu MCP server, dan bagaimana menambahkannya ke Claude Code?

Model Context Protocol adalah standar terbuka untuk menghubungkan alat AI dengan tool dan data di luar. Di Claude Code, MCP server adalah ujung lain dari koneksi itu: program atau layanan web yang menawarkan tool, dan kadang resource serta prompt, yang kemudian bisa dipanggil Claude. Contohnya issue tracker, database, atau sistem monitoring.

Baca selengkapnya (2)

Server ditambahkan dengan claude mcp add. Ada dua transport yang akan Anda pakai. Untuk server jarak jauh, gunakan --transport http dan sebuah URL; dokumentasi merekomendasikan http untuk server remote dan menandai transport sse yang lebih lama sebagai deprecated. Untuk proses lokal, pakai stdio dan taruh perintah server itu setelah tanda dua strip: claude mcp add my-server -- my-command --some-flag. Semua yang ada setelah -- diteruskan apa adanya ke server, jadi flag miliknya tidak tertukar dengan flag Claude.

Kelola server dengan claude mcp list, claude mcp get, dan claude mcp remove. Di dalam sesi, /mcp menampilkan status tiap server dan memungkinkan Anda login, menyambung ulang, atau mengaktifkan dan menonaktifkannya. Untuk server remote yang butuh OAuth, claude mcp login memulai alur browser dari shell. Variabel environment untuk server stdio masuk ke --env, sedangkan header untuk server http masuk ke --header.

Scope mana yang cocok untuk MCP server, dan apa itu .mcp.json?

Scope dipilih dengan --scope (atau -s) dan menjawab dua pertanyaan: siapa yang melihat server itu, dan di mana ia disimpan. Local adalah default: server hanya dimuat di proyek saat ini dan tidak dibagikan. Project menyimpannya di file .mcp.json di root repositori, sehingga version control membagikannya ke semua yang meng-clone. User memuatnya di semua proyek Anda tetapi tidak membagikannya ke siapa pun.

Baca selengkapnya (2)

Bila nama server yang sama didefinisikan di beberapa tempat, local mengalahkan project, project mengalahkan user, lalu menyusul server dari plugin dan connector claude.ai. Seluruh entri dari sumber pemenang yang dipakai; field tidak digabung antar scope. Entri .mcp.json bisa membaca environment variable dengan sintaks dollar-kurung-kurawal VAR, opsional dengan nilai default setelah :-, di command, args, env, url, dan headers, sehingga file bersama tidak perlu menyimpan rahasia.

Karena file proyek bisa menjalankan proses di mesin Anda, Claude Code meminta persetujuan di sesi interaktif sebelum memakai server dari .mcp.json. claude mcp reset-project-choices menghapus jawaban itu. Catatannya ada pada pemakaian non-interaktif: proses claude -p tidak bisa menampilkan prompt, jadi ia memuat server project tanpa bertanya.

Bagaimana izin dan keamanan bekerja untuk tool MCP?

Setiap tool MCP bernama mcp__server__tool, dan aturan izin memakai nama itu. Aturan mcp__puppeteer cocok dengan semua tool dari server puppeteer, mcp__puppeteer__* cocok dengan wildcard, dan mcp__puppeteer__puppeteer_navigate hanya cocok dengan satu tool. Aturan dijalankan berurutan deny, ask, allow, dan kecocokan pertama menang, jadi deny di scope mana pun mengalahkan allow. Di mode Manual, tool tanpa aturan yang cocok akan menanyakan Anda.

Baca selengkapnya (2)

Dua pagar pengaman menjaga aturan yang luas tetap aman. Aturan allow hanya boleh memakai wildcard setelah awalan literal mcp__server__, jadi allow mcp__* dilewati dengan peringatan dan tidak menyetujui apa pun. Lalu aturan mcp__ yang memakai tanda kurung dilewati saat settings dimuat; untuk mencocokkan parameter sebuah tool MCP, berikan aturan deny lewat --disallowedTools. Deny mcp__* sah dan membuang semua tool MCP dari context Claude.

Sikap keamanan di dokumentasi singkat saja: pastikan Anda memercayai tiap server sebelum menghubungkannya, karena server yang mengambil konten eksternal dapat membuka Anda pada prompt injection. Hasil tool MCP adalah teks yang langsung masuk ke context Claude, jadi halaman web atau tiket yang jahat bisa mencoba mengarahkannya. Pilih server yang bisa Anda baca, batasi aturan allow pada tool tertentu, dan simpan rahasia di environment variable, bukan di file yang di-commit.

Cara situs ini melakukannya

Konfigurasi nyata di balik pelajaran ini

Kutipan dari repositori yang membangun dan men-deploy situs ini, apa adanya.

app/components/blogs/McpTransportsStdioVsHttp.tsx:8-24
const STDIO_CONFIG = `{
  "mcpServers": {
    "local-fs": {
      "command": "node",
      "args": ["./dist/server.js"]
    }
  }
}`;

const HTTP_CONFIG = `{
  "mcpServers": {
    "remote-api": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}`;

Repositori ini tidak punya .mcp.json sendiri, jadi ini adalah bentuk konfigurasi dari artikel situs tentang transport MCP. Kedua file memakai key mcpServers yang sama. Entri stdio menyebut command dan args-nya; entri http mengisi type dan url. Nama server, local-fs dan remote-api, menjadi bagian tengah setiap nama tool, misalnya mcp__remote-api__tool.

Yang sering rusak

Kesalahan yang benar-benar membuang waktu

  • Lupa tanda dua strip pada server stdio

    Tanpa --, flag yang ditujukan untuk server, seperti --port, dibaca sebagai opsi milik Claude. Tulis claude mcp add my-server -- my-command --port 3000. Jebakan kedua: --env menerima beberapa pasangan KEY=value, jadi nama server yang diletakkan tepat sesudahnya dibaca sebagai pasangan lain. Sisipkan --transport stdio di antaranya.

  • Aturan allow yang diam-diam tidak berfungsi

    Aturan allow mcp__* dilewati dengan peringatan, dan aturan mcp__ dengan tanda kurung dilewati saat dimuat. Sebut servernya dulu: mcp__github__get_* hanya mengizinkan tool get_ milik server itu. Jalankan claude doctor untuk melihat aturan yang dilewati.

  • Mengira scope akan digabung

    Jika server bernama docs ada di scope local dan project, entri local dipakai seluruhnya. Field-nya tidak digabung dengan entri project, jadi header yang hilang di salinan local tidak dilengkapi dari .mcp.json.

  • Variabel yang tidak diset menjadi teks literal

    Di .mcp.json, variabel yang tidak diset dan tanpa default memunculkan peringatan, dan konfigurasi dimuat dengan teks literal dollar-kurung-kurawal. Beri default setelah :- atau export variabelnya dulu. Di url dan headers remote, beberapa variabel kredensial sengaja dibaca kosong, sehingga file proyek tidak bisa membocorkannya.

  • File .mcp.json yang di-commit pada run tanpa pengawasan

    claude -p tidak menampilkan prompt persetujuan, jadi setiap server di .mcp.json sebuah repositori ikut terhubung. Sebelum menjalankannya di repo yang bukan buatan Anda, mulai dengan --bare atau pakai --strict-mcp-config bersama --mcp-config milik Anda, atau daftarkan servernya di disabledMcpjsonServers.

Tiga scope MCP
local (default)Hanya proyek iniTidak~/.claude.json
projectHanya proyek iniYa, lewat version control.mcp.json di root repo
userSemua proyek AndaTidak~/.claude.json
Coba sendiri

Lakukan di komputer Anda sendiri

Anda butuh Claude Code dan satu repositori git untuk latihan. Latihan ini menambah server, memeriksanya, lalu membatasi apa yang boleh dipanggil Claude. URL di bawah hanyalah placeholder, jadi ganti dengan server asli yang Anda percayai.

  1. Tambahkan server http dengan scope project, sehingga ditulis ke .mcp.json di repo.

    claude mcp add --transport http docs https://example.com/mcp --scope project

  2. Buka file yang ditulisnya dan lihat entrinya. Lalu daftar semua server dan baca satu server secara rinci.

    cat .mcp.json
claude mcp list
claude mcp get docs

  3. Tambahkan server stdio di scope local default. Perhatikan tanda dua strip sebelum perintah milik server.

    claude mcp add --env API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

  4. Jalankan Claude Code, setujui server project saat diminta, lalu jalankan /mcp untuk melihat status tiap server.

    claude
> /mcp

  5. Setujui di muka tool satu server dan blokir tool yang berisiko di .claude/settings.json. Deny mengalahkan allow apa pun urutannya.

    {
  "permissions": {
    "allow": ["mcp__docs__*"],
    "deny": ["mcp__airtable"]
  }
}
Kuis singkat

Tiga pertanyaan sebelum lanjut

Pilih jawaban untuk melihat kenapa benar atau salah. Tidak ada yang disimpan atau dinilai, jadi tebak saja dengan bebas.

  1. 1.Anda ingin setiap rekan yang meng-clone repo mendapat MCP server yang sama. Scope mana yang dipakai?
  2. 2.Apa fungsi tanda dua strip pada claude mcp add my-server -- my-command --port 3000?
  3. 3.Aturan mana yang menyetujui di muka semua tool dari server bernama puppeteer?
Pikirkan dulu

Jawab dalam hati, lalu cek

  1. 1.File .mcp.json Anda memakai environment variable untuk token, dan variabel itu tidak diset di mesin rekan. Apa yang mereka dapat?Lihat jawabannya

    Jawaban:Sebuah peringatan, dan konfigurasi dimuat dengan teks variabel literal sebagai ganti nilai, sehingga server kemungkinan besar gagal autentikasi. Beri default setelah :- bila masuk akal, atau dokumentasikan bahwa variabel itu harus di-export.

  2. 2.Mengapa aturan deny di user settings bisa memblokir tool yang diizinkan project settings?Lihat jawabannya

    Jawaban:Aturan dievaluasi berurutan deny, ask, allow, dan kecocokan pertama yang menentukan. Aturan deny dari scope mana pun diperiksa sebelum aturan allow, jadi tingkat spesifik dan urutan file tidak berpengaruh.

  3. 3.Mengapa MCP server yang mengambil halaman web lebih berisiko daripada yang hanya membaca file lokal buatan Anda?Lihat jawabannya

    Jawaban:Hasilnya adalah teks dari pihak lain yang langsung masuk ke context Claude. Teks itu bisa berisi instruksi untuk mengarahkan Claude, yaitu prompt injection. Dokumentasi menyarankan memercayai tiap server sebelum menghubungkannya.

Pelajari lebih dalam

Bahasan mendalam terkait di situs ini

Sumber

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

Pelajaran sebelumnyaCara Hemat Token Claude Code: Konteks, Compaction, dan ScopePelajaran berikutnyaClaude Code Headless: claude -p dengan Gerbang Lulus/Gagal