Claude Code Subagents + MCP: Batasi Akses Tool per Sub-Agent (2026)

tl;dr: Sub-agent di Claude Code otomatis mewarisi seluruh tool MCP yang aktif di percakapan utama — termasuk tool yang bisa menulis ke database produksi atau mengirim pesan keluar. Dokumentasi resmi Anthropic menyediakan dua rem: field tools sebagai daftar izin dan disallowedTools sebagai daftar larangan, keduanya ditulis di YAML frontmatter file sub-agent. Kuncinya ada di format penamaan mcp__namaserver__namatool yang sering salah ketik, plus pemilihan scope .mcp.json yang menentukan siapa saja yang kebagian server tersebut. Halaman ini membedah cara mengunci akses MCP per sub-agent, contoh konfigurasi lengkap, kesalahan yang paling sering bikin sub-agent gagal jalan, dan kapan pengaturan seketat itu justru mubazir.

Begitu satu server MCP tersambung, semua sub-agent yang kamu buat langsung punya akses ke tool di dalamnya tanpa kamu minta. Untuk sub-agent riset yang cuma perlu membaca kode, itu berarti sub-agent tersebut juga memegang kemampuan menulis ke sistem eksternal — masalah yang solusinya cuma butuh dua baris konfigurasi, mulai dari memahami kenapa pewarisan tool itu terjadi.

Kenapa Sub-Agent Otomatis Kebagian Semua Tool MCP

Menurut dokumentasi resmi Claude Code tentang sub-agent, tiap sub-agent berjalan di jendela konteks sendiri dengan system prompt, akses tool, dan izin yang terpisah dari percakapan utama. Yang sering luput: kalau field tools dikosongkan, sub-agent mewarisi seluruh tool yang tersedia di percakapan utama — tool bawaan maupun tool dari server MCP yang sedang tersambung.

Pewarisan itu bukan bug, melainkan default yang memang dirancang supaya sub-agent langsung berguna tanpa konfigurasi. Konsekuensinya baru terasa saat kamu menyambungkan server MCP yang punya kemampuan menulis: server database yang bisa menjalankan UPDATE, server issue tracker yang bisa menutup tiket, atau server pesan yang bisa mengirim notifikasi ke tim. Sub-agent bernama “peneliti-kode” yang niatnya cuma membaca berkas jadi ikut memegang semua kemampuan itu.

Dokumentasi Claude Code menyebut ada dua filter yang tetap berlaku sebelum daftar tool sampai ke sub-agent. Filter pertama mencopot tool tertentu dari setiap sub-agent walaupun kamu menuliskannya di field tools — di antaranya AskUserQuestion, EnterPlanMode, dan WaitForMcpServers. Filter kedua khusus sub-agent yang berjalan di latar belakang: sub-agent latar belakang tetap memegang seluruh tool MCP, tapi tool bawaannya dipangkas jadi daftar pendek seperti Read, Grep, Glob, Bash, dan Edit.

Perhatikan asimetrinya: tool bawaan dipangkas otomatis, tool MCP tidak. Justru tool MCP — yang menyentuh sistem di luar mesinmu — yang lolos dari pemangkasan otomatis. Itu sebabnya pembatasan manual jadi wajib, bukan opsional.

💡 Key Takeaway

Field tools kosong berarti sub-agent mewarisi semua tool, termasuk seluruh tool MCP dari percakapan utama.
Sub-agent latar belakang dipangkas tool bawaannya, tapi tidak dipangkas tool MCP-nya.
Pembatasan akses MCP per sub-agent harus ditulis manual — tidak ada default yang aman.

Format Penamaan Tool MCP yang Wajib Kamu Hafal

Supaya bisa memasukkan tool MCP ke daftar izin, kamu perlu nama lengkapnya, bukan nama singkat yang muncul di layar. Dokumentasi Claude Code untuk penyambungan tool lewat MCP menetapkan polanya:

mcp__<nama-server>__<nama-tool>

Dua garis bawah, bukan satu, di kedua pemisah. Untuk server bernama notion dengan tool search, nama lengkapnya mcp__notion__search. Kalau kamu ingin memberi akses ke seluruh tool dari satu server sekaligus, sebagian aturan izin menerima pola mcp__notion__* — tapi untuk field tools di sub-agent, menuliskan nama tool satu per satu jauh lebih aman karena kamu jadi tahu persis apa yang dipegang sub-agent tersebut.

