SpyBara
Go Premium

mcp-quickstart.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 215 additions and 249 deletions.

2026
Thu 1 23:59 Thu 15 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Wed 28 23:57 Fri 30 23:01

Terhubung ke server MCP

Tambahkan server MCP ke Claude Code, verifikasi koneksi, dan temukan konfigurasi di disk.

Model Context Protocol (MCP) memungkinkan Claude Code menggunakan alat di luar set bawaan, seperti mencari pelacak masalah, menanyakan database, atau mengontrol browser web. Alat-alat ini berasal dari server MCP, yang berjalan di mesin Anda atau sebagai layanan yang dihosting.

Panduan ini memandu Anda melalui koneksi satu server MCP end-to-end dengan CLI Claude Code. Pada akhirnya, Anda akan memiliki server yang terhubung dan merespons, mengetahui di mana konfigurasinya berada di disk, dan mengetahui cara memperbaiki kesalahan koneksi yang paling umum.

[!NOTE]

Anda juga dapat menambahkan server MCP dari permukaan lain, termasuk aplikasi desktop, VS Code, dan web. Lihat Terhubung dari permukaan lain.

Untuk setiap cara menghubungkan dan mengonfigurasi server MCP di Claude Code, lihat referensi MCP.

Sebelum Anda mulai

Pastikan Anda memiliki:

  • Claude Code terinstal dan terauthentikasi
  • Terminal terbuka di direktori proyek. Direktori apa pun berfungsi, termasuk yang kosong.

Tambahkan dan verifikasi server

Contoh di bawah terhubung ke server MCP dokumentasi Claude Code, server yang dihosting dengan pencarian teks lengkap di atas dokumen Claude Code. Ini tidak memerlukan autentikasi atau konfigurasi khusus apa pun, jadi berfungsi dengan baik sebagai server pertama untuk menguji alur pengaturan.

Langkah-langkahnya sama untuk server apa pun: tambahkan, periksa status koneksi, kemudian gunakan dalam sesi, dengan langkah pembersihan opsional di akhir. Beberapa server menambahkan langkah, seperti masuk browser, ditampilkan di Contoh server MCP tambahan. Untuk lebih banyak server untuk terhubung, telusuri Direktori Anthropic.

1. Tambahkan server MCP

Daftarkan server dengan Claude Code. Jalankan ini di terminal Anda, bukan di dalam sesi claude: Anda mengonfigurasi server sebelum memulai percakapan.

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Bagian-bagian dari perintah:

  • claude mcp add: mendaftarkan server dengan Claude Code.
  • --transport http: server dihosting di URL daripada berjalan sebagai proses lokal.
  • claude-code-docs: nama yang Anda buat. Memanggil server yang sama docs akan berfungsi identik. Claude Code menggunakan nama apa pun yang Anda pilih untuk memberi label alat server di output Claude dan untuk merujuk ke server dalam perintah seperti claude mcp remove.
  • https://code.claude.com/docs/mcp: URL tempat server dihosting.

Perintah mencetak konfirmasi seperti Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config, diikuti oleh baris File modified: yang menunjukkan file konfigurasi yang ditulisnya. Bagian local config berarti server terdaftar untuk Anda, dalam proyek ini: jika Anda memulai Claude Code di proyek yang berbeda, server ini tidak aktif di sana. Untuk mendaftarkan server sekali untuk semua proyek Anda, tambahkan di cakupan pengguna, tercakup dalam Ubah cakupan server.

2. Periksa status koneksi

Konfirmasi server muncul dalam daftar server Anda dan periksa statusnya:

claude mcp list

Server muncul dengan indikator status:

