Konektor MCP

Fitur konektor "Model Context Protocol", atau MCP, milik 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 allowlist untuk alat tertentu, atau denylist untuk alat yang tidak diinginkan
• Konfigurasi per alat: Konfigurasikan alat satu per satu dengan pengaturan kustom
• Autentikasi OAuth: Dukungan untuk token OAuth Bearer untuk server yang memerlukan autentikasi
• Beberapa server: Terhubung ke beberapa server MCP dalam satu permintaan

Kapan Claude menggunakan alat MCP

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

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

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

Keterbatasan

• Dari rangkaian fitur spesifikasi MCP, saat ini hanya pemanggilan alat yang 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. Toolset MCP (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-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 toolset MCP

MCPToolset berada dalam array tools dan mengonfigurasi alat mana dari server MCP yang diaktifkan serta 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

Dengan header beta mcp-client-2026-09-15, MCPToolset juga menerima tools, yaitu salinan daftar alat server yang disematkan (pinned). Lihat Menyematkan daftar alat server MCP.

Opsi konfigurasi alat

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

Untuk direktori lengkap alat yang disediakan Anthropic dan properti opsional seperti defer_loading, lihat Referensi alat. Untuk mencari di antara kumpulan alat yang besar, lihat alat pencarian alat.

Penggabungan konfigurasi

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

1. Pengaturan khusus 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"
}

Allowlist: 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
    }
  }
}

Denylist: nonaktifkan alat tertentu

Aktifkan semua alat secara default, lalu nonaktifkan alat yang tidak diinginkan secara eksplisit. Membuat denylist untuk alat tulis atau alat yang bersifat destruktif disarankan saat membangun asisten read-only, atau ketika 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: allowlist dengan konfigurasi per alat

Gabungkan allowlist 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 tidak dikenal: Jika nama alat dalam configs tidak ada di server MCP, peringatan backend akan 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"
    }
  ]
}

Menyematkan daftar alat server MCP (beta)

Server MCP dapat mengubah alatnya kapan saja. Header beta mcp-client-2026-09-15 mencatat daftar alat yang dikembalikan setiap server dan memungkinkan Anda menyematkannya, sehingga server yang mengubah alatnya tidak mengubah apa yang dilihat Claude di tengah percakapan. Header ini mencakup semua yang dilakukan mcp-client-2025-11-20, jadi kirimkan header ini sebagai pengganti header tersebut. Fitur ini tersedia di Claude API.

Ketika API meminta daftar alat dari server MCP saat menghasilkan respons, respons diawali dengan blok mcp_tool_listing untuk server tersebut, satu blok untuk setiap server yang dimintai:

{
  "type": "mcp_tool_listing",
  "mcp_server_name": "example-mcp",
  "tools": [
    {
      "name": "echo",
      "description": "Returns the text it receives.",
      "input_schema": {
        "type": "object",
        "properties": { "text": { "type": "string" } },
        "required": ["text"]
      }
    }
  ]
}

Jika kode Anda membaca content[0], lewati blok-blok ini. Kirimkan kembali pesan asisten tanpa perubahan, termasuk blok mcp_tool_listing, dan tetap kirimkan mcp-client-2026-09-15 pada setiap permintaan yang membawa blok tersebut. Permintaan berikutnya kemudian menggunakan daftar yang tercatat untuk server tersebut alih-alih memintanya lagi.

Untuk menyematkan daftar sendiri, salin tools dari sebuah blok ke field tools pada MCPToolset server tersebut. API kemudian tidak meminta daftar alat dari server, dan alat dalam toolset tersebut persis berupa entri-entri itu, dengan default_config dan configs diterapkan:

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "tools": [
    {
      "name": "echo",
      "description": "Returns the text it receives.",
      "input_schema": {
        "type": "object",
        "properties": { "text": { "type": "string" } },
        "required": ["text"]
      }
    }
  ]
}

Setiap entri dalam tools memuat name alat sebagaimana dicantumkan oleh server (tanpa nama server), description-nya, dan input_schema-nya.

