From c2b357e57f244a69be2912e913e469f498016329 Mon Sep 17 00:00:00 2001 From: Jiaping Zeng Date: Mon, 4 Aug 2025 13:53:50 -0700 Subject: [PATCH 1/8] initial draft Signed-off-by: Jiaping Zeng --- ...earch-MCP-server-with-Bedrock-AgentCore.md | 283 ++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 _posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md diff --git a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md new file mode 100644 index 0000000000..974bcde5d2 --- /dev/null +++ b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md @@ -0,0 +1,283 @@ +--- +layout: post +title: "Hosting OpenSearch MCP Server with Amazon Bedrock AgentCore" +authors: + - jiapingzeng +date: 2025-08-04 +categories: + - technical-post +meta_keywords: "MCP, Agentic, Agent, Model context protocol, MCP server, LLM integration, observability agent, Bedrock AgentCore, hosted MCP server" +meta_description: "Learn how to deploy OpenSearch MCP Server with Amazon Bedrock AgentCore Runtime." +--- + +The [OpenSearch MCP Server](https://github.com/opensearch-project/opensearch-mcp-server-py) enables AI agents to interact with OpenSearch clusters through the Model Context Protocol (MCP). While you can run it locally, hosting it on AWS Bedrock AgentCore Runtime provides a scalable, managed solution that's accessible from anywhere. + +In this post, we'll walk through two approaches to deploy the OpenSearch MCP Server on Bedrock AgentCore: using a CloudFormation template for quick setup, or manually configuring it with the AgentCore CLI. + +## Prerequisites + +Before we begin, ensure you have: +- An OpenSearch cluster +- Access to one of the supported Bedrock AgentCore regions: `us-east-1`, `us-west-2`, `eu-west-1`, or `ap-southeast-2` + +**Note**: While Bedrock AgentCore is only available in these four regions, your MCP server can connect to OpenSearch clusters in other regions over the public internet. + +## Method 1: Using CloudFormation Template (available for Amazon OpenSearch Service users) + +The fastest way to get started is with the OpenSearch MCP Server CloudFormation template, which automatically provisions all necessary resources. + +### Deploying the Template + +The CloudFormation template requires these parameters: + +**Required:** +- **Agent Name**: Name for your MCP server +- **OpenSearch Endpoint**: Your cluster's endpoint URL +- **OpenSearch Region**: The AWS region where your cluster is located + +**Optional:** +- **DiscoveryUrl, AllowedClients, AllowedAudience**: OAuth2 configuration. If not provided, the template creates Cognito resources automatically +- **ECR Repository**: For storing the container image, auto-created if not specified +- **Execution Role**: IAM role for AgentCore Runtime, auto-created with proper permissions if not specified + +### Understanding the Outputs + +Once deployment completes, you'll find these key outputs: + +- **AgentArn**: The ARN of your Bedrock AgentCore Runtime +- **DiscoveryURL**: OAuth discovery endpoint +- **TokenEndpoint**: Token endpoint obtained from your discovery endpoint +- **McpUrl**: The URL of your hosted MCP server + +### Obtaining an Access Token + +To use your MCP server, you'll need a JWT token from the OAuth authorizer. If you used the auto-created Cognito setup: + +1. Navigate to the CloudFormation Resources tab +2. Find `CognitoUserPool` and click its Physical ID +3. Go to "App clients" and note the Client ID and Client Secret + +Then obtain a token: + +```bash +export TOKEN_ENDPOINT="" +export CLIENT_ID="" +export CLIENT_SECRET="" + +curl --http1.1 -X POST $TOKEN_ENDPOINT \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET" +``` + +Sample response: +```json +{"access_token":"xxxxx","expires_in":3600,"token_type":"Bearer"} +``` + +**Note**: Cognito tokens expire every 60 minutes by default. + +## Method 2: Using Bedrock AgentCore CLI + +You can also use the AgentCore CLI directly. + +### Creating the MCP Server Code + +First, create your MCP server implementation: + +**opensearch_mcp_server.py** +```python +from mcp_server_opensearch import streaming_server +import asyncio +import os + +os.environ["OPENSEARCH_URL"] = "https://your-opensearch-endpoint.com" +os.environ["AWS_REGION"] = "us-east-1" + +if __name__ == "__main__": + asyncio.run(streaming_server.serve(port=8000, host="0.0.0.0", stateless=True)) +``` + +**Important Notes:** +1. `stateless=True` is necessary for AgentCore Runtime. OpenSearch MCP server currently defaults to `stateless=False`. As a workaround, clone the repo and make these changes: https://github.com/opensearch-project/opensearch-mcp-server-py/pull/86/files + +2. `AWS_REGION` here is optional if the OpenSearch cluster and AgentCore runtime are in the same region. The Dockerfile generated by AgentCore will have `AWS_REGION` as an environment variable. + +**requirements.txt** +``` +opensearch-mcp-server-py +``` + +With the workaround mentioned in note 1, you'll need to add the dependencies of opensearch-mcp-server-py directly instead: + +**requirements.txt (with workaround)** +``` +aiohttp>=3.11.18 +boto3>=1.38.3 +mcp[cli]>=1.9.4 +opensearch-py>=2.8.0 +pydantic>=2.11.3 +pyyaml>=6.0.2 +requests-aws4auth>=1.3.1 +semver>=3.0.4 +``` + +### Setting Up OAuth (Optional) + +If you don't have an existing OAuth authorizer, create one using Amazon Cognito following the [Bedrock AgentCore documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html#runtime-mcp-appendix). + +### Configuring AgentCore Deployment + +Install the AgentCore toolkit: + +```bash +pip install bedrock-agentcore-starter-toolkit +``` + +Configure your deployment: + +```bash +agentcore configure -e opensearch_mcp_server.py --protocol MCP +``` + +Follow the prompts to: +- Auto-create execution role (or specify existing) +- Auto-create ECR repository (or specify existing) +- Select your requirements.txt file +- Configure OAuth authorizer with discovery URL and client ID + +### Deploying to AgentCore Runtime + +Deploy your MCP server: + +```bash +agentcore launch +``` + +After successful deployment, generate your MCP server URL: + +```bash +export AWS_REGION="" +export AGENT_ARN="" +export ENCODED_AGENT_ARN=$(echo $AGENT_ARN | sed 's/:/%3A/g; s/\//%2F/g') +echo "https://bedrock-agentcore.$AWS_REGION.amazonaws.com/runtimes/$ENCODED_AGENT_ARN/invocations?qualifier=DEFAULT" +``` + +## Configuring OpenSearch Access + +Regardless of which deployment method you used, you need to map your AgentCore execution role to an OpenSearch backend role so the MCP server can access your data. + +Follow the [OpenSearch fine-grained access control guide](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html#fgac-access-control) to configure the appropriate backend role mapping. + +## Using Your Hosted MCP Server + +### Testing with Q Developer CLI + +The easiest way to test your MCP server is with Amazon Q Developer CLI. Configure `~/.aws/amazonq/mcp.json`: + +```json +{ + "mcpServers": { + "opensearch-mcp-server": { + "command": "mcp-proxy", + "timeout": 60000, + "args": [ + "", + "--transport", + "streamablehttp" + ], + "env": { + "API_ACCESS_TOKEN": "" + } + } + } +} +``` + +Start Q Developer CLI: + +```bash +$ q +✓ opensearch-mcp-server loaded in 3.22 s +``` + +Verify the tools are available: + +```bash +> /tools + +Tool Permission +Built-in: +- execute_bash * trust read-only commands +- fs_read * trusted +- fs_write * not trusted +- report_issue * trusted +- use_aws * trust read-only commands + +opensearch-mcp-server (MCP): +- ClusterHealthTool * not trusted +- CountTool * not trusted +- ExplainTool * not trusted +- GetShardsTool * not trusted +- IndexMappingTool * not trusted +- ListIndexTool * not trusted +- MsearchTool * not trusted +- SearchIndexTool * not trusted +``` + +Now you can ask questions about your OpenSearch data! For examples of what you can do, check out our previous blog post: [Unlocking Agentic AI Experiences with OpenSearch](https://opensearch.org/blog/unlocking-agentic-ai-experiences-with-opensearch/). + +### Using with Custom Agents + +You can integrate your hosted MCP server with any MCP-compatible agent. Here's an example using the Strands Agent framework: + +```python +import os +import requests +from strands import Agent +from strands.tools.mcp import MCPClient +from mcp.client.streamable_http import streamablehttp_client + +def get_bearer_token(discovery_url: str, client_id: str, client_secret: str): + response = requests.get(discovery_url) + discovery_data = response.json() + token_endpoint = discovery_data['token_endpoint'] + + data = { + 'grant_type': 'client_credentials', + 'client_id': client_id, + 'client_secret': client_secret + } + headers = { + 'Content-Type': 'application/x-www-form-urlencoded' + } + + response = requests.post(token_endpoint, data=data, headers=headers) + token_data = response.json() + return token_data['access_token'] + +if __name__ == "__main__": + discovery_url = os.environ["DISCOVERY_URL"] + client_id = os.environ["CLIENT_ID"] + client_secret = os.environ["CLIENT_SECRET"] + mcp_url = os.environ["MCP_URL"] + + bearer_token = get_bearer_token(discovery_url, client_id, client_secret) + + opensearch_mcp_client = MCPClient(lambda: streamablehttp_client(mcp_url, { + "authorization": f"Bearer {bearer_token}", + "Content-Type": "application/json" + })) + + with opensearch_mcp_client: + tools = opensearch_mcp_client.list_tools_sync() + agent = Agent(tools=tools) + agent("list indices") +``` + +## Conclusion + +Hosting your OpenSearch MCP Server on AWS Bedrock AgentCore Runtime provides a scalable, managed solution for integrating OpenSearch with AI agents. Whether you choose the quick CloudFormation deployment or the CLI approach, you'll have a robust, cloud-hosted MCP server that can serve multiple agents and applications. + +The hosted approach eliminates the need to manage infrastructure while providing enterprise-grade security through OAuth authentication and fine-grained access controls. This makes it ideal for production deployments where you need reliable, scalable access to your OpenSearch data from AI agents. + +Ready to get started? Try the CloudFormation template for the fastest setup, or use the CLI method if you need more control over your deployment configuration. From 2772764dcc8cf99be60acfaca43c7a68de748bd0 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Tue, 12 Aug 2025 16:30:56 -0400 Subject: [PATCH 2/8] Doc review Signed-off-by: Fanit Kolchina --- ...earch-MCP-server-with-Bedrock-AgentCore.md | 86 ++++++++++--------- 1 file changed, 44 insertions(+), 42 deletions(-) diff --git a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md index 974bcde5d2..7430307b0b 100644 --- a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md +++ b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md @@ -10,13 +10,14 @@ meta_keywords: "MCP, Agentic, Agent, Model context protocol, MCP server, LLM int meta_description: "Learn how to deploy OpenSearch MCP Server with Amazon Bedrock AgentCore Runtime." --- -The [OpenSearch MCP Server](https://github.com/opensearch-project/opensearch-mcp-server-py) enables AI agents to interact with OpenSearch clusters through the Model Context Protocol (MCP). While you can run it locally, hosting it on AWS Bedrock AgentCore Runtime provides a scalable, managed solution that's accessible from anywhere. +The [OpenSearch MCP Server](https://github.com/opensearch-project/opensearch-mcp-server-py) enables AI agents to interact with OpenSearch clusters through the Model Context Protocol (MCP). While you can run the OpenSearch MCP Server locally, hosting it on AWS Bedrock AgentCore Runtime provides a scalable, managed solution that's accessible from anywhere. -In this post, we'll walk through two approaches to deploy the OpenSearch MCP Server on Bedrock AgentCore: using a CloudFormation template for quick setup, or manually configuring it with the AgentCore CLI. +In this post, we'll walk through two approaches to deploy the OpenSearch MCP Server on Bedrock AgentCore: using a CloudFormation template for a quick setup and manually configuring it using the AgentCore CLI. ## Prerequisites -Before we begin, ensure you have: +Before you begin, ensure that you have the following: + - An OpenSearch cluster - Access to one of the supported Bedrock AgentCore regions: `us-east-1`, `us-west-2`, `eu-west-1`, or `ap-southeast-2` @@ -24,38 +25,38 @@ Before we begin, ensure you have: ## Method 1: Using CloudFormation Template (available for Amazon OpenSearch Service users) -The fastest way to get started is with the OpenSearch MCP Server CloudFormation template, which automatically provisions all necessary resources. +The fastest way to get started is to use the OpenSearch MCP Server CloudFormation template, which automatically provisions all necessary resources. -### Deploying the Template +### Deploying the template The CloudFormation template requires these parameters: **Required:** -- **Agent Name**: Name for your MCP server -- **OpenSearch Endpoint**: Your cluster's endpoint URL -- **OpenSearch Region**: The AWS region where your cluster is located +- **Agent Name**: A name for your MCP server. +- **OpenSearch Endpoint**: Your cluster's endpoint URL. +- **OpenSearch Region**: The AWS region where your cluster is located. **Optional:** -- **DiscoveryUrl, AllowedClients, AllowedAudience**: OAuth2 configuration. If not provided, the template creates Cognito resources automatically -- **ECR Repository**: For storing the container image, auto-created if not specified -- **Execution Role**: IAM role for AgentCore Runtime, auto-created with proper permissions if not specified +- **DiscoveryUrl, AllowedClients, AllowedAudience**: OAuth2 configuration. If not provided, the template creates Cognito resources automatically. +- **ECR Repository**: For storing the container image, auto-created if not specified. +- **Execution Role**: An IAM role for AgentCore Runtime, auto-created with proper permissions if not specified. -### Understanding the Outputs +### Understanding the outputs -Once deployment completes, you'll find these key outputs: +Once deployment completes, it produces these key outputs: -- **AgentArn**: The ARN of your Bedrock AgentCore Runtime -- **DiscoveryURL**: OAuth discovery endpoint -- **TokenEndpoint**: Token endpoint obtained from your discovery endpoint -- **McpUrl**: The URL of your hosted MCP server +- **AgentArn**: The ARN of your Bedrock AgentCore Runtime. +- **DiscoveryURL**: The OAuth discovery endpoint. +- **TokenEndpoint**: The token endpoint obtained from your discovery endpoint. +- **McpUrl**: The URL of your hosted MCP server. -### Obtaining an Access Token +### Obtaining an access token -To use your MCP server, you'll need a JWT token from the OAuth authorizer. If you used the auto-created Cognito setup: +To use your MCP server, you'll need a JWT token from the OAuth authorizer. If you used the auto-created Cognito setup, follow these steps to obtain the token: -1. Navigate to the CloudFormation Resources tab -2. Find `CognitoUserPool` and click its Physical ID -3. Go to "App clients" and note the Client ID and Client Secret +1. Navigate to the **CloudFormation Resources** tab. +2. Find **CognitoUserPool** and select its **Physical ID**. +3. Go to **App clients** and note the **Client ID** and **Client Secret**. Then obtain a token: @@ -69,7 +70,8 @@ curl --http1.1 -X POST $TOKEN_ENDPOINT \ -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET" ``` -Sample response: +The response contains the token: + ```json {"access_token":"xxxxx","expires_in":3600,"token_type":"Bearer"} ``` @@ -80,7 +82,7 @@ Sample response: You can also use the AgentCore CLI directly. -### Creating the MCP Server Code +### Creating the MCP Server code First, create your MCP server implementation: @@ -98,16 +100,16 @@ if __name__ == "__main__": ``` **Important Notes:** -1. `stateless=True` is necessary for AgentCore Runtime. OpenSearch MCP server currently defaults to `stateless=False`. As a workaround, clone the repo and make these changes: https://github.com/opensearch-project/opensearch-mcp-server-py/pull/86/files +1. `stateless=True` is necessary for AgentCore Runtime. OpenSearch MCP server currently defaults to `stateless=False`. As a workaround, clone the repo and make the changes described in [this pull request](https://github.com/opensearch-project/opensearch-mcp-server-py/pull/86/files). -2. `AWS_REGION` here is optional if the OpenSearch cluster and AgentCore runtime are in the same region. The Dockerfile generated by AgentCore will have `AWS_REGION` as an environment variable. +2. `AWS_REGION` is optional if the OpenSearch cluster and AgentCore runtime are in the same region. The Dockerfile generated by AgentCore will have `AWS_REGION` as an environment variable. **requirements.txt** ``` opensearch-mcp-server-py ``` -With the workaround mentioned in note 1, you'll need to add the dependencies of opensearch-mcp-server-py directly instead: +With the workaround mentioned in Note 1, you'll need to add the dependencies of opensearch-mcp-server-py directly instead: **requirements.txt (with workaround)** ``` @@ -121,11 +123,11 @@ requests-aws4auth>=1.3.1 semver>=3.0.4 ``` -### Setting Up OAuth (Optional) +### Setting up OAuth (Optional) -If you don't have an existing OAuth authorizer, create one using Amazon Cognito following the [Bedrock AgentCore documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html#runtime-mcp-appendix). +If you don't have an existing OAuth authorizer, create one using Amazon Cognito by following the [Bedrock AgentCore documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html#runtime-mcp-appendix). -### Configuring AgentCore Deployment +### Configuring AgentCore deployment Install the AgentCore toolkit: @@ -139,13 +141,13 @@ Configure your deployment: agentcore configure -e opensearch_mcp_server.py --protocol MCP ``` -Follow the prompts to: -- Auto-create execution role (or specify existing) -- Auto-create ECR repository (or specify existing) -- Select your requirements.txt file -- Configure OAuth authorizer with discovery URL and client ID +Follow the prompts to perform the following actions: +- Auto-create an execution role (or specify an existing one) +- Auto-create an ECR repository (or specify an existing one) +- Select your `requirements.txt` file +- Configure the OAuth authorizer with the discovery URL and client ID -### Deploying to AgentCore Runtime +### Deploying to AgentCore runtime Deploy your MCP server: @@ -162,9 +164,9 @@ export ENCODED_AGENT_ARN=$(echo $AGENT_ARN | sed 's/:/%3A/g; s/\//%2F/g') echo "https://bedrock-agentcore.$AWS_REGION.amazonaws.com/runtimes/$ENCODED_AGENT_ARN/invocations?qualifier=DEFAULT" ``` -## Configuring OpenSearch Access +## Configuring OpenSearch access -Regardless of which deployment method you used, you need to map your AgentCore execution role to an OpenSearch backend role so the MCP server can access your data. +Regardless of the deployment method you used, you need to map your AgentCore execution role to an OpenSearch backend role so the MCP server can access your data. Follow the [OpenSearch fine-grained access control guide](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html#fgac-access-control) to configure the appropriate backend role mapping. @@ -200,7 +202,7 @@ $ q ✓ opensearch-mcp-server loaded in 3.22 s ``` -Verify the tools are available: +Verify that the tools are available: ```bash > /tools @@ -224,9 +226,9 @@ opensearch-mcp-server (MCP): - SearchIndexTool * not trusted ``` -Now you can ask questions about your OpenSearch data! For examples of what you can do, check out our previous blog post: [Unlocking Agentic AI Experiences with OpenSearch](https://opensearch.org/blog/unlocking-agentic-ai-experiences-with-opensearch/). +Now you can ask questions about your OpenSearch data! For examples of what you can do, check out [Unlocking Agentic AI Experiences with OpenSearch](https://opensearch.org/blog/unlocking-agentic-ai-experiences-with-opensearch/). -### Using with Custom Agents +### Using custom agents You can integrate your hosted MCP server with any MCP-compatible agent. Here's an example using the Strands Agent framework: @@ -278,6 +280,6 @@ if __name__ == "__main__": Hosting your OpenSearch MCP Server on AWS Bedrock AgentCore Runtime provides a scalable, managed solution for integrating OpenSearch with AI agents. Whether you choose the quick CloudFormation deployment or the CLI approach, you'll have a robust, cloud-hosted MCP server that can serve multiple agents and applications. -The hosted approach eliminates the need to manage infrastructure while providing enterprise-grade security through OAuth authentication and fine-grained access controls. This makes it ideal for production deployments where you need reliable, scalable access to your OpenSearch data from AI agents. +The hosted approach eliminates the need to manage infrastructure while providing enterprise-grade security through OAuth authentication and fine-grained access control. This makes it ideal for production deployments where you need reliable, scalable access to your OpenSearch data from AI agents. Ready to get started? Try the CloudFormation template for the fastest setup, or use the CLI method if you need more control over your deployment configuration. From e06456d55e1acd5fb1e014d749e293cdb3ac1542 Mon Sep 17 00:00:00 2001 From: Jiaping Zeng Date: Fri, 15 Aug 2025 01:02:42 -0700 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: Jiaping Zeng --- ...earch-MCP-server-with-Bedrock-AgentCore.md | 74 +++++++++---------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md index 7430307b0b..8ea7fc0bfa 100644 --- a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md +++ b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md @@ -1,51 +1,51 @@ --- layout: post -title: "Hosting OpenSearch MCP Server with Amazon Bedrock AgentCore" +title: "Hosting the OpenSearch MCP server with Amazon Bedrock AgentCore" authors: - jiapingzeng date: 2025-08-04 categories: - technical-post meta_keywords: "MCP, Agentic, Agent, Model context protocol, MCP server, LLM integration, observability agent, Bedrock AgentCore, hosted MCP server" -meta_description: "Learn how to deploy OpenSearch MCP Server with Amazon Bedrock AgentCore Runtime." +meta_description: "Learn how to deploy the OpenSearch MCP server with Amazon Bedrock AgentCore Runtime." --- The [OpenSearch MCP Server](https://github.com/opensearch-project/opensearch-mcp-server-py) enables AI agents to interact with OpenSearch clusters through the Model Context Protocol (MCP). While you can run the OpenSearch MCP Server locally, hosting it on AWS Bedrock AgentCore Runtime provides a scalable, managed solution that's accessible from anywhere. -In this post, we'll walk through two approaches to deploy the OpenSearch MCP Server on Bedrock AgentCore: using a CloudFormation template for a quick setup and manually configuring it using the AgentCore CLI. +In this post, we'll walk you through two approaches to deploying the OpenSearch MCP server on Bedrock AgentCore: using an AWS CloudFormation template for a quick setup and manually configuring it using the AgentCore CLI. ## Prerequisites Before you begin, ensure that you have the following: - An OpenSearch cluster -- Access to one of the supported Bedrock AgentCore regions: `us-east-1`, `us-west-2`, `eu-west-1`, or `ap-southeast-2` +- Access to one of the supported Bedrock AgentCore Regions: `us-east-1`, `us-west-2`, `eu-west-1`, or `ap-southeast-2` -**Note**: While Bedrock AgentCore is only available in these four regions, your MCP server can connect to OpenSearch clusters in other regions over the public internet. +**Note**: While Bedrock AgentCore is only available in these four AWS Regions, your MCP server can connect to OpenSearch clusters in other Regions over the public internet. -## Method 1: Using CloudFormation Template (available for Amazon OpenSearch Service users) +## Method 1: Using a CloudFormation template (available to Amazon OpenSearch Service users) -The fastest way to get started is to use the OpenSearch MCP Server CloudFormation template, which automatically provisions all necessary resources. +The fastest way to get started is to use the OpenSearch MCP server CloudFormation template, which automatically provisions all necessary resources. ### Deploying the template The CloudFormation template requires these parameters: -**Required:** -- **Agent Name**: A name for your MCP server. -- **OpenSearch Endpoint**: Your cluster's endpoint URL. -- **OpenSearch Region**: The AWS region where your cluster is located. +**Required**: +- **Agent name**: A name for your MCP server. +- **OpenSearch endpoint**: Your cluster's endpoint URL. +- **OpenSearch Region**: The AWS Region in which your cluster is located. -**Optional:** -- **DiscoveryUrl, AllowedClients, AllowedAudience**: OAuth2 configuration. If not provided, the template creates Cognito resources automatically. -- **ECR Repository**: For storing the container image, auto-created if not specified. -- **Execution Role**: An IAM role for AgentCore Runtime, auto-created with proper permissions if not specified. +**Optional**: +- **DiscoveryUrl, AllowedClients, AllowedAudience**: OAuth 2.0 configuration. If not provided, the template creates Amazon Cognito resources automatically. +- **Amazon Elastic Container Registry (Amazon ECR) repository**: Used to store the container image; auto-created if not specified. +- **Execution role**: An AWS Identity and Access Management (IAM) role for AgentCore Runtime; auto-created with proper permissions if not specified. ### Understanding the outputs Once deployment completes, it produces these key outputs: -- **AgentArn**: The ARN of your Bedrock AgentCore Runtime. +- **AgentArn**: The Amazon Resource Name (ARN) of your Bedrock AgentCore Runtime. - **DiscoveryURL**: The OAuth discovery endpoint. - **TokenEndpoint**: The token endpoint obtained from your discovery endpoint. - **McpUrl**: The URL of your hosted MCP server. @@ -78,11 +78,11 @@ The response contains the token: **Note**: Cognito tokens expire every 60 minutes by default. -## Method 2: Using Bedrock AgentCore CLI +## Method 2: Using the Bedrock AgentCore CLI -You can also use the AgentCore CLI directly. +You can also use the Bedrock AgentCore CLI directly. -### Creating the MCP Server code +### Creating the MCP server code First, create your MCP server implementation: @@ -99,17 +99,17 @@ if __name__ == "__main__": asyncio.run(streaming_server.serve(port=8000, host="0.0.0.0", stateless=True)) ``` -**Important Notes:** -1. `stateless=True` is necessary for AgentCore Runtime. OpenSearch MCP server currently defaults to `stateless=False`. As a workaround, clone the repo and make the changes described in [this pull request](https://github.com/opensearch-project/opensearch-mcp-server-py/pull/86/files). +**Important notes**: +1. `stateless=True` is required for AgentCore Runtime. OpenSearch MCP server currently defaults to `stateless=False`. As a workaround, clone the repo and make the changes described in [this pull request](https://github.com/opensearch-project/opensearch-mcp-server-py/pull/86/files). -2. `AWS_REGION` is optional if the OpenSearch cluster and AgentCore runtime are in the same region. The Dockerfile generated by AgentCore will have `AWS_REGION` as an environment variable. +2. `AWS_REGION` is optional if the OpenSearch cluster and AgentCore Runtime are in the same Region. The Dockerfile generated by AgentCore will have `AWS_REGION` as an environment variable. **requirements.txt** ``` opensearch-mcp-server-py ``` -With the workaround mentioned in Note 1, you'll need to add the dependencies of opensearch-mcp-server-py directly instead: +With the workaround mentioned in Note 1, you'll instead need to add the dependencies of `opensearch-mcp-server-py` directly: **requirements.txt (with workaround)** ``` @@ -125,7 +125,7 @@ semver>=3.0.4 ### Setting up OAuth (Optional) -If you don't have an existing OAuth authorizer, create one using Amazon Cognito by following the [Bedrock AgentCore documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html#runtime-mcp-appendix). +If you don't have an existing OAuth authorizer, create one using Amazon Cognito by following the instructions provided in the [Bedrock AgentCore documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp.html#runtime-mcp-appendix). ### Configuring AgentCore deployment @@ -142,12 +142,12 @@ agentcore configure -e opensearch_mcp_server.py --protocol MCP ``` Follow the prompts to perform the following actions: -- Auto-create an execution role (or specify an existing one) -- Auto-create an ECR repository (or specify an existing one) -- Select your `requirements.txt` file -- Configure the OAuth authorizer with the discovery URL and client ID +- Auto-create an execution role (or specify an existing one). +- Auto-create an ECR repository (or specify an existing one). +- Select your `requirements.txt` file. +- Configure the OAuth authorizer with the discovery URL and client ID. -### Deploying to AgentCore runtime +### Deploying to AgentCore Runtime Deploy your MCP server: @@ -168,13 +168,13 @@ echo "https://bedrock-agentcore.$AWS_REGION.amazonaws.com/runtimes/$ENCODED_AGEN Regardless of the deployment method you used, you need to map your AgentCore execution role to an OpenSearch backend role so the MCP server can access your data. -Follow the [OpenSearch fine-grained access control guide](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html#fgac-access-control) to configure the appropriate backend role mapping. +Follow the instructions provided at [Fine-grained access control in Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html#fgac-access-control) to configure the appropriate backend role mapping. -## Using Your Hosted MCP Server +## Using Your Hosted MCP server -### Testing with Q Developer CLI +### Testing with the Amazon Q Developer CLI -The easiest way to test your MCP server is with Amazon Q Developer CLI. Configure `~/.aws/amazonq/mcp.json`: +The easiest way to test your MCP server is with the Amazon Q Developer CLI. Configure `~/.aws/amazonq/mcp.json`: ```json { @@ -195,7 +195,7 @@ The easiest way to test your MCP server is with Amazon Q Developer CLI. Configur } ``` -Start Q Developer CLI: +Start the Amazon Q Developer CLI: ```bash $ q @@ -226,11 +226,11 @@ opensearch-mcp-server (MCP): - SearchIndexTool * not trusted ``` -Now you can ask questions about your OpenSearch data! For examples of what you can do, check out [Unlocking Agentic AI Experiences with OpenSearch](https://opensearch.org/blog/unlocking-agentic-ai-experiences-with-opensearch/). +Now you can ask questions about your OpenSearch data! For examples of what you can do, check out the blog post [Unlocking agentic AI experiences with OpenSearch](https://opensearch.org/blog/unlocking-agentic-ai-experiences-with-opensearch/). ### Using custom agents -You can integrate your hosted MCP server with any MCP-compatible agent. Here's an example using the Strands Agent framework: +You can integrate your hosted MCP server with any MCP-compatible agent. Here's an example using the Strands Agents framework: ```python import os @@ -278,7 +278,7 @@ if __name__ == "__main__": ## Conclusion -Hosting your OpenSearch MCP Server on AWS Bedrock AgentCore Runtime provides a scalable, managed solution for integrating OpenSearch with AI agents. Whether you choose the quick CloudFormation deployment or the CLI approach, you'll have a robust, cloud-hosted MCP server that can serve multiple agents and applications. +Hosting your OpenSearch MCP server on Amazon Bedrock AgentCore Runtime provides a scalable, managed solution for integrating OpenSearch with AI agents. Whether you choose the quick CloudFormation deployment or the CLI approach, you'll have a robust, cloud-hosted MCP server that can serve multiple agents and applications. The hosted approach eliminates the need to manage infrastructure while providing enterprise-grade security through OAuth authentication and fine-grained access control. This makes it ideal for production deployments where you need reliable, scalable access to your OpenSearch data from AI agents. From 178cbc618e731563fe5e204b01659c8eb7c38120 Mon Sep 17 00:00:00 2001 From: Jiaping Zeng Date: Fri, 15 Aug 2025 01:05:09 -0700 Subject: [PATCH 4/8] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: Jiaping Zeng --- ...8-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md index 8ea7fc0bfa..609ae19ecd 100644 --- a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md +++ b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md @@ -10,7 +10,7 @@ meta_keywords: "MCP, Agentic, Agent, Model context protocol, MCP server, LLM int meta_description: "Learn how to deploy the OpenSearch MCP server with Amazon Bedrock AgentCore Runtime." --- -The [OpenSearch MCP Server](https://github.com/opensearch-project/opensearch-mcp-server-py) enables AI agents to interact with OpenSearch clusters through the Model Context Protocol (MCP). While you can run the OpenSearch MCP Server locally, hosting it on AWS Bedrock AgentCore Runtime provides a scalable, managed solution that's accessible from anywhere. +The [OpenSearch MCP server](https://github.com/opensearch-project/opensearch-mcp-server-py) enables AI agents to interact with OpenSearch clusters through the Model Context Protocol (MCP). While you can run the OpenSearch MCP server locally, hosting it on Amazon Bedrock AgentCore Runtime provides a scalable, managed solution that's accessible from anywhere. In this post, we'll walk you through two approaches to deploying the OpenSearch MCP server on Bedrock AgentCore: using an AWS CloudFormation template for a quick setup and manually configuring it using the AgentCore CLI. From 3360c018f366bdd1e0da2e5d5c418f8d1e767ec7 Mon Sep 17 00:00:00 2001 From: Jiaping Zeng Date: Fri, 15 Aug 2025 10:55:10 -0700 Subject: [PATCH 5/8] update variable names, removed workaround section Signed-off-by: Jiaping Zeng --- ...earch-MCP-server-with-Bedrock-AgentCore.md | 30 +++++-------------- 1 file changed, 7 insertions(+), 23 deletions(-) diff --git a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md index 609ae19ecd..ab4612d76e 100644 --- a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md +++ b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md @@ -37,18 +37,17 @@ The CloudFormation template requires these parameters: - **OpenSearch Region**: The AWS Region in which your cluster is located. **Optional**: -- **DiscoveryUrl, AllowedClients, AllowedAudience**: OAuth 2.0 configuration. If not provided, the template creates Amazon Cognito resources automatically. - **Amazon Elastic Container Registry (Amazon ECR) repository**: Used to store the container image; auto-created if not specified. - **Execution role**: An AWS Identity and Access Management (IAM) role for AgentCore Runtime; auto-created with proper permissions if not specified. +- **OAuth Discovery URL, Allowed Clients IDs, Allowed Audience**: OAuth 2.0 configuration. If not provided, the template creates Amazon Cognito resources automatically. ### Understanding the outputs Once deployment completes, it produces these key outputs: -- **AgentArn**: The Amazon Resource Name (ARN) of your Bedrock AgentCore Runtime. -- **DiscoveryURL**: The OAuth discovery endpoint. +- **AgentCoreArn**: The Amazon Resource Name (ARN) of your Bedrock AgentCore Runtime. - **TokenEndpoint**: The token endpoint obtained from your discovery endpoint. -- **McpUrl**: The URL of your hosted MCP server. +- **MCPServerEndpoint**: The URL of your hosted MCP server. ### Obtaining an access token @@ -99,28 +98,11 @@ if __name__ == "__main__": asyncio.run(streaming_server.serve(port=8000, host="0.0.0.0", stateless=True)) ``` -**Important notes**: -1. `stateless=True` is required for AgentCore Runtime. OpenSearch MCP server currently defaults to `stateless=False`. As a workaround, clone the repo and make the changes described in [this pull request](https://github.com/opensearch-project/opensearch-mcp-server-py/pull/86/files). - -2. `AWS_REGION` is optional if the OpenSearch cluster and AgentCore Runtime are in the same Region. The Dockerfile generated by AgentCore will have `AWS_REGION` as an environment variable. +Note: `AWS_REGION` is optional if the OpenSearch cluster and AgentCore Runtime are in the same Region. The Dockerfile generated by AgentCore will have `AWS_REGION` as an environment variable. **requirements.txt** ``` -opensearch-mcp-server-py -``` - -With the workaround mentioned in Note 1, you'll instead need to add the dependencies of `opensearch-mcp-server-py` directly: - -**requirements.txt (with workaround)** -``` -aiohttp>=3.11.18 -boto3>=1.38.3 -mcp[cli]>=1.9.4 -opensearch-py>=2.8.0 -pydantic>=2.11.3 -pyyaml>=6.0.2 -requests-aws4auth>=1.3.1 -semver>=3.0.4 +opensearch-mcp-server-py>=0.3.1 ``` ### Setting up OAuth (Optional) @@ -172,6 +154,8 @@ Follow the instructions provided at [Fine-grained access control in Amazon OpenS ## Using Your Hosted MCP server +The following sections show you how to test and use your new hosted MCP server. + ### Testing with the Amazon Q Developer CLI The easiest way to test your MCP server is with the Amazon Q Developer CLI. Configure `~/.aws/amazonq/mcp.json`: From 047c0c81ee65ea7ed189d8631b734e0064b8ea6f Mon Sep 17 00:00:00 2001 From: Jiaping Zeng Date: Tue, 19 Aug 2025 23:16:10 -0700 Subject: [PATCH 6/8] Update supported region Signed-off-by: Jiaping Zeng --- ...8-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md index ab4612d76e..64c565c4d6 100644 --- a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md +++ b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md @@ -19,7 +19,7 @@ In this post, we'll walk you through two approaches to deploying the OpenSearch Before you begin, ensure that you have the following: - An OpenSearch cluster -- Access to one of the supported Bedrock AgentCore Regions: `us-east-1`, `us-west-2`, `eu-west-1`, or `ap-southeast-2` +- Access to one of the supported Bedrock AgentCore Regions: `us-east-1`, `us-west-2`, `eu-central-1`, or `ap-southeast-2` **Note**: While Bedrock AgentCore is only available in these four AWS Regions, your MCP server can connect to OpenSearch clusters in other Regions over the public internet. From 5092daad70d55e3c3599cb45183d3c57644c07c2 Mon Sep 17 00:00:00 2001 From: Jiaping Zeng Date: Wed, 27 Aug 2025 09:20:26 -0700 Subject: [PATCH 7/8] Update 2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md apply suggestions Signed-off-by: Jiaping Zeng --- ...-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md index 64c565c4d6..d652769e3e 100644 --- a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md +++ b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md @@ -3,11 +3,11 @@ layout: post title: "Hosting the OpenSearch MCP server with Amazon Bedrock AgentCore" authors: - jiapingzeng -date: 2025-08-04 +date: 2025-08-27 categories: - technical-post -meta_keywords: "MCP, Agentic, Agent, Model context protocol, MCP server, LLM integration, observability agent, Bedrock AgentCore, hosted MCP server" -meta_description: "Learn how to deploy the OpenSearch MCP server with Amazon Bedrock AgentCore Runtime." +meta_keywords: OpenSearch MCP Server, Model Context Protocol, OpenSearch clusters, Amazon Bedrock, Bedrock AgentCore, AWS CloudFormation, OpenSearch integration, AI agents +meta_description: Learn to deploy OpenSearch MCP server on Bedrock AgentCore Runtime to securely connect AI agents with OpenSearch clusters using CloudFormation or CLI methods. --- The [OpenSearch MCP server](https://github.com/opensearch-project/opensearch-mcp-server-py) enables AI agents to interact with OpenSearch clusters through the Model Context Protocol (MCP). While you can run the OpenSearch MCP server locally, hosting it on Amazon Bedrock AgentCore Runtime provides a scalable, managed solution that's accessible from anywhere. From c08f8d1b556a7951bc34002e962beaa848ac09f3 Mon Sep 17 00:00:00 2001 From: Jiaping Zeng Date: Fri, 12 Sep 2025 15:28:25 -0700 Subject: [PATCH 8/8] add link to AWS doc Signed-off-by: Jiaping Zeng --- ...8-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md index d652769e3e..1ca737808a 100644 --- a/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md +++ b/_posts/2025-08-04-Hosting-OpenSearch-MCP-server-with-Bedrock-AgentCore.md @@ -25,7 +25,7 @@ Before you begin, ensure that you have the following: ## Method 1: Using a CloudFormation template (available to Amazon OpenSearch Service users) -The fastest way to get started is to use the OpenSearch MCP server CloudFormation template, which automatically provisions all necessary resources. +The fastest way to get started is to use the [OpenSearch MCP server CloudFormation template](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/cfn-template-mcp-server.html), which automatically provisions all necessary resources. ### Deploying the template