Konektor MCP

Fitur konektor "Model Context Protocol", atau MCP, dari Claude memungkinkan Anda terhubung ke server MCP jarak jauh langsung dari Messages API tanpa klien MCP terpisah.



Fitur utama

• Integrasi API langsung: Terhubung ke server MCP tanpa mengimplementasikan klien MCP
• Dukungan pemanggilan alat: Akses alat MCP melalui Messages API
• Konfigurasi alat yang fleksibel: Aktifkan semua alat, buat daftar izin untuk alat tertentu, atau buat daftar tolak untuk alat yang tidak diinginkan
• Konfigurasi per alat: Konfigurasikan alat individual dengan pengaturan kustom
• Autentikasi OAuth: Dukungan untuk token OAuth Bearer untuk server yang terautentikasi
• Beberapa server: Terhubung ke beberapa server MCP dalam satu permintaan



Kapan Claude menggunakan alat MCP

Setelah server MCP terhubung, Claude memanggil alatnya ketika permintaan pengguna sesuai dengan kemampuan yang dijelaskan oleh suatu alat, baik secara eksplisit ("cari bug terbuka di Jira") maupun secara implisit ("apa yang menghambat rilis?" dengan server Jira yang terhubung).

Claude tidak memanggil alat MCP untuk pertanyaan pengetahuan umum tentang layanan yang terhubung. Bertanya "bagaimana cara kerja database Notion?" dengan server Notion yang terhubung akan dijawab secara langsung; bertanya "apa yang ada di database Projects saya?" akan memicu alat tersebut.

Anda dapat mengarahkan seberapa mudah Claude memanggil alat MCP melalui prompt sistem Anda. Lihat Kapan Claude menggunakan alat untuk panduan umum dan contoh frasa.



Batasan

• Dari kumpulan fitur spesifikasi MCP, hanya pemanggilan alat yang saat ini didukung.
• Server harus diekspos secara publik melalui HTTP (mendukung transport Streamable HTTP dan SSE). Server STDIO lokal tidak dapat dihubungkan secara langsung.



Menggunakan konektor MCP di Messages API

Konektor MCP menggunakan dua komponen:

1. Definisi Server MCP (array mcp_servers): Mendefinisikan detail koneksi server (URL, autentikasi)
2. MCP Toolset (array tools): Mengonfigurasi alat mana yang diaktifkan dan bagaimana mengonfigurasinya



Contoh dasar

Contoh ini mengaktifkan semua alat dari server MCP dengan konfigurasi default:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What tools do you have available?"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse",
            "name": "example-mcp",
            "authorization_token": "YOUR_TOKEN",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)



Konfigurasi server MCP

Setiap server MCP dalam array mcp_servers mendefinisikan detail koneksi:

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}



Deskripsi field



Konfigurasi MCP toolset

MCPToolset berada dalam array tools dan mengonfigurasi alat mana dari server MCP yang diaktifkan dan bagaimana alat tersebut harus dikonfigurasi.



Struktur dasar

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}



Deskripsi field



Opsi konfigurasi alat

Setiap alat (baik dikonfigurasi dalam default_config atau dalam configs) mendukung field berikut:

Untuk direktori lengkap alat yang disediakan Anthropic dan properti opsional seperti defer_loading, lihat Referensi alat. Untuk pencarian di seluruh kumpulan alat yang besar, lihat Tool search tool.



Penggabungan konfigurasi

Nilai konfigurasi digabungkan dengan urutan prioritas ini (tertinggi ke terendah):

1. Pengaturan spesifik alat dalam configs
2. default_config tingkat set
3. Default sistem

Contoh:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": false
    }
  }
}

Menghasilkan:

• search_events: enabled: false (dari configs), defer_loading: true (dari default_config)
• Semua alat lainnya: enabled: true (default sistem), defer_loading: true (dari default_config)



Pola konfigurasi umum



Aktifkan semua alat dengan konfigurasi default

Pola paling sederhana - aktifkan semua alat dari sebuah server:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}



Daftar izin: aktifkan hanya alat tertentu

Atur enabled: false sebagai default, lalu aktifkan alat tertentu secara eksplisit:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false
  },
  "configs": {
    "search_events": {
      "enabled": true
    },
    "create_event": {
      "enabled": true
    }
  }
}



Daftar tolak: nonaktifkan alat tertentu