Ada satu jebakan tambahan. Kalau server MCP-nya datang dari plugin, namanya berbeda total. Dokumentasi Claude Code menyebutkan bentuk lengkapnya mcp__plugin_<nama-plugin>_<nama-server>__<nama-tool> — jadi tool query dari server database-tools di plugin my-plugin dipanggil sebagai mcp__plugin_my-plugin_database-tools__query. Aturan izin yang ditulis memakai nama server polos, misalnya mcp__database-tools__*, tidak akan pernah cocok dengan server bawaan plugin. Kesalahan ini diam-diam berbahaya: kamu merasa sudah memasang pagar, padahal pagarnya tidak menempel pada apa pun.

Cara paling cepat memastikan nama yang benar: jalankan perintah /mcp di dalam sesi Claude Code untuk melihat daftar server yang tersambung beserta tool-nya, lalu salin nama persis dari situ. Mengarang nama dari ingatan adalah sumber kegagalan paling umum di tahap ini.

Contoh Nyata: Sub-Agent Riset dengan Satu Server MCP Saja

Anggap kamu punya dua server MCP tersambung — satu untuk dokumentasi internal, satu lagi untuk database produksi — dan kamu ingin sub-agent peneliti yang cuma boleh menyentuh dokumentasi. Langkah pertama, daftarkan server dengan scope yang tepat.

Untuk server yang perlu dipakai satu tim, Claude Code menyimpannya di berkas .mcp.json di root proyek lewat perintah dengan flag --scope project:

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

Berkas .mcp.json yang terbentuk berbentuk seperti berikut, dan bisa kamu masukkan ke version control supaya seluruh tim mendapat konfigurasi yang sama:

{
  "mcpServers": {
    "docs-internal": {
      "type": "http",
      "url": "https://mcp.contoh.com/mcp"
    }
  }
}

Langkah kedua, buat file sub-agent di .claude/agents/peneliti-docs.md. Bagian YAML frontmatter di atas garis tiga strip adalah tempat pagarnya dipasang:

---
name: peneliti-docs
description: Mencari jawaban di dokumentasi internal. Pakai saat butuh rujukan kebijakan atau spesifikasi produk.
tools: Read, Grep, Glob, mcp__docs-internal__search, mcp__docs-internal__fetch
model: haiku
---

Kamu adalah peneliti dokumentasi internal. Jawab hanya berdasarkan isi
dokumen yang kamu temukan. Sertakan nama berkas atau judul dokumen
sebagai rujukan di tiap jawaban. Jangan menebak isi dokumen yang tidak
kamu baca.

Dengan daftar itu, sub-agent peneliti-docs tidak lagi punya akses ke server database — bukan karena servernya dimatikan, melainkan karena namanya tidak ada di daftar izin. Kalau kamu lebih suka pendekatan sebaliknya, gunakan disallowedTools yang mewarisi semua tool kecuali yang kamu sebutkan:

---
name: analis-tanpa-tulis
description: Menganalisis data tanpa mengubah apa pun.
disallowedTools: Write, Edit, mcp__db-prod__execute
---

Pilih salah satu pola sesuai situasi. Daftar izin (tools) cocok saat kamu tahu persis apa yang dibutuhkan sub-agent — lebih ketat, dan tool baru yang tersambung belakangan tidak otomatis masuk. Daftar larangan (disallowedTools) cocok saat kebutuhan sub-agent luas dan yang perlu dijaga cuma beberapa tool berbahaya — lebih longgar, tapi tool MCP baru akan otomatis diwariskan. Untuk sesuatu yang menyentuh sistem produksi, daftar izin adalah pilihan yang lebih tepat.

Kalau kamu belum familier dengan struktur file sub-agent secara umum, langkah dasarnya sudah dibedah terpisah di panduan konfigurasi sub-agent Claude Code. Sementara untuk memahami apa itu server MCP dan cara kerjanya dari sisi protokol, penjelasan lengkapnya ada di pembedahan MCP Server dan alasan AI Agent membutuhkannya.

💡 Key Takeaway

Nama tool MCP memakai pola mcp__server__tool dengan dua garis bawah di tiap pemisah.
Server dari plugin memakai pola berbeda: mcp__plugin_<plugin>_<server>__<tool>.
Pakai tools (daftar izin) untuk sub-agent yang menyentuh sistem penting, disallowedTools untuk pembatasan ringan.

Scope Server MCP Menentukan Siapa yang Kebagian

Pembatasan di level sub-agent baru separuh cerita. Separuh lagi ada di scope tempat server MCP didaftarkan, karena scope menentukan di proyek mana server itu ikut termuat. Dokumentasi Claude Code mencatat tiga pilihan:

