Panduan Claude Code MCP Server: integrasi SaaS yang aman untuk tim

MCP Server membuat Claude Code bisa membaca GitHub issue, mencari dokumen tim, terhubung ke Notion, Google Drive, CRM, atau API internal. Ini sangat berguna, tetapi juga menambah risiko. Scope yang terlalu luas, token yang masuk ke .mcp.json, OAuth yang disetujui tanpa dicek, npx yang gagal di Windows, atau output besar yang memicu 10,000 token warning bisa membuat workflow sulit dipakai.

Panduan ini fokus pada penggunaan nyata: mulai dari scope kecil, pisahkan secrets, verifikasi dengan /mcp, dan buat konfigurasi yang bisa dipahami tim.

Apa yang berubah dengan MCP

MCP berarti Model Context Protocol. Ini standar untuk menghubungkan AI client dengan tool dan sumber data eksternal. Claude Code bertindak sebagai MCP client dan memanggil tool dari MCP server.

Tanpa MCP, Claude Code terutama melihat repository dan konteks yang kamu berikan. Dengan MCP, ia bisa melihat dokumen, ticket, metrik produk, data pelanggan, atau SaaS internal. Jadi pertanyaan pertama bukan “server apa yang keren”, tetapi “data apa yang boleh dilihat proyek ini, dengan izin apa, dan siapa yang mengecek hasilnya”.

Untuk batas izin, baca juga panduan permission Claude Code dan praktik keamanan Claude Code.

Transport	Cocok untuk	Catatan
stdio	Server lokal dengan npx, Python, atau binary internal	Di Windows sering perlu cmd /c npx
http	MCP remote, SaaS, OAuth	Cek workspace dan scope OAuth
sse	Kompatibilitas server lama	Untuk integrasi baru biasanya pilih HTTP

Pilih scope lebih dulu

claude mcp add mendukung --scope local, --scope project, dan --scope user.

scope	Arti	Pakai untuk
local	Hanya proyek saat ini di mesin ini	Tes pribadi, proyek klien, koneksi dengan secret
project	Disimpan di .mcp.json dan dibagikan lewat repo	Definisi server untuk tim
user	Tersedia di semua proyek Claude Code	Tool pribadi yang benar-benar umum

Mulai dengan local. Gunakan project jika tim perlu berbagi nama dan command. Hati-hati dengan user, terutama jika satu laptop dipakai untuk banyak klien.

claude mcp add --scope local --transport stdio repo-files -- npx -y @modelcontextprotocol/server-filesystem ./docs

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

claude mcp add --scope user --transport http personal-notes https://mcp.example.com/mcp

Project server membutuhkan approval. Itu bukan gangguan, tetapi mekanisme untuk memastikan repository memang percaya server tersebut.

Windows: gunakan cmd /c npx

Di Windows, npx bisa berjalan di PowerShell tetapi gagal saat Claude Code menjalankan MCP stdio server. Pola yang lebih aman adalah cmd /c npx.

claude mcp add --scope local --transport stdio repo-files -- cmd /c npx -y @modelcontextprotocol/server-filesystem "C:\Users\masa\work\claudecode-lab\docs"

Di .mcp.json, pisahkan command dan args.

{
  "mcpServers": {
    "repo-files": {
      "type": "stdio",
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\masa\\work\\claudecode-lab\\docs"
      ],
      "env": {}
    }
  }
}

Jangan langsung memberi akses ke seluruh home directory. Mulai dari docs, reports, atau repository uji. Jika server bisa menulis, gabungkan dengan panduan Claude Code hooks untuk menahan aksi berbahaya.

Remote MCP, OAuth, dan /mcp

Untuk Notion, Google Drive, GitHub, atau CRM, HTTP biasanya paling jelas.

claude mcp add --scope local --transport http notion https://mcp.notion.com/mcp

Setelah itu, jalankan /mcp di Claude Code. Di sana kamu melihat status koneksi, OAuth, dan tools yang tersedia.

/mcp

# Cek:
# - server connected
# - OAuth authenticated
# - workspace yang disetujui
# - tools sesuai kebutuhan
# - tidak ada write/admin jika hanya butuh read-only

Untuk API internal dengan bearer token, gunakan header tetapi jangan simpan token di file bersama.

claude mcp add --scope local --transport http crm-readonly https://mcp.example.com/readonly \
  --header "Authorization: Bearer $CRM_READONLY_TOKEN"

.mcp.json untuk tim harus berisi struktur koneksi, bukan secrets.

{
  "mcpServers": {
    "customer-docs": {
      "type": "http",
      "url": "https://mcp.example.com/customer-docs"
    },
    "github-readonly": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@example/github-readonly-mcp"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_READONLY_TOKEN}"
      }
    }
  }
}

Use case 1: GitHub dan Notion untuk triage issue