Status Arti
✔ Connected Siap digunakan. Ini adalah apa yang seharusnya Anda lihat untuk claude-code-docs
! Connected · tools fetch failed Server terhubung tetapi tidak dapat membuat daftar alatnya. Jalankan claude mcp get <name> untuk detail kesalahan
! Needs authentication Server dapat dijangkau tetapi memerlukan masuk browser, atau token yang diteruskan dengan --header. Lihat Terhubung ke server yang memerlukan masuk
✘ Failed to connect Server tidak merespons. Lihat Troubleshooting
✘ Connection error Upaya koneksi melempar kesalahan. Lihat Troubleshooting
⏸ Pending approval (run `claude` to approve) Server yang dibatasi proyek yang belum Anda setujui. Lihat Edit .mcp.json secara langsung
⊘ Disabled for this project (re-enable via /mcp) Server yang dimatikan untuk proyek ini oleh daftar disabledMcpServers proyek. Lihat Nonaktifkan server tanpa menghapusnya

Beberapa konsol Windows warisan, seperti konsol default di Windows 10, tidak mendukung merek Unicode ini dan menampilkan √ dan × sebagai pengganti ✔ dan ✘.

3. Gunakan server

Mulai sesi dan minta Claude menggunakan server baru berdasarkan nama:

claude

Use the claude-code-docs server to look up what MCP_TIMEOUT does

[!NOTE]

Anda biasanya tidak perlu menyebutkan server dalam prompt Anda, karena Claude memilih alat yang relevan dengan sendirinya. Menyebutkannya di sini menjamin demonstrasi melalui server baru daripada alat lain, seperti web fetch, yang dapat menjawab pertanyaan yang sama.

Jika Claude Code meminta izin pertama kali Claude memanggil server, setujui. Panggilan alat dalam output Claude diberi label dengan nama server, yang merupakan cara Anda mengonfirmasi jawaban berasal dari server MCP daripada pengetahuan bawaan Claude.

4. Hapus server

Langkah ini bersifat opsional. Ketika Anda selesai bereksperimen, Anda dapat menghapus server:

claude mcp remove claude-code-docs

Perintah mengonfirmasi dengan Removed MCP server "claude-code-docs" from local config dan baris File modified: yang menunjukkan file yang diperbarui.

[!NOTE]

Setiap server yang terhubung membutuhkan beberapa ruang di jendela konteks Claude karena nama alat dan instruksi server dimuat ke dalam setiap sesi. Menghapus server yang tidak lagi Anda gunakan membuat ruang itu tetap bebas.

Tempat server disimpan

Perintah claude mcp add menulis detail server ke file konfigurasi. Secara default, perintah ini mendaftarkan server pada cakupan local: pribadi untuk Anda, aktif hanya di proyek saat ini. Berikan --scope user untuk mendaftarkannya sekali untuk semua proyek Anda, atau --scope project untuk membagikannya dengan rekan kerja. Ubah cakupan server menjelaskan keduanya.

[!NOTE]

claude mcp add bekerja sama di setiap shell, termasuk PowerShell dan Command Prompt. Di dalam sesi claude, gunakan perintah /mcp untuk memeriksa dan mengelola server yang telah Anda tambahkan.

Ada cara lain untuk menambahkan server, masing-masing dengan bagiannya sendiri:

Temukan konfigurasi Anda di disk

Perintah claude mcp add menulis server ke salah satu dari tiga cakupan, disimpan di dua file, tergantung pada flag --scope. Anda tidak perlu mengedit file ini secara langsung, tetapi mengetahui di mana file ini berada membantu dengan debugging dan kontrol versi.

Cakupan File Tersedia untuk
local ~/.claude.json, di bawah entri untuk proyek ini Hanya Anda, hanya proyek ini. Default
project .mcp.json di root proyek Anda Semua orang yang mengkloning proyek
user ~/.claude.json, di bawah kunci mcpServers tingkat atas Hanya Anda, semua proyek

Di Windows, ~/.claude.json diselesaikan menjadi %USERPROFILE%\.claude.json, biasanya C:\Users\YourName\.claude.json. Jika Anda telah menetapkan CLAUDE_CONFIG_DIR, Claude Code membaca .claude.json dari dalam direktori tersebut sebagai gantinya.

Jalankan claude mcp get claude-code-docs untuk melihat cakupan mana yang menyimpan definisi server. Untuk cara cakupan berinteraksi ketika server yang sama didefinisikan di lebih dari satu, lihat MCP installation scopes.

