Model Context Protocol (MCP) servers allow foundation models to access external data and tools, supporting standardized, secure access to files, databases, and APIs. They give AI agents the ability to interact with real-world applications, reduce hallucinations with accurate context, and offer stateful, multi-turn capabilities. Industry-standard architectures quickly evolved and adopted MCP to power agentic AI workflows.
Amazon Quick supports MCP integrations for autonomous execution, real-time data access, and specialized AI sub-agent integrations. If you already have an MCP server, you can use this integration guide to integrate it with Amazon Quick. If you do not have an MCP server yet, you can use the AWS provided guidance for deploying MCP servers on AWS, which follows AWS Well-Architected pillars. Depending on your use case, you have several options:
- If you have your own REST API or one running on Amazon API Gateway, you can integrate Amazon Quick directly with your API usingAmazon Bedrock AgentCoreGateway. - If you prefer a serverless architecture and need only the bare minimum execution capability for your AI agent, you can author an AWS Lambda function and integrate with Amazon Quick using AgentCore Gateway.
- If you want a fully managed serverless MCP server solution with session isolation, extended execution time, persistent file systems, built-in authentication, observability, enhanced payload, bidirectional streaming, and evaluations, you can use AgentCore Runtimefor MCP server hosting and connect with Amazon Quick using AgentCore Gateway.
In this post, you will learn how to deploy and host your MCP server in AgentCore Runtime and integrate it with Amazon Quick, along with the prerequisites. With this pattern, you promote reusability and avoid duplication of AI tools, so clients can reuse commonly used tools and agents exposed through an MCP server instead of authoring them from scratch again. Your customers get a way to use your product inside Amazon Quick (chat agents and workflows) without building custom connectors for every use case.
Solution overview
As of this writing, you can use Amazon Quick in a web browser or the desktop app to work with a chat agent or Flows that provide AI agent capabilities. To connect the AI agent with the MCP server for access to additional tools and sub-agent capabilities, you need to integrate the MCP server with Amazon Quick. The integration is handled through connectors on the Amazon Quick end and AgentCore Gateway on the AgentCore end. AgentCore Gateway and Runtime are available in Amazon Bedrock AgentCore, a fully managed service for building generative AI applications. The authorization flow from Amazon Quick to AgentCore Gateway is referred to as Inbound Auth, and the flow from AgentCore Gateway to AgentCore Runtime is referred to as Outbound Auth. Inbound Auth handles authentication and authorizes the user to access the MCP server. For Inbound Auth, we use Amazon Cognito for authorization needs, but you can use another identity provider. Outbound Auth handles machine-to-machine authentication and authorization, and we use AgentCore Identity, a comprehensive identity and access management service purpose-built for AI agents. The MCP protocol currently requires OAuth 2.0 as the authentication protocol, so Outbound Auth uses OAuth 2.0.
Prerequisites
Before you begin, verify that you meet the following prerequisites to deploy the solution in your own AWS account using the step-by-step instructions in this post.
-
An AWS account. - Amazon Quick set up with an Author or higher subscription.
-
Permission to create AWS Identity and Access Management (IAM)roles and policies, and AWS resources for AgentCore, Amazon Cognito, and Amazon CloudWatch. - Basic knowledge of AWS services.
-
For the Amazon Bedrock AgentCore setup:
-
Access to a command-line environment with the AWS SDK and Python installed.
-
Knowledge of the AWS CLI and Python.
-
Amazon Bedrock with access enabled for Anthropic models.
-
To run this tutorial:
-
Python 3.10+.
-
AWS credentials configured.
-
Amazon Bedrock AgentCore SDK.
-
MCP (Model Context Protocol) library.
-
Running Docker daemon.
Implementation steps
Follow these steps to go from a locally authored MCP server to a fully integrated, authenticated tool available inside your Amazon Quick chat agent.
- Implement and deploy a sample remote MCP server on AgentCore Runtime.
- Integrate the MCP server with AgentCore Gateway with inbound and outbound auth.
- Register the MCP integration in Amazon Quick and integrate with your chat agent.
- Test the MCP server integration within Amazon Quick.
- Clean up resources.
Step 1: Implement and deploy a remote MCP server on AgentCore Runtime
In this step, we deploy a sample MCP server on AgentCore Runtime with basic dummy tools. The detailed step-by-step code is available in the AgentCore samples notebook on GitHub, and we cover it at a high level.
Create the project structure and files as follows:
Project structure
mcp_server_project/
├── mcp_server.py # Main MCP server code
├── requirements.txt # Dependencies
└── __init__.py # Python package marker
File: requirements.txt
mcp>=1.10.0
boto3
bedrock-agentcore
bedrock-agentcore-starter-toolkit>=0.1.21
strands-agents
Install the requirements in your Python interpreter using the following command:
The following is a sample bare-minimum code. For more details on secure auth setup, see Building a secure auth code flow setup using AgentCore Gateway with MCP clients. When you configure an AgentCore Runtime with the MCP protocol, the service expects MCP server containers to be available at the path 0.0.0.0:8000/mcp
, which is the default path supported by most official MCP server SDKs.
File: sample_mcp_server.py
The server uses FastMCP
with stateless_http=True
, which is required for AgentCore Runtime compatibility. This code does the following:
FastMCP
: Creates an MCP server that can host your tools.@mcp.tool()
: Decorator that turns your Python functions into MCP tools.stateless_http=True
: Required for AgentCore Runtime compatibility.
You can test your MCP server locally using a local MCP server client by following the Creating Local Testing Client and Testing Locally sections in the notebook.
Now, you are ready to deploy to AgentCore Runtime. You can deploy using the Bedrock starter kit from the terminal (described in the following steps) or through a Python script, as listed in the Launching MCP Server to AgentCore Runtime section in the notebook. We use the AgentCore starter kit in this tutorial.
Open your terminal with the current working directory set to your project directory, and configure your project for deployment. The configure
command is interactive with self-explanatory steps. You can pick the defaults for this tutorial.
The configure
command performs several key setup tasks automatically. It generates a Dockerfile
and .dockerignore
file for containerizing your agent so that your Python application runs consistently across different environments. Most importantly, it creates a .bedrock_agentcore.yaml
configuration file that stores your agent’s runtime settings and deployment parameters.
The --entrypoint
parameter specifies the Python file that contains your agent’s main logic. This is the file with your @app.entrypoint
decorated function. The --name
parameter assigns a unique identifier to your agent within your AWS account, which is used for resource naming and management across AWS services.
After you configure the project, you can initiate the deployment by running the following command.
You should be able to see the MCP server in Runtime now.
Step 2: Integrate the MCP server with AgentCore Gateway with inbound and outbound auth
In this step, we configure AgentCore Gateway to act as the secure bridge between Amazon Quick and your deployed MCP server. The inbound and outbound flows are set up with recommended security best practices, including end-to-end TLS that is available out of the box. You can refer to the respective service documentation for customizations. This involves setting up an IAM role for the Gateway, configuring two Amazon Cognito user pools to handle Inbound Auth (authorizing requests from Amazon Quick) and Outbound Auth (authenticating calls to the MCP server through OAuth 2.0), and creating the Gateway endpoint. For programmatic setup, follow the MCP server as a target tutorial on GitHub.
Step 2a: Create an IAM role for AgentCore Gateway to assume
Go to the AWS Management Console, choose IAM, and then choose Create role. Select Amazon Bedrock AgentCore as the use case.
You can attach the following inline IAM policy in Permissions:
Use the sample role name agentcore-sample-mcpgateway-role
(or pick your own). For Resource, populate it with the runtime ARN of the MCP server deployed on AgentCore Runtime.
Step 2b: Create an Amazon Cognito user pool for inbound authorization to the Gateway
Navigate to Amazon Cognito and create a new user pool that serves as the Inbound authorization layer, validating requests from Amazon Quick before they reach the Gateway.
Go to Amazon Cognito and choose Create user pool.
Next, configure the resource server for your user pool. In the navigation pane, choose Domain under Branding, and create a new resource server to define the protected custom scope invoke
that the Gateway validates during authorization.
Keep a note of the following Inbound Auth details from the user pool created earlier, because these are referenced in later steps:
Client ID and Client Secret: In the navigation pane, choose App Clients, and then select your app client to view the credentials.** Discovery URL**:https://cognito-idp.{REGION}.amazonaws.com/{gw_user_pool_id}/.well-known/openid-configuration
Step 2c: Create an Amazon Cognito user pool for outbound authorization
Navigate to Amazon Cognito and create a second user pool that serves as the Outbound authorization layer, so the Gateway can authenticate itself when making calls to the MCP server hosted on AgentCore Runtime.
Go to Amazon Cognito and choose Create user pool.
Similar to inbound authorization, create a resource server for outbound authorization and get the details for the client ID, secret, and discovery URL with the protected custom scope invoke
.
Keep a note of the following information available from the user pool for Outbound Auth that is needed later:
Client ID and Client Secret: In the navigation pane, choose App Clients, and then select your app client to view the credentials.** Discovery URL**:https://cognito-idp.{REGION}.amazonaws.com/{gw_user_pool_id}/.well-known/openid-configuration
Next, create an OAuth credential provider in AgentCore Identity. Navigate to Amazon Bedrock AgentCore, choose Identity, and then choose Add Outbound Auth and Create OAuth Client. Populate the form with the Discovery URL, Client ID, and Client Secret from the app client created in the Outbound Auth Amazon Cognito user pool in the previous step.
Step 2d: Create the AgentCore Gateway
Navigate to Amazon Bedrock AgentCore, choose Gateway, and then choose Create Gateway. For this walkthrough, we name it ac-gateway-mcp-server
. For Inbound Auth, select JWT as the authentication type, choose Use Existing Identity Provider Configuration, and provide the Discovery URL and Client ID from the Inbound Auth Amazon Cognito user pool created in Step 2b.
In the Permissions section, use the IAM role we created in Step 2a.
Under the Target section, register your MCP server as a target. Verify that you select OAuth Client as the authorization type, because the MCP protocol does not support other authorization methods at this time. To build the MCP endpoint URL, use the following template, replacing encoded_agentcore_runtime_mcp_server_arn
with the URL-encoded ARN of your MCP server deployed on AgentCore Runtime.
https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/{encoded_agentcore_runtime_mcp_server_arn}/invocations?qualifier=DEFAULT
For the Outbound Auth configuration, use the OAuth client that we created in the Outbound Auth section.
After the details are filled in, choose Create Gateway, and wait for both the Gateway and its Target to reach a Ready state before proceeding to the next step.
Step 3: Register MCP integration in Amazon Quick
Navigate to Amazon Quick, choose Connectors, and then choose Create for your team. Select Model Context Protocol (MCP) as the integration type to begin registering your newly created Gateway as an MCP integration.
Provide a name and description for your integration, along with the MCP Server Endpoint, which is the Resource URL of the AgentCore Gateway created in Step 2d. For the connection type, you also have the option to choose private VPC connectivity to restrict the visibility of your MCP server over the network for better security.
On the Authenticate screen, fill in the Inbound Auth details configured on the AgentCore Gateway in Step 2d. You can select the authentication type based on your use case. If your use case is authenticating individual users, select User authentication. If your use case is a more systematic integration, then select Service authentication. For this tutorial, we use User authentication with Amazon Cognito. You can connect your preferred identity provider. Fill in the Client ID, Client Secret, Token URL, and Authorization URL details based on the identity provider selected.
For the Token URL, use the following template. Note that the underscore in the user pool ID must be removed (for example, us-west-2_qNBcTlLbR
becomes us-west-2qNBcTlLbR
). For the Authorize URL, use the same URL but replace token
with authorize
.
Token URL template:
https://{user_pool_id_without_underscore}.auth.{REGION}.amazoncognito.com/oauth2/token
After the details are filled in, choose Create and Continue, and review your configuration. The screen shows only listTools for now and syncs the tools with the MCP server. The sync is complete after the Action is in the Available state.
You should see the tools refreshed after the Action is in the Available or Ready state.
Step 4: Test the MCP server integration within Amazon Quick
You can choose Test Action APIs to verify that your MCP tools are accessible and functioning as expected.
After the integration is set up, you can add it as an Action in your chat agent or Flows. The Actions integration allows your Quick agent or workflow to invoke MCP tools. For this tutorial, we create one sample chat agent. You can provide more context to the agent by linking a Space or up files, but we skip that for now and focus only on the MCP server integration.
In the Actions section, choose Link Actions and select the Actions integration we created in Step 3.
You can then test the integration with the MCP server within the chat agent and launch the chat agent after validating the results.
Step 5: Clean up
To avoid incurring unnecessary costs, delete the resources created in this walkthrough in the reverse order of creation to make sure that dependencies are cleanly removed before you delete the resources they rely on. You can also refer to the cleanup code in the tutorial notebook on GitHub.
- Delete the Amazon Quick chat agent or Flow.
- Delete the Amazon Quick Action.
- Delete the AgentCore Gateway.
- Delete the AgentCore Identity resources.
- Delete both the inbound and outbound auth Amazon Cognito user pools.
- Delete the AgentCore Runtime.
- Delete the AgentCore Gateway IAM role.
Conclusion
In this post, you learned how Amazon Quick integrates with custom MCP servers hosted on Amazon Bedrock AgentCore Runtime. You walked through deploying a remote MCP server on AgentCore Runtime, securing it with inbound and outbound authentication using Amazon Cognito and AgentCore Identity, bridging it to Amazon Quick through AgentCore Gateway, and registering it as an Action integration in Amazon Quick. This pattern promotes reusability of AI tools and agents across your organization, so teams can expose specialized capabilities through a standardized MCP interface and consume them directly within Amazon Quick chat agents and Flows, without building custom connectors for every use case.
For more information about Amazon Quick and how you can get started, see the blog post Announcing Amazon Quick: your agentic teammate for answering questions and taking action. For more information about Amazon Bedrock AgentCore, see the blog post Introducing Amazon Bedrock AgentCore Gateway: Transforming enterprise AI agent tool development.