Nilai tercepat muncul saat kamu mengurangi pindah-pindah antara issue, PR, dan spesifikasi. Claude Code bisa membaca issue lewat GitHub MCP, mencari requirement di Notion atau docs, lalu merangkum risiko sebelum mengedit.

Baca GitHub issue #248 dan cari requirement terkait di dokumentasi produk.
Jangan ubah kode dulu.
Kembalikan:
1. File yang mungkin terkait
2. Requirement yang jelas
3. Pertanyaan yang masih terbuka
4. Rencana implementasi paling kecil dan aman

Instruksi “jangan ubah kode dulu” penting. MCP memberi lebih banyak konteks, tetapi juga bisa membuat keputusan salah terasa meyakinkan.

Use case 2: Google Drive untuk draft proposal

Dalam konsultasi, training, atau implementasi, meeting notes dan proposal lama sering tersebar di Drive. MCP read-only bisa membantu membuat draft proposal.

Cari folder "2026-05 Customer A".
Buat outline proposal:
1. Lima masalah pelanggan
2. Scope implementasi yang mungkin
3. Hal yang perlu dikonfirmasi
4. Tiga paket: training, implementation support, operations support

Samarkan nama, email, dan nilai kontrak persis.

Desain aman: folder terbatas, read-only, dan review manusia sebelum dikirim.

Use case 3: metrik read-only

MCP juga bisa membaca metrik produk atau analytics. Jangan berikan permission tulis production untuk analisis. Endpoint read-only cukup.

claude mcp add --scope local --transport http product-metrics https://mcp.example.com/readonly-metrics \
  --header "Authorization: Bearer $METRICS_READONLY_TOKEN"

Tinjau sumber traffic, PV per artikel, dan conversion clicks selama 14 hari terakhir.
Kelompokkan halaman berdasarkan topik.
Rekomendasikan lima tema artikel berikutnya dengan metrik pendukung.
Sertakan bagian data yang lemah atau noisy.

Ini dekat dengan monetisasi karena konten menjadi feedback loop, bukan sekadar tebak tema.

10,000 token warning

Jika MCP tool mengembalikan terlalu banyak data, Claude Code bisa menampilkan 10,000 token warning. Ini sering terjadi saat pencarian mengembalikan full body, daftar issue terlalu panjang, full HTML, atau query tanpa limit.

Pertama, kecilkan output.

Kembalikan maksimal 10 hasil.
Untuk setiap hasil, tampilkan title, URL, updated date, dan alasan cocok.
Jangan tampilkan full body sampai saya meminta item tertentu.

Untuk analisis sekali jalan:

MAX_MCP_OUTPUT_TOKENS=50000 claude

$env:MAX_MCP_OUTPUT_TOKENS = "50000"
claude

Jika ini dibutuhkan setiap hari, perbaiki server dengan pagination, filter, dan summary.

Kesalahan umum

Pertama, secrets di .mcp.json. Konfigurasi project dibagikan; token harus lewat environment, OAuth, atau secret manager.

Kedua, memakai --scope user karena praktis. Integrasi klien bisa muncul di proyek lain.

Ketiga, menganggap dokumen remote sebagai perintah. Konten dari MCP adalah data, bukan instruksi.

Keempat, tidak mengecek /mcp setelah OAuth. Login sukses tidak berarti workspace benar.

Kelima, workflow bergantung pada response besar. Workflow stabil memakai filter, ringkasan, dan detail saat diminta.

Diagnosis

claude mcp list
claude mcp get repo-files

Di Claude Code:

/mcp

Reset project approval:

claude mcp reset-project-choices

Smoke test:

Verifikasi hanya koneksi repo-files MCP.
Tampilkan maksimal 10 nama file di folder yang diizinkan.
Jangan baca isi file dan jangan ubah apa pun.

Monetisasi: jual workflow yang aman

MCP dekat dengan pendapatan karena menghubungkan Claude Code ke sistem nyata tim. Tetapi “saya pasang MCP Server” kurang kuat. Lebih kuat: “saya menghubungkan GitHub, Notion, Google Drive, dan SaaS internal secara aman agar tim bisa memakai Claude Code setiap minggu”.

• Produk murah: template .mcp.json dan checklist keamanan
• Layanan tim: review GitHub, Notion, Drive, dan permission
• Implementasi premium: scope, OAuth, hooks, monitoring, dan training

Mulai dari filesystem di folder uji. Untuk tim, pilih satu SaaS read-only dan satu .mcp.json project-scoped. Lalu hubungkan dengan Claude Code Harness Engineering.

Artikel ini mengikuti dokumentasi resmi Claude Code tentang claude mcp add, scope, .mcp.json, /mcp, OAuth, project server approval, dan MAX_MCP_OUTPUT_TOKENS. Prinsipnya sederhana: scope kecil, read-only dulu, tidak ada secret di file bersama, dan verifikasi sebelum dipakai.