Ubah cakupan server

Cakupan server diperbaiki ketika Anda menambahkannya, jadi mengubah cakupan berarti menghapus entri dan menambahkannya kembali di yang baru. Kedua kasus di bawah dimulai dengan menghapus entri lokal dari panduan pertama, jadi server hanya memiliki satu definisi. Jika Anda sudah menghapusnya di akhir panduan itu, lewati perintah ini:

claude mcp remove claude-code-docs --scope local

Gunakan server di semua proyek Anda

Tambahkan kembali server di cakupan user untuk membuatnya aktif di setiap proyek yang Anda buka, masih pribadi untuk Anda:

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

Bagikan server dengan tim Anda

Tambahkan kembali server di cakupan project, yang menulis ke .mcp.json di akar proyek:

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

Komit .mcp.json ke kontrol versi. Rekan tim yang mengkloning repositori dan memulai Claude Code melihat prompt untuk menyetujui server, kemudian terhubung untuk mereka juga.

Contoh server MCP tambahan

Panduan pertama menggunakan server yang dihosting yang terhubung tanpa masuk apa pun. Contoh di bawah mencakup dua bentuk umum lainnya, dengan alur tambah, periksa, gunakan yang sama.

Tambahkan server lokal

Server stdio lokal adalah program yang Claude Code mulai sebagai subprocess di mesin Anda, daripada layanan yang dijangkaunya melalui URL. Gunakan satu untuk alat yang memerlukan akses ke sumber daya lokal seperti browser, sistem file Anda, atau soket database.

Server MCP Playwright adalah yang bagus untuk dicoba: memberikan Claude browser yang dapat dinavigasi, diklik, dan dibaca, dan tidak memerlukan akun. Ini berjalan melalui npx, jadi memerlukan Node.js 18 atau lebih baru.

1. Tambahkan server Playwright

Daftarkan server dengan perintah yang harus Claude Code jalankan untuk memulainya:

claude mcp add playwright -- npx -y @playwright/mcp@latest

Perintah ini berbeda dari contoh yang dihosting dalam tiga cara:

  • Tidak ada flag --transport, karena server lokal menggunakan transport stdio default.
  • Semuanya setelah pemisah -- adalah perintah yang Claude Code jalankan untuk memulai server.
  • -y memberitahu npx untuk menginstal paket tanpa meminta.

Perintah ini mencetak konfirmasi seperti Added stdio MCP server playwright with command: npx -y @playwright/mcp@latest to local config, diikuti oleh baris File modified: yang menunjukkan file konfigurasi yang ditulisnya.

Playwright mendorong Chrome apa pun yang sudah terinstal di mesin Anda. Untuk menggunakan browser yang berbeda, tambahkan --browser dengan nama browser, misalnya --browser firefox, setelah @playwright/mcp@latest.

2. Periksa koneksi

Konfirmasi Added berarti entri disimpan, bukan bahwa perintah berjalan. Periksa koneksi:

claude mcp list

Pemeriksaan pertama dapat menunjukkan ✘ Failed to connect sementara npx mengunduh paket, jadi tunggu sebentar dan jalankan lagi. Setelah unduhan selesai, status berubah menjadi ✔ Connected. Jika masih menunjukkan ✘ Failed to connect setelah beberapa kali mencoba ulang, lihat Troubleshooting.

3. Gunakan browser

Berikan Claude tugas yang memerlukan browser:

Use playwright to open https://example.com and tell me the page title

Jendela browser terbuka sehingga Anda dapat menontonnya bekerja, dan panggilan alat dalam output Claude diberi label dengan nama server playwright dan tindakan, seperti browser_navigate.

Coba arahkan ke server dev lokal Anda untuk memeriksa bahwa halaman masih dirender setelah perubahan, atau buat Claude menjalani laporan bug langkah demi langkah.

Terhubung ke server yang memerlukan masuk

Layanan yang dihosting seperti Sentry, Linear, dan Notion menjalankan server MCP mereka di belakang OAuth: Anda menambahkan URL server, kemudian masuk melalui browser Anda.

