Kontrol akses server MCP untuk organisasi Anda

Batasi server MCP mana yang dapat ditambahkan atau dihubungkan pengguna dengan file konfigurasi yang dikelola, daftar izin, dan daftar penolakan.

Secara default, siapa pun yang menjalankan Claude Code dapat menghubungkan server MCP apa pun yang mereka pilih. Anthropic meninjau konektor terhadap kriteria pendaftarannya sebelum menambahkannya ke Direktori Anthropic, tetapi tidak melakukan audit keamanan atau mengelola server MCP apa pun. Sebagai administrator, Anda dapat membatasi server mana yang berjalan di organisasi Anda, mulai dari menerapkan set yang disetujui tetap hingga menonaktifkan MCP sepenuhnya.

Halaman ini mencakup cara untuk:

• Memilih pola yang sesuai dengan tingkat kontrol yang Anda butuhkan
• Menerapkan set server tetap dengan managed-mcp.json, termasuk cara menonaktifkan MCP sepenuhnya
• Mengontrol server dengan daftar izin dan daftar penolakan
• Memberitahu pengguna apa yang diharapkan ketika pembatasan memblokir server
• Memantau server mana yang benar-benar digunakan organisasi Anda

Pilih pola

Claude Code mendukung berbagai tingkat pembatasan. Setiap pola menggunakan satu atau kedua mekanisme yang dibahas di bawah: managed-mcp.json untuk menerapkan set tetap, dan allowedMcpServers/deniedMcpServers untuk memfilter apa yang dikonfigurasi pengguna.

Kontrol eksklusif dengan managed-mcp.json

Jika Anda menerapkan file managed-mcp.json, Claude Code hanya memuat server yang didefinisikan file tersebut. Pengguna tidak dapat menambah, memodifikasi, atau menggunakan server MCP lain apa pun, termasuk server yang disediakan plugin. File juga menekan konektor claude.ai kecuali Anda mengizinkannya bersama set yang dikelola.

Dua pengaturan lainnya dapat memfilter set yang dikelola lebih lanjut:

• allowedMcpServers dan deniedMcpServers juga berlaku untuk server yang dikelola, jadi server yang dikelola yang tidak melewati mereka tidak akan dimuat.
• deniedMcpServers pengguna sendiri digabungkan dari pengaturan mereka, jadi pengguna dapat memblokir server yang dikelola untuk diri mereka sendiri.

Lihat Bagaimana server dievaluasi untuk urutan pemeriksaan lengkap.

managed-mcp.json adalah file mandiri, jadi tidak dapat dikirimkan melalui pengaturan yang dikelola server. Proses apa pun yang dapat menulis ke jalur sistem dengan hak istimewa administrator dapat menerapkannya. Dalam skala besar, itu biasanya melalui alat manajemen perangkat, seperti Jamf atau profil konfigurasi di macOS, Group Policy atau Intune di Windows, atau manajemen armada pilihan Anda di Linux. Claude Code mencari file di salah satu jalur berikut:

File menggunakan format yang sama dengan file proyek .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.example.com"
      }
    }
  }
}

Autentikasi dengan kredensial per pengguna

Pengguna apa pun di mesin dapat membaca file ini, jadi jangan simpan kunci API atau kredensial lain dalam blok env. Teruskan kredensial per pengguna dengan salah satu dari ini:

• Ekspansi ${VAR} untuk membaca rahasia dari lingkungan setiap pengguna.
• OAuth atau header per pengguna sehingga setiap pengguna mengautentikasi sebagai diri mereka sendiri.
• headersHelper untuk menghasilkan kredensial pada waktu koneksi.

Validasi konfigurasi

Untuk mengonfirmasi file berlaku, jalankan dua pemeriksaan pada mesin yang dikelola:

1. claude mcp list menampilkan hanya server di managed-mcp.json. Jika server pengguna sendiri masih muncul, file tidak dibaca; periksa jalur dan izin.
2. claude mcp add --transport http test https://example.com/mcp gagal dengan Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers. URL tidak perlu menjadi server nyata, karena pemeriksaan kebijakan menolak perintah sebelum apa pun dihubungi.

Nonaktifkan MCP sepenuhnya

Terapkan managed-mcp.json yang berisi peta server kosong untuk memblokir setiap server MCP:

{
  "mcpServers": {}
}

Pengguna tidak melihat server MCP apa pun di /mcp, dan claude mcp add gagal dengan kesalahan kebijakan perusahaan di atas. Server yang dikonfigurasi pengguna sebelumnya berhenti dimuat saat mereka memulai sesi berikutnya, tanpa peringatan bahwa kebijakan adalah alasannya.

Izinkan konektor claude.ai bersama set yang dikelola