Local — default, tersimpan di ~/.claude.json, cuma termuat di proyek tempat kamu menambahkannya, dan tidak dibagi ke tim. Cocok untuk server percobaan atau server yang memakai kredensial pribadi.
Project — tersimpan di .mcp.json di root proyek dan ikut masuk version control, jadi seluruh tim mendapat server yang sama.
User — tersimpan di ~/.claude.json dan termuat di semua proyekmu. Praktis, tapi berarti server itu ikut hadir di proyek yang tidak membutuhkannya.

Ada catatan keamanan penting soal scope project. Claude Code meminta persetujuan lebih dulu sebelum memakai server dari .mcp.json di sesi interaktif. Tapi pada mode non-interaktif — misalnya claude -p, sesi lewat Agent SDK, atau sesi cloud — prompt persetujuan itu tidak bisa ditampilkan, sehingga server scope project dimuat tanpa bertanya. Artinya berkas .mcp.json yang di-commit ke repositori bersama efektif menjadi konfigurasi tepercaya di semua jalur otomatis. Perlakukan berkas itu seperti berkas kredensial: ditinjau tiap kali berubah, bukan dilewati begitu saja saat code review.

Ketegangan antara kemudahan dan risiko ini persis alasan pembatasan tool per sub-agent jadi penting. Server bisa saja tersedia luas di seluruh tim; yang membatasi dampaknya adalah daftar tool di tiap sub-agent.

Menggabungkan Batas Tool dengan Pilihan Model

Field model di frontmatter menerima nilai sonnet, opus, haiku, ID model lengkap, atau inherit. Menurut dokumentasi Claude Code, salah satu manfaat sub-agent memang mengendalikan biaya dengan mengarahkan tugas ke model yang lebih murah dan cepat.

Digabung dengan pembatasan tool, kombinasinya jadi masuk akal secara operasional. Sub-agent yang cuma boleh membaca dan memanggil satu-dua tool MCP pencarian tidak butuh model paling mahal — pekerjaannya mengambil dan meringkas, bukan menalar rancangan sistem. Sebaliknya, sub-agent yang memegang tool bermodal tulis lebih pas memakai model yang lebih kuat sekaligus daftar tool yang paling sempit, karena kesalahannya lebih mahal.

Pola pikirnya sama seperti membagi tugas ke beberapa agen di kerangka multi-agent lain — pertimbangan pemilihan kerangkanya sudah dibandingkan di ulasan framework multi-agent LangGraph, CrewAI, AutoGen, Claude, dan OpenClaw. Bedanya, di Claude Code pembagian itu ditulis sebagai berkas Markdown biasa, bukan kode orkestrasi.

Kesalahan yang Paling Sering Bikin Gagal

Empat masalah berikut muncul berulang saat menggabungkan sub-agent dengan MCP, dan semuanya punya gejala yang membingungkan.

Daftar tool tidak cocok dengan tool mana pun. Dokumentasi Claude Code menyebut kalau tidak ada satu pun entri di field tools yang resolve ke tool nyata, sub-agent gagal diluncurkan dengan galat yang menyebut entri bermasalah. Penyebab tersering: salah ketik jumlah garis bawah, atau nama server berubah setelah didaftar ulang.

Entri .mcp.json punya url tapi tidak punya type. Claude Code membaca entri tanpa type sebagai server stdio, lalu melewatkannya sambil melaporkan bahwa entri tersebut butuh "type": "http". Konfigurasi yang disalin dari dokumentasi klien lain sering kehilangan field ini. Perlu dicatat, field type juga menerima streamable-http sebagai alias dari http, sesuai nama transport di spesifikasi MCP.

Masih memakai transport SSE. Dokumentasi Claude Code menandai transport SSE sebagai deprecated dan menyarankan HTTP di tempat yang mendukungnya. Konfigurasi lama yang masih memakai --transport sse tetap jalan, tapi bukan jalur yang akan dirawat ke depan.

Deskripsi sub-agent kepanjangan. Claude memakai field description untuk memutuskan kapan mendelegasikan tugas, jadi deskripsi itu selalu berada di konteks. Claude Code menampilkan peringatan saat startup kalau gabungan deskripsi sub-agent buatanmu melewati 15.000 token. Solusinya bukan menghapus sub-agent, melainkan memindahkan detail dari description ke badan system prompt yang hanya termuat saat sub-agent tersebut berjalan.

💡 Key Takeaway

Scope project lewat .mcp.json dimuat tanpa prompt persetujuan di sesi non-interaktif — tinjau berkas itu seperti berkas kredensial.
Salah ketik nama tool bikin sub-agent gagal diluncurkan, bukan gagal diam-diam — galatnya menyebut entri yang bermasalah.
Deskripsi sub-agent ikut memakan konteks; pindahkan detail panjang ke system prompt.