Aktifkan semua alat secara default, lalu nonaktifkan alat yang tidak diinginkan secara eksplisit. Memasukkan alat tulis atau alat destruktif ke daftar tolak direkomendasikan saat membangun asisten read-only, atau saat Anda menginginkan langkah konfirmasi manusia sebelum perubahan state:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": {
      "enabled": false
    },
    "share_calendar_publicly": {
      "enabled": false
    }
  }
}



Campuran: daftar izin dengan konfigurasi per alat

Gabungkan daftar izin dengan konfigurasi kustom untuk setiap alat:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false,
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": true,
      "defer_loading": false
    },
    "list_events": {
      "enabled": true
    }
  }
}

Dalam contoh ini:

• search_events diaktifkan dengan defer_loading: false
• list_events diaktifkan dengan defer_loading: true (diwarisi dari default_config)
• Semua alat lainnya dinonaktifkan



Aturan validasi

API menerapkan aturan validasi berikut:

• Server harus ada: mcp_server_name dalam MCPToolset harus cocok dengan server yang didefinisikan dalam array mcp_servers
• Server harus digunakan: Setiap server MCP yang didefinisikan dalam mcp_servers harus direferensikan oleh tepat satu MCPToolset
• Toolset unik per server: Setiap server MCP hanya dapat direferensikan oleh satu MCPToolset
• Nama alat yang tidak dikenal: Jika nama alat dalam configs tidak ada di server MCP, peringatan backend dicatat tetapi tidak ada error yang dikembalikan (server MCP mungkin memiliki ketersediaan alat yang dinamis)



Tipe konten respons

Ketika Claude menggunakan alat MCP, respons menyertakan dua tipe blok konten baru:



Blok MCP tool use

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}



Blok MCP tool result

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}



Beberapa server MCP

Anda dapat terhubung ke beberapa server MCP dengan menyertakan beberapa definisi server dalam mcp_servers dan MCPToolset yang sesuai untuk masing-masing dalam array tools:

{
  "model": "claude-opus-5",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example1.com/sse",
      "name": "mcp-server-1",
      "authorization_token": "TOKEN1"
    },
    {
      "type": "url",
      "url": "https://mcp.example2.com/sse",
      "name": "mcp-server-2",
      "authorization_token": "TOKEN2"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-1"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-2",
      "default_config": {
        "defer_loading": true
      }
    }
  ]
}

Dengan banyak alat yang tersedia, Claude memilih berdasarkan nama dan deskripsi alat. Deskripsi alat yang jelas dan spesifik meningkatkan akurasi pemilihan. Untuk kumpulan alat yang besar (puluhan alat di beberapa server), pertimbangkan untuk mengaktifkan defer_loading dengan Tool search tool sehingga hanya alat yang relevan yang dimunculkan per kueri.



Autentikasi

Untuk server MCP yang memerlukan autentikasi OAuth, Anda perlu mendapatkan access token. Beta konektor MCP mendukung pengiriman parameter authorization_token dalam definisi server MCP. Konsumen API diharapkan menangani alur OAuth dan mendapatkan access token sebelum melakukan panggilan API, serta me-refresh token sesuai kebutuhan.



Mendapatkan access token untuk pengujian

MCP inspector dapat memandu Anda melalui proses mendapatkan access token untuk tujuan pengujian.

1. Jalankan inspector dengan perintah berikut. Anda memerlukan Node.js yang terinstal di mesin Anda.

   npx @modelcontextprotocol/inspector

   

2. Di sidebar sebelah kiri, untuk "Transport type", pilih "SSE" atau "Streamable HTTP".

3. Masukkan URL server MCP.

4. Di area kanan, klik tombol "Open Auth Settings" setelah "Need to configure authentication?".

5. Klik "Quick OAuth Flow" dan otorisasi pada layar OAuth.

6. Ikuti langkah-langkah di bagian "OAuth Flow Progress" pada inspector dan klik "Continue" hingga Anda mencapai "Authentication complete".

7. Salin nilai access_token.

8. Tempelkan ke field authorization_token dalam konfigurasi server MCP Anda.



Menggunakan access token

Setelah Anda mendapatkan access token menggunakan salah satu alur OAuth sebelumnya, Anda dapat menggunakannya dalam konfigurasi server MCP Anda:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

Untuk penjelasan terperinci tentang alur OAuth, lihat bagian Authorization dalam spesifikasi MCP.



Helper MCP sisi klien

