View a markdown version of this page

Menggunakan endpoint MCP Registry - Batuan Dasar Amazon AgentCore
Gambaran umumConnect ke endpoint MCP OAuth-based registri dari klien MCP yang adaConnect ke endpoint MCP IAM-based registri dari klien MCP yang adaKembangkan klien MCP Anda sendiri

Menggunakan endpoint MCP Registry

Migrasi namespace yang akan datang

AWS Agent Registry saat ini dalam pratinjau publik di bawah namespace bedrock-agentcore. Mulai 6 Agustus 2026, layanan pindah ke namespace agen-registri. Jika Anda menggunakan AWS Agen Registri, Anda harus memperbarui titik akhir, kebijakan IAM, klien SDK, skrip CLI, dan data registri. Untuk informasi selengkapnya tentang migrasi dari pratinjau publik, lihat Panduan migrasi registri komprehensif.

Gambaran umum

Setiap registri mengekspos MCP-compatible titik akhir mengikuti spesifikasi 2025-11-25. Titik akhir mendukung daftar alat dan pemanggilan alat untuk mencari catatan registri.

https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp

MCP berisi satu alat bernama “search_registry_records”.

Tool name: search_registry_records

Description:
Searches for registry records using natural language queries. Returns metadata for matching records.

Parameters:
- searchQuery (required): string - Natural language search query
- maxResults: integer - Maximum number of results to return (1-20, default 10)
- filter: object - Optional metadata filter using structured JSON operators. Supports field-level operators ($eq, $ne,
  $in) and logical operators ($and, $or) on filterable fields (name, descriptorType, version). Example:
  {"descriptorType": {"$eq": "MCP"}}

Anda dapat terhubung ke registri dari klien MCP yang ada, seperti Kiro, Claude, dll.

Connect ke endpoint MCP OAuth-based registri dari klien MCP yang ada

Izin

Titik akhir MCP akan menggunakan hal yang sama CustomJWTAuthorizerConfigurationuntuk mengotorisasi permintaan yang masuk.

.well-known/oauth-protected-resourceJalannya adalah:https://bedrock-agentcore.<region>.amazonaws.com/.well-known/oauth-protected-resource/registry/<registryId>/mcp.

Klien juga dapat menemukan metadata dari WWW-Authenticate header:

www-authenticate: Bearer resource_metadata="https://bedrock-agentcore.<region>.amazonaws.com/.well-known/oauth-protected-resource/registry/<registryId>/mcp"

Setelah Anda mendapatkan token akses, Anda dapat memvalidasinya:

curl -s -X POST "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_registry_records","arguments":{"searchQuery":"weather"}}}'

Bergantung pada server otorisasi dan persyaratan keamanan organisasi Anda, Anda dapat memilih salah satu pendekatan berikut untuk mengonfigurasi klien MCP Anda:

  1. Token pembawa: gunakan proses terpisah untuk mengambil token pembawa dan mengkonfigurasinya di header klien MCP

  2. Pre-registered klien: buat klien di server otorisasi Anda, dan izinkan daftar klien pada konfigurasi registri.

  3. Registrasi klien dinamis: jika server otorisasi Anda mendukung pendaftaran klien dinamis (DCR), Anda dapat mengizinkan daftar audiens dalam konfigurasi registri.

OAuth-based Pengaturan klien MCP

Gunakan token pembawa

Di sebagian besar IDE, Anda dapat mengonfigurasi token pembawa header otorisasi dalam konfigurasi mcp. Misalnya, Kiro mendukung variabel lingkungan menggunakan ${ENV_VAR} sintaks. Anda dapat menggunakan contoh berikut:

{
  "mcpServers": {
    "my-registry": {
      "type": "http",
      "url": "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp",
      "headers": {
        "Authorization": "Bearer ${ACCESS_TOKEN}"
      }
    }
  }
}

Pre-registered klien

Anda dapat membuat klien baru berdasarkan hibah kode otorisasi di server otorisasi Anda, dan menggunakan klien untuk mengakses registri. Misalnya, buat klien di kumpulan pengguna Cognito.