Langkah-langkah di bawah menggunakan Sentry sebagai contoh. Untuk terhubung ke layanan yang berbeda, gantikan URL-nya, yang dapat Anda temukan di Direktori Anthropic atau dokumentasi layanan.

1. Tambahkan server

Perintah add sama seperti untuk server docs, dengan URL Sentry:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Setelah menambahkan, claude mcp list menunjukkan server dengan ! Needs authentication. Itu diharapkan: langkah berikutnya menyelesaikan masuk.

2. Autentikasi di browser Anda

Mulai sesi Claude Code dan buka panel MCP:

/mcp

Pilih sentry dari daftar, tekan Enter, dan pilih Authenticate. Browser Anda membuka halaman masuk Sentry. Setujui koneksi di sana.

Kembali di Claude Code, status server berubah menjadi terhubung. Jika masuk gagal atau browser tidak terbuka, lihat Troubleshooting.

3. Gunakan server

Tanyakan Claude sesuatu yang memerlukan layanan, seperti What Sentry projects do I have access to?, dan cari panggilan alat yang diberi label dengan nama server sentry di outputnya.

Server yang mengautentikasi dengan token statis daripada OAuth mengambil token pada waktu penambahan dengan --header "Authorization: Bearer <token>". Lihat contoh GitHub untuk versi yang dikerjakan.

Edit .mcp.json secara langsung

Setiap file dalam tabel cakupan menggunakan format JSON yang sama untuk entri server. Bagian ini mengedit .mcp.json, file cakupan proyek. Ini adalah yang paling layak ditulis dengan tangan karena diperiksa ke dalam repositori, di mana ia berfungsi ganda sebagai konfigurasi-sebagai-kode untuk tim Anda.

Buat .mcp.json di akar proyek Anda. Contoh di bawah mendefinisikan kedua server dari panduan ini, server docs yang dihosting dijangkau melalui HTTP dan server Playwright sebagai proses stdio lokal:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Bidang berbeda menurut jenis server:

  • Untuk server HTTP, url adalah titik akhir yang Claude Code terhubung.
  • Untuk server stdio, command dan args adalah program yang dijalankannya.

Setelah menyimpan file, mulai sesi Claude Code baru di proyek. Claude Code membaca .mcp.json saat startup.

Pertama kali Claude Code melihat server yang dibatasi proyek, ia meminta Anda untuk menyetujuinya. Prompt ada sehingga repositori yang Anda kloning tidak dapat meluncurkan proses di mesin Anda tanpa persetujuan Anda. Setujui prompt, atau jalankan /mcp untuk menyetujui nanti jika Anda melewatkannya.

Setelah Anda menyetujui, jalankan /mcp dan periksa bahwa server menunjukkan sebagai terhubung. Jika salah satu menunjukkan kesalahan, lihat Troubleshooting.

Terhubung dari permukaan lain

Panduan ini menggunakan perintah CLI claude mcp, tetapi setiap permukaan Claude Code dapat terhubung ke server MCP:

Troubleshooting

Jika server tidak terhubung, periksa statusnya dengan /mcp di dalam sesi atau claude mcp list dari shell Anda, kemudian cocokkan gejala di bawah. Panel /mcp juga memungkinkan Anda untuk menghubungkan kembali atau mengautentikasi tanpa meninggalkan sesi.

/mcp shows No MCP servers configured

Claude Code tidak menemukan server apa pun untuk direktori saat ini. Penyebab paling umum:

  • Anda menjalankan claude mcp add dari proyek yang berbeda. Server yang dibatasi lokal terikat pada proyek tempat Anda menambahkannya: akar repositori, atau direktori yang tepat jika Anda tidak berada di repositori git. Tambahkan kembali server dari proyek yang Anda gunakan sekarang, atau tambahkan dengan --scope user sehingga tidak terikat pada proyek.
  • Anda mengedit file konfigurasi di jalur yang salah. File yang benar adalah ~/.claude.json dan <project>/.mcp.json. Claude Code tidak membaca jalur seperti ~/.claude/.mcp.json, ~/.claude/config/mcp.json, ~/.claude/mcp.json, atau %APPDATA%\Claude\mcp.json. Untuk server yang dibatasi pengguna, jalankan claude mcp add --scope user, yang menulis ke kunci mcpServers di ~/.claude.json; untuk server yang dibatasi proyek, edit .mcp.json di akar proyek.
  • Anda menulis entri yang salah bentuk di .mcp.json. Claude Code melewati entri itu dan masih memuat yang lain. Jalankan claude mcp list dari shell Anda dan cari peringatan parse, yang menyebutkan nama bidang yang menyinggung.