Jika Anda mengelola koneksi klien MCP Anda sendiri (misalnya, dengan server stdio lokal, prompt MCP, atau resource MCP), SDK menyediakan fungsi helper yang mengonversi antara tipe MCP dan tipe Claude API. Ini menghilangkan kode konversi manual saat menggunakan SDK MCP untuk bahasa Anda (misalnya, TypeScript MCP SDK) bersama dengan Anthropic SDK.



Instalasi

Instal Anthropic SDK dan MCP SDK:

pip install "anthropic[mcp]"



Helper yang tersedia

Impor helper untuk bahasa Anda:

from anthropic.lib.tools.mcp import (
    async_mcp_tool,
    mcp_message,
    mcp_resource_to_content,
    mcp_resource_to_file,
)

Nama helper dan signature persisnya mengikuti konvensi masing-masing bahasa; tabel ini menunjukkan bentuk TypeScript:



Menggunakan alat MCP

Konversi alat MCP untuk digunakan dengan tool runner SDK, yang menangani eksekusi alat secara otomatis:

from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

client = AsyncAnthropic()


async def main() -> None:
    # Menghubungkan ke server MCP
    server_params = StdioServerParameters(command="mcp-server")
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as mcp_client:
            await mcp_client.initialize()

            # Mendaftar alat dan mengonversinya untuk Claude API
            tools_result = await mcp_client.list_tools()
            runner = client.beta.messages.tool_runner(
                model="claude-opus-5",
                max_tokens=1024,
                messages=[
                    {"role": "user", "content": "What tools do you have available?"},
                ],
                tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
            )

            final_message = await runner.until_done()
            print(final_message)


asyncio.run(main())



Menggunakan prompt MCP

Konversi pesan prompt MCP ke format pesan Claude API:

from anthropic.lib.tools.mcp import mcp_message

prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[mcp_message(message) for message in prompt.messages],
)

print(response)



Menggunakan resource MCP

Konversi resource MCP menjadi blok konten untuk disertakan dalam pesan, atau menjadi objek file untuk diunggah:

from anthropic.lib.tools.mcp import (
    mcp_resource_to_content,
    mcp_resource_to_file,
)

# Sebagai blok konten dalam sebuah pesan
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                mcp_resource_to_content(resource),
                {"type": "text", "text": "Summarize this document"},
            ],
        }
    ],
)
print(response)

# Sebagai unggahan file
file_resource = await mcp_client.read_resource(
    uri="file:///path/to/data.json",
)
uploaded = await client.beta.files.upload(
    file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)



Penanganan error

Fungsi konversi melempar UnsupportedMCPValueError jika nilai MCP tidak didukung oleh Claude API (di Go, helper mengembalikan UnsupportedValueError; di Java dan C#, helper melempar AnthropicInvalidDataException). Ini dapat terjadi dengan tipe konten yang tidak didukung, tipe MIME, atau tautan resource (selesaikan tautan resource dengan klien MCP Anda sebelum mengonversi).



Permintaan batch

Anda dapat menyertakan mcp_servers dalam permintaan Message Batches API. Pemanggilan alat MCP melalui Batches API dikenakan harga yang sama dengan permintaan Messages API reguler.



Retensi data

Konektor MCP tidak tercakup oleh pengaturan ZDR. Data yang dipertukarkan dengan server MCP, termasuk definisi alat dan hasil eksekusi, disimpan sesuai dengan kebijakan retensi data standar Anthropic.

Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data.



Panduan migrasi

Jika Anda menggunakan beta header mcp-client-2025-04-04 yang sudah tidak digunakan lagi, ikuti panduan ini untuk bermigrasi ke versi baru.



Perubahan utama

1. Beta header baru: Ubah dari mcp-client-2025-04-04 ke mcp-client-2025-11-20
2. Konfigurasi alat dipindahkan: Konfigurasi alat sekarang berada dalam array tools sebagai objek MCPToolset, bukan dalam definisi server MCP
3. Konfigurasi lebih fleksibel: Pola baru mendukung daftar izin, daftar tolak, dan konfigurasi per alat



Langkah-langkah migrasi

Sebelum (tidak digunakan lagi):

{
  "model": "claude-opus-5",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}

Sesudah (saat ini):

{
  "model": "claude-opus-5",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}



Pola migrasi umum



Versi yang tidak digunakan lagi: mcp-client-2025-04-04

Versi sebelumnya dari konektor MCP menyertakan konfigurasi alat langsung dalam definisi server MCP:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}



Deskripsi field yang tidak digunakan lagi