Kapan Kamu Belum Perlu Mengunci Akses MCP

Pengaturan seketat ini punya ongkos: tiap tool MCP baru yang ingin dipakai sub-agent harus ditambahkan manual ke daftar izin. Dalam beberapa situasi ongkos itu tidak sepadan.

Kalau seluruh server MCP yang tersambung bersifat baca-saja — misalnya server dokumentasi publik atau server pencarian — dampak terburuk dari pewarisan tool cuma pemborosan token, bukan kerusakan data. Begitu pula kalau kamu bekerja sendirian di proyek pribadi tanpa server yang menyentuh sistem produksi: menulis daftar izin panjang untuk tiap sub-agent akan lebih banyak menghambat daripada melindungi.

Batas yang masuk akal: mulai mengunci begitu ada satu saja server MCP yang bisa mengubah sesuatu di luar mesinmu — menulis ke database, mengirim pesan, mengubah tiket, atau menyentuh repositori bersama. Sebelum titik itu, biarkan default berjalan dan fokus ke hal lain.

Untuk kebutuhan yang beda lagi, misalnya menjalankan agen yang tetap hidup di WhatsApp atau Telegram alih-alih di terminal pengembang, Claude Code bukan alat yang tepat — perbandingan situasinya sudah dibahas di ulasan Claude Code versus OpenClaw dan kapan memakai yang mana.

Pertanyaan yang Sering Ditanya

Apakah sub-agent Claude Code otomatis bisa memakai semua server MCP saya?

Ya, selama field tools di frontmatter dikosongkan. Dokumentasi Claude Code menyebut sub-agent mewarisi tool bawaan dan tool MCP yang tersedia di percakapan utama. Untuk membatasinya, tulis daftar tool yang diizinkan di field tools, atau daftar yang dilarang di disallowedTools.

Bagaimana format penulisan nama tool MCP di field tools?

Polanya mcp__namaserver__namatool dengan dua garis bawah di tiap pemisah, contohnya mcp__notion__search. Untuk server yang datang dari plugin, polanya lebih panjang: mcp__plugin_namaplugin_namaserver__namatool. Cara paling aman mendapatkan nama yang benar adalah menyalinnya dari keluaran perintah /mcp di dalam sesi.

Kenapa sub-agent saya gagal jalan setelah field tools diisi?

Penyebab tersering adalah tidak ada satu pun entri di daftar yang cocok dengan tool nyata — biasanya karena salah ketik atau nama server berubah. Claude Code menolak meluncurkan sub-agent yang berakhir tanpa tool sama sekali dan menyebutkan entri yang bermasalah di pesan galatnya.

Apa bedanya menyimpan server MCP di .mcp.json dan di ~/.claude.json?

Berkas .mcp.json di root proyek adalah scope project: ikut version control dan dibagikan ke seluruh tim. Sedangkan ~/.claude.json menampung scope local (hanya proyek tertentu, pribadi) dan scope user (semua proyekmu, pribadi). Untuk server berkredensial sensitif, scope local lebih aman karena tidak ikut terbawa ke repositori.

Apakah sub-agent yang berjalan di latar belakang lebih aman otomatis?

Tidak untuk urusan MCP. Claude Code memangkas tool bawaan sub-agent latar belakang jadi daftar pendek, tapi seluruh tool MCP tetap dipertahankan. Justru tool MCP yang menyentuh sistem eksternal, jadi pembatasan manual tetap dibutuhkan.

Apakah perlu bisa coding untuk mengatur pembatasan ini?

Tidak. Berkas sub-agent adalah dokumen Markdown biasa dengan blok YAML di bagian atas, dan pendaftaran server MCP dilakukan lewat satu perintah terminal. Kemampuan pemrograman baru dibutuhkan kalau kamu ingin membangun server MCP sendiri dari nol.

Disclosure: Komunitech menyelenggarakan workshop dan layanan pengerjaan AI Agent, termasuk yang memanfaatkan integrasi tools lewat MCP, sehingga punya kepentingan komersial atas topik yang dibahas di halaman ini.

Disclaimer: seluruh detail teknis mengacu pada dokumentasi resmi Claude Code (code.claude.com) per 2 September 2026. Beberapa perilaku yang disebutkan terikat versi tertentu — misalnya pelaporan galat konfigurasi MCP yang berubah sejak v2.1.202 dan penghapusan wizard interaktif /agents sejak v2.1.198 — sehingga hasilnya bisa berbeda pada versi yang kamu pakai. Periksa dokumentasi versi terkini sebelum menerapkannya di lingkungan kerja.