Status shows Failed to connect or Connection error

Kedua status berarti server tidak dimulai atau URL tidak merespons. Mereka juga dapat muncul untuk server HTTP yang menolak token yang Anda konfigurasi di headers.Authorization; server yang menginginkan token yang belum Anda konfigurasi menampilkan ! Needs authentication sebagai gantinya, tercakup dalam Terhubung ke server yang memerlukan masuk.

Langkah pertama Anda tergantung pada status mana yang Anda lihat:

  • Failed to connect: mulai dengan detail kegagalan pada status itu sendiri. claude mcp list dan claude mcp get <name> menampilkan status HTTP atau kode kesalahan dan teks kesalahan apa pun yang dikembalikan server, yang sering kali menyebutkan masalah secara langsung, seperti header yang hilang atau token yang ditolak. Sebelum v2.1.219, Failed to connect hanya menampilkan status telanjang, dan Anda memerlukan pemeriksaan curl dan perintah nanti di bagian ini untuk menemukan penyebabnya.
  • Connection error: Claude Code tidak menambahkan detail ke status ini pada versi apa pun, jadi langsung ke pemeriksaan curl dan perintah nanti di bagian ini.

Jika detail menunjuk ke kredensial atau URL, juga periksa peringatan dalam output claude mcp list. Claude Code menandai nilai konfigurasi dengan spasi putih terkemuka atau tertinggal yang tersembunyi, penyebab umum kegagalan autentikasi setelah menempel token.

Jika server HTTP mengembalikan 404 Not Found, Claude Code menampilkan MCP endpoint not found at <origin>. Check the URL in your MCP config. ketika Anda memilih server di /mcp. Pesan menyebutkan asal URL, seperti https://mcp.example.com, tanpa jalurnya, jadi jalankan claude mcp get <name> untuk melihat URL lengkap yang Anda konfigurasi. Bandingkan jalurnya dengan jalur titik akhir MCP yang didokumentasikan server, kemudian jalankan claude mcp remove <name> dan tambahkan kembali dengan URL yang benar. Sebelum v2.1.219, pesan menyertakan jalur URL juga, dan sebelum v2.1.191, 404 menampilkan pesan generik Error POSTing to endpoint tanpa URL.

Untuk server HTTP, konfirmasi URL dapat dijangkau dari mesin Anda:

curl -I https://mcp.sentry.dev/mcp

Di PowerShell, gunakan curl.exe daripada curl sehingga permintaan pergi ke biner curl nyata daripada alias Invoke-WebRequest.

Respons memberi tahu Anda jenis masalah apa yang Anda miliki:

  • A 404 atau 405: server aktif. Banyak titik akhir MCP hanya menjawab permintaan POST, jadi ini masih mengonfirmasi URL dapat dijangkau dari mesin Anda.
  • A 401 atau 403: server aktif dan Anda perlu mengautentikasi. Gunakan masuk browser di Terhubung ke server yang memerlukan masuk, atau untuk server yang mengambil token, seperti GitHub, teruskan dengan --header "Authorization: Bearer <token>" pada perintah claude mcp add.
  • Tidak ada respons sama sekali: periksa URL dan jaringan Anda.

Untuk server stdio, jalankan perintah yang dikonfigurasi langsung di terminal Anda untuk melihat kesalahan yang mendasar. Untuk server Playwright dari panduan ini, jalankan:

npx -y @playwright/mcp@latest

