diff --git a/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/README.md b/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/README.md new file mode 100644 index 000000000..306397814 --- /dev/null +++ b/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/README.md @@ -0,0 +1,79 @@ +# Synchronize MCP Server Metadata to AWS Agent Registry + +## Overview + +This tutorial demonstrates how to use AWS Agent Registry's URL-based synchronization to automatically extract and register MCP server metadata (server schema, tools, descriptions, and versions) from both externally hosted and AgentCore Runtime-hosted MCP servers. + +Instead of manually defining tool schemas, you provide the MCP server URL and the registry connects to the server, discovers its capabilities, and creates a registry record with the extracted metadata. + +## Getting Started + +To get started with this tutorial, open and follow the step-by-step guide in the Jupyter notebook: + +**[📓 registry_synchronize_mcpserver.ipynb](registry_synchronize_mcpserver.ipynb)** + +The notebook contains all the code examples, configurations, and detailed instructions needed to complete this tutorial. + +## What You'll Learn + +* How to list available registries and create a new registry with IAM authorization +* How to synchronize a **public unprotected** MCP server to the registry +* How to synchronize an **OAuth-protected** MCP server deployed on AgentCore Runtime +* How to synchronize an **IAM-protected** MCP server deployed on AgentCore Runtime + | +### Tutorial Architecture + +The diagram below shows how AWS Agent Registry synchronizes metadata from OAuth-protected and IAM-protected MCP Servers. + +![Registry Synchronize MCP Server Architecture](registry-synchronize-mcpserver-arch.png) + +After synchronization, the record will be created in CREATING status. After about ten seconds, the record transitions to DRAFT status and contains descriptors extracted from the MCP server, including server descriptor and tools descriptor. The registry also updates the record name, description, and version if those values are found when connecting to the MCP server. + +### Tutorial Key Features + +* URL-based synchronization (pull-based metadata extraction) +* Public MCP server synchronization +* OAuth-protected MCP server synchronization with Cognito +* IAM-protected MCP server synchronization with role-based access + +## Prerequisites + +- AWS account with IAM credentials that have permissions for AWS Agent Registry, AgentCore Runtime, Cognito, and IAM role management +- Python 3.10+ with boto3 >= 1.42.87 (with `bedrock-agentcore-control` service support) +- AWS CLI v2 configured with an appropriate profile +- `bedrock-agentcore-starter-toolkit` for deploying MCP servers to AgentCore Runtime + +## Notebook Sections + +| Section | What It Does | +|---------|--------------| +| Setup | Installs dependencies, initializes AWS session and clients, creates helper functions for waiting on async operations. | +| 1. List Registries | Lists all available registries in the account. | +| 2. Create Registry | Creates a new registry with IAM authorization and `autoApproval: False`. | +| 3. Synchronize from Public MCP Server | Synchronizes metadata from a public unprotected MCP server (e.g., AWS Knowledge MCP Server) using URL-based sync. | +| 4. Synchronize from OAuth-Protected MCP Server | Creates a Cognito user pool and OAuth provider, deploys an MCP server with JWT authorization to AgentCore Runtime, and synchronizes using OAuth credentials. | +| 5. Synchronize from IAM-Protected MCP Server | Deploys an MCP server with default IAM auth to AgentCore Runtime, creates an IAM role for registry-to-runtime invocation, and synchronizes using IAM credentials. | +| 6. List All Records | Lists all synchronized records in the registry. | +| 7. Cleanup | Deletes all created resources: registry records, registry, runtimes, OAuth providers, Cognito resources, IAM roles, and local files. | + +## AWS Services Used + +| Service | Purpose | +|---------|---------| +| **AWS Agent Registry** | Stores MCP server records with extracted tool schemas and metadata. | +| **AgentCore Runtime** | Hosts MCP servers with OAuth or IAM authentication. | +| **Amazon Cognito** | Provides OAuth2 authentication for MCP server access (client credentials flow). | +| **IAM** | Provides role-based access for registry-to-runtime invocation. | + +## Cleanup + +The notebook includes a cleanup section (Section 7) that removes all resources created during the tutorial: + +- Registry records and registry +- AgentCore Runtime deployments +- OAuth2 credential providers +- Cognito user pools and domains +- IAM roles and policies +- Local files generated by `%%writefile` + +Run the cleanup cell to avoid incurring ongoing charges. diff --git a/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/registry-synchronize-mcpserver-arch.png b/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/registry-synchronize-mcpserver-arch.png index da8cf6930..268e645fe 100644 Binary files a/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/registry-synchronize-mcpserver-arch.png and b/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/registry-synchronize-mcpserver-arch.png differ diff --git a/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/registry_synchronize_mcpserver.ipynb b/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/registry_synchronize_mcpserver.ipynb index 7a684be20..977551475 100644 --- a/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/registry_synchronize_mcpserver.ipynb +++ b/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/registry_synchronize_mcpserver.ipynb @@ -19,7 +19,7 @@ "\n", "## Architecture\n", "\n", - "![Registry Synchronize MCP Server Architecture](registry-synchronize-mcpserver-arch.png)\n", + "\"Registry\n", "\n", "After synchronization, the record will be created in CREATING status. After about ten seconds, the record would be in DRAFT status, and it will contain descriptors that extracted and converted from the MCP server, including server descriptor and tools descriptor. AWS Agent registry will also update record name, description, and version, if the values are found when connecting to MCP server.\n", "\n" @@ -111,11 +111,7 @@ }, "outputs": [], "source": [ - "!pip install boto3 \n", - "!pip install python-dotenv\n", - "!pip install \"botocore[crt]\"\n", - "%pip install requests\n", - "!pip install bedrock-agentcore-starter-toolkit" + "%pip install -r requirements.txt -q" ] }, { @@ -153,7 +149,7 @@ "from datetime import datetime\n", "\n", "# Configuration - update these for your environment\n", - "AWS_REGION = \"REGION\"\n", + "AWS_REGION = \"us-west-2\" \n", "AWS_PROFILE = \"your_aws_profile\" # Your configured AWS profile\n", "os.environ[\"AWS_PROFILE\"] = AWS_PROFILE\n", "\n", @@ -548,7 +544,7 @@ "id": "687cff3c", "metadata": {}, "source": [ - "### 4.2: Write empty requirements.txt (include for any dependencies)" + "### 4.2: Write empty server_requirements.txt (include for any dependencies)" ] }, { @@ -558,7 +554,7 @@ "metadata": {}, "outputs": [], "source": [ - "%%writefile requirements.txt\n", + "%%writefile server_requirements.txt\n", "# No external dependencies - uses Python stdlib only" ] }, @@ -680,7 +676,7 @@ " entrypoint=\"it_ops_toolkit.py\",\n", " auto_create_execution_role=True,\n", " auto_create_ecr=True,\n", - " requirements_file=\"requirements.txt\",\n", + " requirements_file=\"server_requirements.txt\",\n", " region=AWS_REGION,\n", " authorizer_configuration=auth_config,\n", " protocol=\"MCP\",\n", @@ -950,7 +946,7 @@ "id": "8b73506d", "metadata": {}, "source": [ - "### 5.2: Write requirements.txt" + "### 5.2: Write server_requirements.txt" ] }, { @@ -960,7 +956,7 @@ "metadata": {}, "outputs": [], "source": [ - "%%writefile requirements.txt\n", + "%%writefile server_requirements.txt\n", "# No external dependencies - uses Python stdlib only" ] }, @@ -991,7 +987,7 @@ " entrypoint=\"ecommerce_order_toolkit.py\",\n", " auto_create_execution_role=True,\n", " auto_create_ecr=True,\n", - " requirements_file=\"requirements.txt\",\n", + " requirements_file=\"server_requirements.txt\",\n", " region=AWS_REGION,\n", " protocol=\"MCP\",\n", " agent_name=f\"ecom_order_iam_{TIMESTAMP}\"\n", @@ -1228,7 +1224,7 @@ "\n", "# ── Delete local files created by %%writefile ───────────────────────────\n", "for f in [ \"ecommerce_order_toolkit.py\", \n", - " \"it_ops_toolkit.py\",\"requirements.txt\", \"Dockerfile\"]:\n", + " \"it_ops_toolkit.py\",\"server_requirements.txt\", \"Dockerfile\"]:\n", " if os.path.exists(f):\n", " os.remove(f)\n", " print(f\"✓ Deleted local file: {f}\")\n", diff --git a/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/requirements.txt b/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/requirements.txt new file mode 100644 index 000000000..6f06bc999 --- /dev/null +++ b/01-tutorials/10-Agent-Registry/01-advanced/registry-synchronize-mcpserver/requirements.txt @@ -0,0 +1,5 @@ +boto3>=1.42.87 +botocore>=1.42.87 +requests>=2.31.0 +python-dotenv>=1.0.0 +bedrock-agentcore-starter-toolkit>=0.1.21