Contoh berikut mengirimkan satu permintaan dengan toolset yang tidak disematkan, menyalin daftar yang dikembalikan ke field tools pada toolset, lalu mengirimkan permintaan tersebut lagi. Respons kedua tidak memiliki blok mcp_tool_listing, karena API tidak meminta daftar dari server:

from anthropic.types.beta import (
    BetaMessageParam,
    BetaRequestMCPServerURLDefinitionParam,
)

client = anthropic.Anthropic()

mcp_servers: list[BetaRequestMCPServerURLDefinitionParam] = [
    {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN",
    },
]
messages: list[BetaMessageParam] = [
    {"role": "user", "content": "What tools do you have available?"},
]

# Permintaan pertama: toolset belum disematkan, jadi API meminta server untuk
# mengirim daftar alatnya dan respons diawali dengan blok mcp_tool_listing.
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    messages=messages,
)

listing = next(block for block in first.content if block.type == "mcp_tool_listing")
print([tool.name for tool in listing.tools])

# Sematkan daftarnya: salin tools dari blok tersebut ke toolset. API memakai
# persis entri-entri ini dan tidak meminta ke server lagi.
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[
        {
            "type": "mcp_toolset",
            "mcp_server_name": "example-mcp",
            "tools": [
                {
                    "name": tool.name,
                    "description": tool.description,
                    "input_schema": tool.input_schema,
                }
                for tool in listing.tools
            ],
        },
    ],
    messages=messages,
)

# Dengan toolset yang disematkan, respons tidak berisi blok mcp_tool_listing.
print([block.type for block in second.content])

Dengan tambahan header beta inline-tools-2026-09-15, Anda dapat menambahkan server MCP di tengah percakapan. Lihat Menambahkan server MCP di tengah percakapan.

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-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 bersama alat pencarian alat sehingga hanya alat yang relevan yang ditampilkan per kueri.

Autentikasi

Untuk server MCP yang memerlukan autentikasi OAuth, Anda perlu mendapatkan access token. Konektor MCP beta mendukung pengiriman parameter authorization_token dalam definisi server MCP. Konsumen API diharapkan menangani alur OAuth dan mendapatkan access token sebelum melakukan panggilan API, serta memperbarui 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 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 Open Auth Settings setelah Need to configure authentication?.

5. Klik Quick OAuth Flow dan lakukan otorisasi di 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 detail 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 MCP SDK untuk bahasa Anda (misalnya, TypeScript MCP SDK) bersama 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-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-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 pesan
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5-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.files.upload(
    file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)

Penanganan error

Fungsi konversi gagal dengan UnsupportedMCPValueError jika suatu nilai MCP tidak didukung oleh Claude API (dilempar sebagai exception, atau di Go dikembalikan sebagai error). Hal ini dapat terjadi pada tipe konten, tipe MIME, atau tautan resource yang tidak didukung (selesaikan tautan resource dengan klien MCP Anda sebelum melakukan konversi).

Permintaan batch

Anda dapat menyertakan mcp_servers dalam permintaan Message Batches API. Pemanggilan alat MCP melalui Batches API dikenai harga yang sama dengan pemanggilan dalam permintaan Messages API biasa.

Retensi data

Konektor MCP tidak tercakup dalam 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 header beta mcp-client-2025-04-04 yang sudah deprecated, ikuti panduan ini untuk bermigrasi ke versi baru.

Perubahan utama

1. Header beta baru: Ubah dari mcp-client-2025-04-04 menjadi mcp-client-2025-11-20
2. Konfigurasi alat dipindahkan: Konfigurasi alat kini berada dalam array tools sebagai objek MCPToolset, bukan dalam definisi server MCP
3. Konfigurasi lebih fleksibel: Pola baru mendukung allowlist, denylist, dan konfigurasi per alat

Langkah migrasi

Sebelum (deprecated):

{
  "model": "claude-opus-5-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-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 deprecated: 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 deprecated

Compatibility