Apa yang terjadi selanjutnya memberi tahu Anda di mana masalahnya:

  • Perintah dimulai dan menunggu input: server itu sendiri berfungsi.

    Jalankan claude mcp get <name> dan konfirmasi perintah yang ditampilkan di sana cocok dengan apa yang baru saja Anda jalankan. Jika perintah yang ditampilkan berbeda dari apa yang Anda ketik, Anda mungkin menghilangkan pemisah -- sebelum perintah server. Hapus server dan tambahkan kembali dengan -- di tempat. Jika Anda menulis .mcp.json dengan tangan, periksa sintaks dan lokasinya. Sebelum v2.1.285, claude mcp get tidak mencetak baris Command untuk entri stdio yang disimpan tanpa bidang type, seperti entri .mcp.json yang ditulis dengan tangan. Pada versi tersebut, jalankan claude mcp list sebagai gantinya, yang mencetak baris perintah baik cara.

  • Perintah kesalahan: pesan menyebutkan apa yang hilang, seperti Node.js atau browser.

Connection timed out at startup

Server membutuhkan waktu lebih lama dari batas waktu startup default 30 detik. Jalankan pertama server stdio dapat lambat sementara npx mengunduh paket. Tingkatkan batas dengan variabel lingkungan MCP_TIMEOUT, dalam milidetik:

MCP_TIMEOUT=60000 claude

Di PowerShell, atur variabel sebelum perintah pada baris yang sama:

$env:MCP_TIMEOUT = "60000"; claude

Sebelum v2.1.299, beberapa koneksi ke server HTTP yang aktif mengalami timeout saat startup terlepas dari MCP_TIMEOUT. Jika Anda menggunakan salah satu versi tersebut dan server HTTP yang aktif masih mengalami timeout setelah Anda menaikkan batas, perbarui Claude Code.

Server already exists

Anda telah menambahkan server dengan nama itu di cakupan yang sama. Baik hapus entri yang ada terlebih dahulu atau pilih nama yang berbeda:

claude mcp remove claude-code-docs

Jika nama ada di lebih dari satu cakupan, remove melaporkan exists in multiple scopes. Teruskan --scope untuk memilih salinan mana yang akan dihapus, misalnya claude mcp remove claude-code-docs --scope local.

Server connects but no tools appear

Jalankan /mcp di dalam sesi dan pilih server untuk melihat daftar alatnya. Jika daftar kosong, server dimulai tetapi tidak mendaftarkan alat apa pun, yang biasanya berarti hilang variabel lingkungan yang diperlukan seperti kunci API.

Teruskan variabel dengan --env KEY=value pada claude mcp add, atau di bidang env dari entri .mcp.json server. Dokumentasi server mencantumkan variabel yang dibutuhkannya.

Sebelum v2.1.302, /mcp menampilkan status tools fetch failed untuk server yang menggunakan revisi protokol 2026-07-28 yang tidak menyertakan resultType, ttlMs, atau cacheScope dalam balasannya. Jika Anda menggunakan salah satu versi tersebut dan server menampilkan status itu, perbarui Claude Code.

Changes to .mcp.json don't take effect

Claude Code membaca .mcp.json saat startup sesi. Keluar dan mulai ulang sesi setelah mengedit file.

Jika server Anda masih tidak muncul, jalankan claude mcp list dan cari peringatan parse. Claude Code melewati entri yang salah bentuk dan menunjukkan bidang yang menyinggung di sana.

Jika Anda sebelumnya menolak server saat diminta, atur ulang persetujuan proyek:

claude mcp reset-project-choices

OAuth sign-in fails or browser doesn't open

Jalankan /mcp, pilih server, dan pilih Authenticate lagi. Jika browser tidak terbuka secara otomatis, salin URL yang ditampilkan di terminal dan buka secara manual. Lihat Autentikasi dengan server MCP jarak jauh untuk port callback tetap dan kredensial yang telah dikonfigurasi sebelumnya.

Langkah berikutnya

Dengan satu server terhubung, jelajahi sisa dari apa yang MCP memungkinkan: