query, dan mengontrol alat mana yang dapat diakses Claude. Ini juga mencakup penanganan kesalahan, anotasi alat, dan mengembalikan konten non-teks seperti gambar.
Referensi cepat
| Jika Anda ingin… | Lakukan ini |
|---|---|
| Menentukan alat | Gunakan @tool (Python) atau tool() (TypeScript) dengan nama, deskripsi, skema, dan penangan. Lihat Buat alat kustom. |
| Mendaftarkan alat dengan Claude | Bungkus dalam create_sdk_mcp_server / createSdkMcpServer dan teruskan ke mcpServers dalam query(). Lihat Panggil alat kustom. |
| Pra-setujui alat | Tambahkan ke alat yang diizinkan Anda. Lihat Konfigurasi alat yang diizinkan. |
| Hapus alat bawaan dari konteks Claude | Teruskan array tools yang hanya mencantumkan bawaan yang Anda inginkan. Lihat Konfigurasi alat yang diizinkan. |
| Biarkan Claude memanggil alat secara paralel | Atur readOnlyHint: true pada alat tanpa efek samping. Lihat Tambahkan anotasi alat. |
| Tangani kesalahan tanpa menghentikan loop | Kembalikan isError: true alih-alih melempar. Lihat Tangani kesalahan. |
| Kembalikan gambar atau file | Gunakan blok image atau resource dalam array konten. Lihat Kembalikan gambar dan sumber daya. |
| Kembalikan hasil JSON yang dapat dibaca mesin | Atur structuredContent pada hasilnya. Lihat Kembalikan data terstruktur. |
| Skalakan ke banyak alat | Gunakan pencarian alat untuk memuat alat sesuai permintaan. |
Buat alat kustom
Alat didefinisikan oleh empat bagian, diteruskan sebagai argumen ke pembantutool() di TypeScript atau dekorator @tool di Python:
- Nama: pengidentifikasi unik yang digunakan Claude untuk memanggil alat.
- Deskripsi: apa yang dilakukan alat. Claude membaca ini untuk memutuskan kapan memanggilnya.
- Skema input: argumen yang harus disediakan Claude. Di TypeScript ini selalu skema Zod, dan
argspenangan diketik darinya secara otomatis. Di Python ini adalah dict yang memetakan nama ke tipe, seperti{"latitude": float}, yang dikonversi SDK ke JSON Schema untuk Anda. Dekorator Python juga menerima dict JSON Schema lengkap secara langsung ketika Anda membutuhkan enum, rentang, bidang opsional, atau objek bersarang. - Penangan: fungsi async yang berjalan ketika Claude memanggil alat. Ini menerima argumen yang divalidasi dan harus mengembalikan objek dengan:
content(diperlukan): array blok hasil, masing-masing dengantypedari"text","image", atau"resource". Lihat Kembalikan gambar dan sumber daya untuk blok non-teks.structuredContent(opsional): objek JSON yang menyimpan hasil sebagai data yang dapat dibaca mesin, dikembalikan bersamacontent. Lihat Kembalikan data terstruktur.isError(opsional): atur ketrueuntuk menandakan kegagalan alat sehingga Claude dapat bereaksi terhadapnya. Lihat Tangani kesalahan.
createSdkMcpServer (TypeScript) atau create_sdk_mcp_server (Python). Server berjalan dalam proses di dalam aplikasi Anda, bukan sebagai proses terpisah.
Contoh alat cuaca
Contoh ini menentukan alatget_temperature dan membungkusnya dalam server MCP. Ini hanya menyiapkan alat; untuk meneruskannya ke query dan menjalankannya, lihat Panggil alat kustom di bawah.
tool() atau referensi Python @tool untuk detail parameter lengkap, termasuk format input JSON Schema dan struktur nilai pengembalian.
Panggil alat kustom
Teruskan server MCP yang Anda buat kequery melalui opsi mcpServers. Kunci dalam mcpServers menjadi segmen {server_name} dalam nama lengkap setiap alat: mcp__{server_name}__{tool_name}. Cantumkan nama itu dalam allowedTools sehingga alat berjalan tanpa prompt izin.
Cuplikan ini menggunakan kembali weatherServer dari contoh di atas untuk menanyakan Claude tentang cuaca di lokasi tertentu.
Tambahkan lebih banyak alat
Server menyimpan sebanyak alat yang Anda cantumkan dalam arraytools nya. Dengan lebih dari satu alat di server, Anda dapat mencantumkan masing-masing dalam allowedTools secara individual atau menggunakan wildcard mcp__weather__* untuk mencakup setiap alat yang diekspos server.
Contoh di bawah menambahkan alat kedua, get_precipitation_chance, ke weatherServer dari contoh alat cuaca dan membangunnya kembali dengan kedua alat dalam array.
Tambahkan anotasi alat
Anotasi alat adalah metadata opsional yang menggambarkan perilaku alat. Teruskan sebagai argumen kelima ke pembantutool() di TypeScript atau melalui argumen kata kunci annotations untuk dekorator @tool di Python. Semua bidang hint adalah Boolean.
| Bidang | Default | Arti |
|---|---|---|
readOnlyHint | false | Alat tidak memodifikasi lingkungannya. Mengontrol apakah alat dapat dipanggil secara paralel dengan alat baca-saja lainnya. |
destructiveHint | true | Alat dapat melakukan pembaruan destruktif. Hanya informatif. |
idempotentHint | false | Panggilan berulang dengan argumen yang sama tidak memiliki efek tambahan. Hanya informatif. |
openWorldHint | true | Alat menjangkau sistem di luar proses Anda. Hanya informatif. |
readOnlyHint: true masih dapat menulis ke disk jika itulah yang dilakukan penangan. Jaga anotasi akurat dengan penangan.
Contoh ini menambahkan readOnlyHint ke alat get_temperature dari contoh alat cuaca.
ToolAnnotations dalam referensi TypeScript atau Python.
Kontrol akses alat
Contoh alat cuaca mendaftarkan server dan mencantumkan alat dalamallowedTools. Bagian ini mencakup cara nama alat dibangun dan cara membatasi akses ketika Anda memiliki beberapa alat atau ingin membatasi bawaan.
Format nama alat
Ketika alat MCP diekspos ke Claude, nama mereka mengikuti format tertentu:- Pola:
mcp__{server_name}__{tool_name} - Contoh: Alat bernama
get_temperaturedi serverweathermenjadimcp__weather__get_temperature
Konfigurasi alat yang diizinkan
Opsitools dan daftar izin/larangan yang diizinkan mempengaruhi dua lapisan: ketersediaan, yang mengontrol apakah alat muncul dalam konteks Claude, dan izin, yang mengontrol apakah panggilan disetujui setelah Claude mencobanya. tools dan entri disallowedTools dengan nama biasa mengubah ketersediaan. allowedTools dan aturan disallowedTools yang dibatasi ruang lingkup mengubah izin saja.
| Opsi | Lapisan | Efek |
|---|---|---|
tools: ["Read", "Grep"] | Ketersediaan | Hanya bawaan yang tercantum ada dalam konteks Claude. Bawaan yang tidak tercantum dihapus. Alat MCP tidak terpengaruh. |
tools: [] | Ketersediaan | Semua bawaan dihapus. Claude hanya dapat menggunakan alat MCP Anda. |
| alat yang diizinkan | Izin | Alat yang tercantum berjalan tanpa prompt izin. Alat yang tidak tercantum tetap tersedia; panggilan melalui alur izin. |
| alat yang dilarang | Keduanya | Nama alat biasa seperti "Bash" menghapus alat dari konteks Claude, sama seperti menghilangkannya dari tools. Aturan yang dibatasi ruang lingkup seperti "Bash(rm *)" membiarkan alat dalam konteks dan hanya menolak panggilan yang cocok. |
tools atau cantumkan nama biasanya dalam disallowedTools (Python: disallowed_tools); keduanya membuat alat tetap keluar dari konteks sehingga Claude tidak pernah mencobanya. Aturan disallowedTools yang dibatasi ruang lingkup memblokir panggilan yang cocok tetapi membiarkan alat terlihat, jadi Claude mungkin membuang giliran mencobanya. Lihat Konfigurasi izin untuk urutan evaluasi lengkap.
Tangani kesalahan
Cara penangan Anda melaporkan kesalahan menentukan apakah loop agen berlanjut atau berhenti:| Apa yang terjadi | Hasil |
|---|---|
| Penangan melempar pengecualian yang tidak tertangkap | Loop agen berhenti. Claude tidak pernah melihat kesalahan, dan panggilan query gagal. |
Penangan menangkap kesalahan dan mengembalikan isError: true (TS) / "is_error": True (Python) | Loop agen berlanjut. Claude melihat kesalahan sebagai data dan dapat mencoba lagi, mencoba alat berbeda, atau menjelaskan kegagalan. |
try/except (Python) atau try/catch (TypeScript) sekitarnya dan juga dikembalikan sebagai hasil kesalahan. Dalam kedua kasus penangan mengembalikan secara normal dan loop agen berlanjut.
Kembalikan gambar dan sumber daya
Arraycontent dalam hasil alat menerima blok text, image, dan resource. Anda dapat mencampurnya dalam respons yang sama.
Gambar
Blok gambar membawa byte gambar secara inline, dikodekan sebagai base64. Tidak ada bidang URL. Untuk mengembalikan gambar yang berada di URL, ambil dalam penangan, baca byte respons, dan kodekan base64 sebelum mengembalikan. Hasilnya diproses sebagai input visual.| Bidang | Tipe | Catatan |
|---|---|---|
type | "image" | |
data | string | Byte yang dikodekan Base64. Hanya base64 mentah, tanpa awalan data:image/...;base64, |
mimeType | string | Diperlukan. Misalnya image/png, image/jpeg, image/webp, image/gif |
Sumber daya
Blok sumber daya menyematkan sepotong konten yang diidentifikasi oleh URI. URI adalah label untuk Claude referensikan; konten aktual berada dalam bidangtext atau blob blok. Gunakan ini ketika alat Anda menghasilkan sesuatu yang masuk akal untuk ditangani berdasarkan nama nanti, seperti file yang dihasilkan atau catatan dari sistem eksternal.
| Bidang | Tipe | Catatan |
|---|---|---|
type | "resource" | |
resource.uri | string | Pengidentifikasi untuk konten. Skema URI apa pun |
resource.text | string | Konten, jika teks. Sediakan ini atau blob, bukan keduanya |
resource.blob | string | Konten yang dikodekan base64, jika biner |
resource.mimeType | string | Opsional |
file:///tmp/report.md adalah label yang dapat direferensikan Claude nanti; SDK tidak membaca dari jalur itu.
CallToolResult. Lihat spesifikasi MCP untuk definisi lengkap.
Kembalikan data terstruktur
structuredContent adalah objek JSON opsional pada hasil, terpisah dari array content. Gunakan untuk mengembalikan nilai mentah yang dapat dibaca Claude sebagai bidang tepat alih-alih menguraikannya dari string teks atau gambar.
Ketika structuredContent diatur, Claude menerima JSON plus blok gambar atau sumber daya apa pun dari content. Blok teks dalam content tidak diteruskan, karena diasumsikan menduplikasi data terstruktur. Contoh di bawah merender bagan sebagai blok gambar dan mengembalikan titik data di baliknya dalam structuredContent dari penangan yang sama.
TypeScript
Dekorator Python
@tool hanya meneruskan content dan is_error dari dict pengembalian penangan. Untuk mengembalikan structuredContent dari Python, jalankan server MCP mandiri alih-alih server SDK dalam proses.Contoh: konverter unit
Alat ini mengonversi nilai antara unit panjang, suhu, dan berat. Pengguna dapat menanyakan “konversi 100 kilometer ke mil” atau “berapa 72°F dalam Celsius,” dan Claude memilih tipe unit dan unit yang tepat dari permintaan. Ini menunjukkan dua pola:- Skema enum:
unit_typedibatasi pada set nilai tetap. Di TypeScript, gunakanz.enum(). Di Python, skema dict tidak mendukung enum, jadi dict JSON Schema lengkap diperlukan. - Penanganan input yang tidak didukung: ketika pasangan konversi tidak ditemukan, penangan mengembalikan
isError: truesehingga Claude dapat memberi tahu pengguna apa yang salah alih-alih memperlakukan kegagalan sebagai hasil normal.
query dengan cara yang sama seperti contoh cuaca. Contoh ini mengirim tiga prompt berbeda dalam loop untuk menunjukkan alat yang sama menangani tipe unit berbeda. Untuk setiap respons, ia memeriksa objek AssistantMessage (yang berisi panggilan alat yang dibuat Claude selama giliran itu) dan mencetak setiap ToolUseBlock sebelum mencetak teks ResultMessage akhir. Ini memungkinkan Anda melihat kapan Claude menggunakan alat versus menjawab dari pengetahuannya sendiri.
Langkah berikutnya
Alat kustom membungkus fungsi async dalam antarmuka standar. Anda dapat mencampur pola di halaman ini di server yang sama: server tunggal dapat menyimpan alat database, alat gateway API, dan renderer gambar bersama-sama. Dari sini:- Jika server Anda tumbuh menjadi puluhan alat, lihat pencarian alat untuk menunda pemuatan mereka sampai Claude membutuhkannya.
- Untuk terhubung ke server MCP eksternal (sistem file, GitHub, Slack) alih-alih membangun milik Anda sendiri, lihat Hubungkan server MCP.
- Untuk mengontrol alat mana yang berjalan secara otomatis versus memerlukan persetujuan, lihat Konfigurasi izin.