Setelah Anda memiliki ID klien, pastikan Anda mengizinkannya di registri:

aws bedrock-agentcore-control update-registry \
  --registry-id <registryId> \
  --authorizer-configuration '{
    "optionalValue": {
      "customJWTAuthorizer": {
        "discoveryUrl": "https://<example-domain>/.well-known/openid-configuration",
        "allowedClients": ["<client-id>"]
      }
    }
  }'

Kemudian Anda dapat mengkonfigurasi klien MCP Anda jika mendukung menentukan ClientID. Contoh dalam kode Claude:

{
  "mcpServers": {
    "pre-registered-registry": {
      "type": "http",
      "url": "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp",
      "oauth": {
        "clientId": "<client-id>",
        "callbackPort": "<port-number>"
      }
    }
  }
}
catatan

Beberapa server otorisasi seperti Auth0 dan Cognito tidak mengizinkan Anda mengonfigurasi berbagai port sebagai URI pengalihan yang diizinkan, jadi Anda perlu menyetelnya secara eksplisit di URL yang diizinkan klien yang telah didaftarkan sebelumnya, serta di mcp.json. redirect/callback

Registrasi klien dinamis

Sebagian besar aplikasi klien MCP mendukung pendaftaran klien dinamis. Dalam hal ini, Anda TIDAK harus menentukan allowedClients nilai dalam registri. Sebagai gantinya, Anda dapat memilih untuk mengaturallowedAudience. Nilainya bisa sama dengan registri MCP Anda. Anda harus mengonfigurasi server otorisasi Anda untuk mengeluarkan JWT dengan aud bidang dengan nilai yang sama seperti di. allowedAudience

aws bedrock-agentcore-control update-registry \
  --registry-id <registryId> \
  --authorizer-configuration '{
    "optionalValue": {
      "customJWTAuthorizer": {
        "discoveryUrl": "https://<example-domain>/.well-known/openid-configuration",
        "allowedAudience": ["https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp"]
      }
    }
  }'

Kemudian Anda dapat mengkonfigurasi klien MCP Anda hanya menggunakan url:

{
  "mcpServers": {
    "dcr-registry": {
      "type": "http",
      "url": "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp"
    }
  }
}

Kesalahan umum saat Anda mengatur pendaftaran klien dinamis:

Connect ke endpoint MCP IAM-based registri dari klien MCP yang ada

Izin

Untuk inisialisasi MCP dan daftar alat:

{
    "Effect": "Allow",
    "Action": "bedrock-agentcore:InvokeRegistryMcp",
    "Resource": "arn:aws:bedrock-agentcore:*:<account>:registry/*"
}

Untuk mencari melalui permintaan alat MCP, Anda juga perlu:

{
    "Effect": "Allow",
    "Action":
    [
        "bedrock-agentcore:InvokeRegistryMcp",
        "bedrock-agentcore:SearchRegistryRecords"
    ],
    "Resource": "arn:aws:bedrock-agentcore:*:<account>:registry/*"
}

Anda dapat memverifikasi izin dengan perintah:

curl -s -X POST "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp" \
  -H "Content-Type: application/json" \
  -H "X-Amz-Security-Token: ${AWS_SESSION_TOKEN}" \
  --aws-sigv4 "aws:amz:<region>:bedrock-agentcore" \
  --user "${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_registry_records","arguments":{"searchQuery":"weather"}}}'

IAM-based Pengaturan klien MCP

Anda dapat menggunakan mcp-proxy-for-aws untuk terhubung ke registri. IAM-based Misalnya, di Kiro mcp.json:

{
  "mcpServers": {
    "iam-based-registry": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp",
        "--service",
        "bedrock-agentcore",
        "--region",
        "<region>",
        "--profile",
        "my-profile"
      ]
    }
  }
}

Kembangkan klien MCP Anda sendiri

Untuk referensi kode lebih lanjut tentang cara memanggil titik akhir MCP Registry, termasuk dari IDE populer seperti Kiro atau Claude Code, silakan merujuk ke referensi kode contoh di repositori kode publik.