Skip to main content
search
Blog

Hosting OpenSearch MCP Server with Amazon Bedrock AgentCore

By August 27, 2025No Comments

The OpenSearch MCP server 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.

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-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.

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.

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 in which your cluster is located.

Optional:

  • 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:

  • AgentCoreArn: The Amazon Resource Name (ARN) of your Bedrock AgentCore Runtime.
  • TokenEndpoint: The token endpoint obtained from your discovery endpoint.
  • MCPServerEndpoint: 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, follow these steps to obtain the token:

  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:

export TOKEN_ENDPOINT="<YOUR TOKEN ENDPOINT>"
export CLIENT_ID="<YOUR CLIENT ID>"
export CLIENT_SECRET="<YOUR 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"

The response contains the token:

{"access_token":"xxxxx","expires_in":3600,"token_type":"Bearer"}

Note: Cognito tokens expire every 60 minutes by default.

Method 2: Using the Bedrock AgentCore CLI

You can also use the Bedrock AgentCore CLI directly.

Creating the MCP server code

First, create your MCP server implementation:

opensearch_mcp_server.py

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))

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>=0.3.1

Setting up OAuth (Optional)

If you don’t have an existing OAuth authorizer, create one using Amazon Cognito by following the instructions provided in the Bedrock AgentCore documentation.

Configuring AgentCore deployment

Install the AgentCore toolkit:

pip install bedrock-agentcore-starter-toolkit

Configure your deployment:

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.

Deploying to AgentCore Runtime

Deploy your MCP server:

agentcore launch

After successful deployment, generate your MCP server URL:

export AWS_REGION="<YOUR AWS REGION>"
export AGENT_ARN="<YOUR 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 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 instructions provided at Fine-grained access control in Amazon OpenSearch Service to configure the appropriate backend role mapping.

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:

{
  "mcpServers": {
    "opensearch-mcp-server": {
      "command": "mcp-proxy",
      "timeout": 60000,
      "args": [
        "<YOUR MCP URL>",
        "--transport",
        "streamablehttp"
      ],
      "env": {
        "API_ACCESS_TOKEN": "<YOUR ACCESS TOKEN>"
      }
    }
  }
}

Start the Amazon Q Developer CLI:

$ q
✓ opensearch-mcp-server loaded in 3.22 s

Verify that the tools are available:

> /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 the blog post 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 Agents framework:

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 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.

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.

Author

  • Jiaping Zeng is a Software Engineer at AWS working on the OpenSearch Project. He primarily works on OpenSearch's AI/ML and semantic search features.

    View all posts