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, izinkan alat tertentu (allowlist), atau tolak alat yang tidak diinginkan (denylist)
• 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 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 isi 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 rangkaian 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.
• Konektor MCP tersedia di Claude API, Claude Platform di AWS, dan Microsoft Foundry. Di Microsoft Foundry, konektor MCP memerlukan deployment Hosted on Anthropic. Saat ini tidak tersedia di Amazon Bedrock atau Google Cloud.



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-4-8",
    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 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 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"
}



Allowlist: aktifkan hanya alat tertentu

Tetapkan 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. Menolak alat tulis atau destruktif 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: 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 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-4-8",
  "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 ditampilkan per kueri.



Autentikasi

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



Memperoleh access token untuk pengujian

MCP inspector dapat memandu Anda melalui proses memperoleh 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 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 memperoleh 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 (seperti TypeScript MCP SDK) bersama dengan Anthropic SDK.



Instalasi

Instal Anthropic SDK dan MCP SDK:

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk



Helper yang tersedia

Impor helper dari namespace beta:

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";



Menggunakan alat MCP

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

import { mcpTools } from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// Hubungkan ke server MCP
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// Daftar alat dan konversikan untuk API Claude
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

console.log(finalMessage);



Menggunakan prompt MCP

Konversi pesan prompt MCP ke format pesan Claude API:

import { mcpMessages } from "@anthropic-ai/sdk/helpers/beta/mcp";

const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

console.log(response);



Menggunakan resource MCP

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

import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";

// Sebagai blok konten dalam pesan
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// Sebagai unggahan file
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });



Penanganan error

Fungsi konversi melempar UnsupportedMCPValueError jika nilai MCP tidak didukung oleh Claude API. Ini dapat terjadi dengan tipe konten yang tidak didukung, tipe MIME, atau tautan resource non-HTTP.



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 header beta mcp-client-2025-04-04 yang sudah tidak digunakan lagi, ikuti panduan ini untuk bermigrasi ke versi baru.



Perubahan utama

1. Header beta 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 allowlist, denylist, dan konfigurasi per alat



Langkah migrasi

Sebelum (tidak digunakan lagi):

{
  "model": "claude-opus-4-8",
  "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-4-8",
  "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