Menerapkan managed-mcp.json menekan konektor claude.ai secara default, termasuk konektor yang dikonfigurasi administrator untuk organisasi di konsol admin claude.ai. Untuk memuat konektor tersebut bersama server di managed-mcp.json, atur "allowAllClaudeAiMcps": true dalam sumber pengaturan yang dikelola. Memerlukan Claude Code v2.1.149 atau lebih baru.

Dengan pengaturan diaktifkan, Claude Code memuat konektor claude.ai yang sama yang akan dimuat jika managed-mcp.json tidak diterapkan. Daftar izin dan daftar penolakan masih berlaku untuk konektor tersebut, jadi Anda dapat memblokir yang spesifik dengan deniedMcpServers. Pengaturan hanya mempengaruhi konektor claude.ai; server yang disediakan plugin tetap ditekan.

Claude Code membaca pengaturan ini hanya dari tingkat kebijakan yang dikendalikan admin: pengaturan yang dikelola server, kunci plist yang diterapkan MDM atau kunci registri HKLM, atau file managed-settings.json sistem. Menempatkannya dalam pengaturan pengguna atau proyek tidak berpengaruh, jadi pengguna tidak dapat mengaktifkan kembali konektor yang kontrol eksklusif tekan.

Kontrol berbasis kebijakan dengan daftar izin dan daftar penolakan

Daftar izin dan daftar penolakan memfilter server mana yang dikonfigurasi yang diizinkan untuk dimuat. Mereka bukan registri: server masih harus ditambahkan oleh pengguna, plugin, atau managed-mcp.json sebelum daftar izin atau daftar penolakan berlaku padanya. Untuk menerapkan server kepada pengguna, gunakan managed-mcp.json.

Untuk membuat daftar izin berwenang, atur allowedMcpServers dan allowManagedMcpServersOnly: true bersama-sama dalam sumber pengaturan yang dikelola, seperti pengaturan yang dikelola server atau file managed-settings.json yang diterapkan. Batasi daftar izin ke pengaturan yang dikelola saja menunjukkan konfigurasi. Tanpa allowManagedMcpServersOnly, daftar izin dari setiap sumber pengaturan digabungkan, termasuk ~/.claude/settings.json pengguna sendiri, jadi pengguna dapat memperluas apa yang diizinkan daftar izin Anda. Daftar penolakan digabungkan dari setiap sumber terlepas dari itu.

Cocokkan server berdasarkan URL, perintah, atau nama

allowedMcpServers dan deniedMcpServers adalah daftar entri. Setiap entri adalah objek dengan satu kunci yang mengidentifikasi server berdasarkan URL, perintah, atau nama mereka:

Membiarkan allowedMcpServers tidak diatur berbeda dari menetapkannya ke array kosong:

Validasi serverName berbeda antara dua daftar:

• {/* min-version: 2.1.182 */}Dalam deniedMcpServers, serverName menerima string non-kosong apa pun, jadi Anda dapat memblokir konektor claude.ai berdasarkan nama tampilan mereka. Misalnya, { "serverName": "claude.ai Slack" } memblokir konektor Slack. Lebih suka entri serverUrl ketika Anda memerlukan penolakan yang kuat terhadap penggantian nama, atau ketika nama konektor bertabrakan dan mendapatkan akhiran (N).
• Dalam allowedMcpServers, serverName terbatas pada huruf, angka, tanda hubung, dan garis bawah. Gunakan serverUrl untuk daftar izin konektor claude.ai.

Untuk mematikan semua konektor claude.ai, lihat disableClaudeAiConnectors.

Bagaimana server dievaluasi

Sebelum memuat server, termasuk yang dari managed-mcp.json, Claude Code menjalankan tiga pemeriksaan secara berurutan:

1. Gabungkan daftarnya. Entri daftar izin dan daftar penolakan dari setiap sumber pengaturan digabungkan menjadi satu daftar izin dan satu daftar penolakan. Ketika allowManagedMcpServersOnly adalah true, hanya daftar izin yang dikelola yang disimpan; daftar penolakan selalu digabungkan dari setiap sumber.
2. Periksa daftar penolakan. Server yang cocok dengan entri daftar penolakan apa pun, berdasarkan URL, perintah, atau nama, diblokir. Tidak ada yang mengganti kecocokan daftar penolakan.
3. Periksa daftar izin. Jika allowedMcpServers tidak diatur di mana pun, setiap server yang melewati daftar penolakan dimuat. Jika diatur, apa yang harus cocok dengan server tergantung pada jenisnya, ditunjukkan dalam tabel di bawah.

Dua aturan pencocokan berlaku dalam pemeriksaan tersebut:

• Perintah cocok dengan tepat. Setiap argumen, dalam urutan. ["npx", "-y", "server"] tidak cocok dengan ["npx", "server"] atau ["npx", "-y", "server", "--flag"].
• URL mendukung wildcard * di mana pun dalam pola, termasuk skema. Pencocokan nama host tidak peka huruf besar-kecil dan mengabaikan titik FQDN yang tertinggal, jadi https://Mcp.Example.com/* cocok dengan https://mcp.example.com/api. Jalur tetap peka huruf besar-kecil.

Contoh konfigurasi

Konfigurasi di bawah menyiapkan daftar izin keras dengan daftar penolakan. Baris yang disorot mengubah cara sisa daftar dievaluasi, dan callout setelah blok menjelaskan masing-masing:

{
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://mcp.sentry.dev/*" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },
    { "serverUrl": "https://mcp.example.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverCommand": ["npx", "-y", "unapproved-package"] },
    { "serverUrl": "https://*.untrusted.example.com/*" }
  ]
}

• Baris 3: entri serverUrl pertama. Setelah satu ada, setiap server jarak jauh harus cocok dengan pola URL, jadi pengguna tidak dapat mendapatkan server jarak jauh yang tidak terdaftar dengan memberikannya nama yang diizinkan.
• Baris 5: entri serverCommand pertama. Efek yang sama untuk server stdio, jadi setiap server lokal harus cocok dengan perintah yang terdaftar dengan tepat.
• Baris 11: entri serverName dalam daftar penolakan. Entri daftar penolakan selalu berlaku, jadi server apa pun yang bernama dangerous-server diblokir terlepas dari URL atau perintahnya.

Entri serverName dalam daftar izin ini tidak akan pernah cocok dengan apa pun, karena kedua jenis transportasi sudah memiliki entri yang lebih ketat.

Accordion di bawah menjelaskan cara server dievaluasi terhadap kombinasi daftar izin dan daftar penolakan lainnya.

{
"allowedMcpServers": [
{ "serverUrl": "https://mcp.example.com/*" },
{ "serverUrl": "https://*.internal.example.com/*" }
]
}

{
"allowedMcpServers": [
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}

{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}

{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverName": "internal-tool" }
]
}

{
"allowedMcpServers": [
{ "serverUrl": "https://*.example.com/*" }
],
"deniedMcpServers": [
{ "serverUrl": "https://staging.example.com/*" }
]
}

Batasi daftar izin ke pengaturan yang dikelola saja

Untuk membuat daftar izin yang dikelola satu-satunya yang berlaku, atur allowManagedMcpServersOnly dalam file pengaturan yang dikelola:

{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ]
}

Ketika allowManagedMcpServersOnly adalah true, daftar izin dari pengaturan pengguna, proyek, dan lokal diabaikan. Daftar penolakan masih digabungkan dari semua sumber, jadi pengguna selalu dapat memblokir server untuk diri mereka sendiri.

Bagaimana pembatasan muncul kepada pengguna

Ketika pembatasan memblokir server, pengguna melihat kesalahan dari claude mcp add atau server berhenti dimuat secara diam-diam. Gunakan tabel ini untuk mengenali laporan tersebut dan untuk memberitahu pengguna apa yang diharapkan sebelum Anda meluncurkan perubahan:

Dalam kasus terakhir, pengguna tidak mendapat sinyal bahwa kebijakan adalah alasan server mereka menghilang, jadi beri tahu pengguna yang terpengaruh server mana yang diblokir saat Anda meluncurkan pembatasan baru.

Pantau penggunaan MCP

Ketika ekspor OpenTelemetry dikonfigurasi, Claude Code dapat merekam server MCP dan alat mana yang digunakan pengguna. Atur OTEL_LOG_TOOL_DETAILS=1 untuk menyertakan nama server dan alat MCP dalam acara alat, kemudian agregasikan di kolektor Anda untuk melihat server mana yang benar-benar dihubungkan pengguna Anda. Lihat Monitoring untuk menyiapkan pengekspor dan untuk skema acara lengkap.

Ringkasan konfigurasi

Setiap file dan pengaturan yang dibahas halaman ini, apa yang dikontrolnya, dan cara mengirimkannya:

Sumber daya terkait

• Tentukan apa yang akan diterapkan: pembatasan MCP bersama dengan aturan izin, sandboxing, dan kontrol admin lainnya
• Hubungkan Claude Code ke alat melalui MCP: referensi MCP lengkap, termasuk transportasi, cakupan, dan autentikasi
• Pengaturan: hierarki pengaturan dan bagaimana pengaturan yang dikelola memiliki prioritas
• Pengaturan yang dikelola server: kirimkan allowedMcpServers dan deniedMcpServers dari konsol admin Claude.ai
• Keamanan: model ancaman yang dilindungi kontrol ini
• Panduan Administrator Perusahaan Claude: SSO, SCIM, manajemen kursi, dan playbook peluncuran