Connecting MCP servers to Amazon Bedrock AgentCore Gateway utilizing Authorization Code stream

Amazon Bedrock AgentCore Gateway gives a centralized layer for managing how AI brokers hook up with instruments and MCP servers throughout your group. It consolidates authentication, observability, and coverage enforcement right into a single endpoint, eradicating the necessity to configure and safe every MCP server connection individually.

On this publish, we stroll by means of tips on how to configure AgentCore Gateway to connect with an OAuth-protected MCP server utilizing the Authorization Code stream.

Utilizing AgentCore Gateway as an MCP server endpoint

As organizations scale their AI agent deployments, the variety of MCP servers that every group depends on grows rapidly. Builders are adopting Amazon Bedrock AgentCore Gateway as a single endpoint for accessing a number of MCP servers. As a substitute of configuring every MCP server individually per IDE, groups level to 1 Gateway URL for constant entry to their full MCP toolset throughout software.

This sample is accelerating as groups transfer past customized MCP servers and undertake production-grade third-party ones, like these from AWS, GitHub, Salesforce, and Databricks. Many of those MCP servers are protected by their main id supplier by means of federation, whereas others are secured by their very own authorization servers. Because the variety of MCP servers per group grows, managing connections, authentication, and routing on the IDE stage turns into unsustainable. AgentCore Gateway centralizes this complexity, giving groups a single management aircraft for MCP entry whereas giving builders a frictionless expertise.

Many enterprise MCP servers require OAuth 2.0 authorization, the place the agent should authenticate on behalf of a person earlier than invoking instruments. AgentCore Gateway now helps the OAuth 2.0 Authorization Code stream by means of Amazon Bedrock AgentCore Identification. With this, your brokers can securely entry protected MCP servers with out embedding credentials in software code or managing the token lifecycle manually.

Key phrases

• AgentCore Gateway person – The top person who consumes the instruments in Amazon Bedrock AgentCore Gateway with MCP shoppers. Gateway customers don’t handle the AgentCore Gateway itself. They use the one AgentCore Gateway URL to entry the instruments out there to them.
• Admin person – The person that manages and maintains Amazon Bedrock AgentCore Gateway. This person is answerable for attaching MCP servers, instruments, or APIs to the AgentCore Gateway in order that AgentCore gateway customers can eat them.
• MCP server – On this publish, we assume that the MCP server is protected by an OAuth 2.0 Authorization Code stream, which requires person interplay to finish authentication. That is distinct from machine-to-machine authentication strategies reminiscent of Consumer Credentials or Token Change, the place no person intervention is required. The patterns described on this publish apply particularly to MCP servers that require user-delegated authorization.

How Authorization Code stream works

To offer assist for the Authorization Code Grant kind, we offer two methods for goal creations.

1. Implicit sync throughout MCP Server goal creation

On this methodology, the admin person completes the authorization code stream throughout CreateGatewayTarget, UpdateGatewayTarget, or SynchronizeGatewayTargets operations. This enables AgentCore Gateway to find and cache the MCP server’s instruments upfront.

2. Present schema upfront throughout MCP Server targets creation

With this methodology, admin customers present the software schema instantly throughout CreateGatewayTarget or UpdateGatewayTarget operations, fairly than AgentCore Gateway fetching them dynamically from the MCP server. AgentCore Gateway parses the offered schema and caches the software definitions. This removes the necessity for the admin person to finish the authorization code stream throughout goal creation or replace. That is the advisable strategy when human intervention isn’t potential throughout create/replace operations. This methodology is useful while you don’t wish to expose all of the instruments offered by the MCP server goal.

Observe: As a result of software schemas are offered upfront with this methodology, the SynchronizeGatewayTargets operation isn’t supported. You may change a goal between Technique 1 and Technique 2 by updating the goal configuration.

Which means that AgentCore Gateway customers can name record/instruments with out being prompted to authenticate with the MCP server authentication server, as a result of this fetches the cached instruments. The authorization code stream is barely triggered when a Gateway person invokes a software on that MCP server. That is notably helpful when a number of MCP servers are connected to a single Gateway. Customers can browse the complete software catalog (cached instruments) with out authenticating to each MCP server and solely full the stream for the precise server whose software they invoke.

URL Session Binding

URL session binding verifies that the person who initiated the OAuth authorization request is similar person who granted consent. When AgentCore Identification generates an authorization URL, it additionally returns a session-URI. After the person completes consent, the browser redirects again to a callback URL with the session-URI. The applying is then answerable for calling the CompleteResourceTokenAuth API, presenting each the person’s id and the session-URI. AgentCore Identification validates that the person who began the stream is similar person who accomplished it earlier than exchanging the authorization code for an entry token. This helps keep away from a situation the place a person by chance shares the authorization URL, and another person completes the consent, which might grant entry tokens to the improper celebration. The authorization URL and session URI are solely legitimate for 10 minutes, additional limiting the window for misuse. Session binding applies throughout admin goal creation (implicit sync) and through software invocation.

Answer overview

On this publish, we present tips on how to connect the GitHub MCP server to Amazon Bedrock AgentCore Gateway utilizing Technique 1 (admin-initiated sync throughout goal creation) and Technique 2 (offering the software schema upfront throughout goal creation). The accompanying code is obtainable on this repository.

Stipulations

You will need to observe the next stipulations together with this publish.

1. GitHub OAuth Apps setup
   • Go to https://github.com/settings/apps → New GitHub App
     
   • Fill in particulars:
     1. GitHub App title: AgentCore Gateway GitHub MCP
     2. Homepage URL (The complete URL to your GitHub App’s web site): The Homepage URL seems as a clickable hyperlink when person see your OAuth app, letting them be taught extra about your app. It helps customers confirm the legitimacy of the app requesting entry to their GitHub account.
     3. Authorization callback URL: The Authorization callback URL (redirect URI) is the URL GitHub redirects the person to after they authorize (or deny) your OAuth app. For now, let’s put https://instance.com/auth, we are going to come again and alter this worth.
     4. Superior Settings: Right here we go over the advisable defaults. Nonetheless, please guarantee to observe safety finest practices based mostly in your organizations polices.
        1. Expire person authorization tokens: Disable – If enabled, it will enable AgentCore Identification to robotically refresh tokens for the person.
        2. Request person authorization (OAuth) throughout set up: Disable.
        3. System Circulate: Disable – Permits authorization on units that don’t have a browser (for instance, CLI instruments, good TVs, CI environments).
        4. Webhook: Disable.
        5. Person permissions:  Use case dependent, hold it default for now – These are granted when the person goes by means of the OAuth authorization stream. Solely request what you want, customers see these permissions on the consent display screen and extreme permissions cut back belief.

• • Select Create GitHub App.
  • Make sure that to notice down the app Consumer ID (completely different to the App ID).
  • Beneath your Oauth app common settings, select Generate a brand new shopper secret. Make sure that to notice down the shopper secret as GitHub solely reveals it as soon as upon creation.

2. IAM permissions: You want applicable IAM permissions to run the code from this weblog publish. These are the minimal IAM permissions required.
3. Code repository: First clone the GitHub repository, after which open github-mcp-server.ipynb. We advocate following the console directions on this weblog publish to know the ideas after which have a look at the code walkthrough.

   git clone https://github.com/awslabs/amazon-bedrock-agentcore-samples.git

   cd 01-tutorials/02-AgentCore-gateway/05-mcp-server-as-a-target/03-authorization-code-flow

4. GitHub credential supplier: On this step we are going to setup Agentcore Identification Credential Supplier. On the Amazon Bedrock AgentCore console, go to AgentCore Identification and create an OAuth shopper.
   
   1. Present a reputation for the OAuth Consumer, select the included GitHub supplier, and fill within the GitHub OAuth App shopper ID and shopper secret.
      
   2. Copy the AgentCore Identification OAuth shopper callback URL, and ensure to return to GitHub OAuth supplier you created and replace the Authorization callback URL.
      

Implicit sync throughout MCP Server goal creation

On this part, we are going to introduce how implicit sync throughout MCP Server goal creation works. Make it possible for the AgentCore Gateway execution position has GetWorkloadAccessTokenForUserId and CompleteResourceTokenAuth permissions. First, let’s begin by understanding the stream.

1. The admin person calls CreateGatewayTarget, offering the MCP server endpoint, the AgentCore Identification Credential Supplier, and return URL. This tells AgentCore Gateway which MCP server to connect with and which credential supplier to make use of for acquiring OAuth 2.0 tokens. This identical stream additionally applies to UpdateGatewayTarget and SynchronizeGatewayTargets operations.
2. AgentCore Gateway requests a workload entry token from the AgentCore Identification Credential Supplier, passing the AgentCore Gateway workload id and a person ID within the format {gatewayId}{targetId}{uuid}. This workload entry token identifies the AgentCore Gateway as a certified caller for subsequent credential operations.
3. Utilizing the workload entry token, AgentCore Gateway requests an OAuth 2.0 entry token from the AgentCore Identification Credential Supplier. This gives the admin person with an authorization URL and a session-URI. At this stage, the goal is in Wants Authorization standing.
4. The admin opens the authorization URL of their browser, indicators in, and grants the requested permissions to the AgentCore Gateway.
5. After the admin grants consent, the OAuth 2.0 authorization server sends an authorization code to the AgentCore Identification Credential Supplier’s registered callback endpoint.
6. The credential supplier redirects the admin browser to the return URL, with the session URI. The admin software calls CompleteResourceTokenAuth, presenting the person id and the session-URI returned in step 2. The credential supplier validates that the person who initiated the authorization stream (step 3) is similar person who accomplished consent. This revents token hijacking if the authorization URL was by chance shared. If the stream was initiated from the AWS Console, this step is dealt with robotically. If initiated from one other context, the admin is answerable for calling the CompleteResourceTokenAuth API instantly.
7. After profitable session binding validation, the credential supplier exchanges the authorization code with the OAuth 2.0 authorization server for an OAuth 2.0 entry token.
8. This entry token is used to record the instruments on MCP server goal; returned software definitions from the goal are cached at AgentCore Gateway.

Observe {that a} subsequent replace or synchronization to the goal received’t reuse the entry token. As a substitute, AgentCore Identification will get a brand new entry token from Authorization Server.

Goal creation

First, let’s begin by creating an Amazon Bedrock AgentCore Gateway and Goal and see how implicit sync works throughout MCP Server goal creation.

When creating an AgentCore Gateway, you could use MCP model 2025-11-25 or later. Hold every part else default and choose MCP server goal. Present the MCP server endpoint, and for OAuth shopper, choose the AgentCore Identification OAuth Consumer created in the course of the stipulations part.

Beneath further configuration, be sure that to pick out Authorization code grant (3LO). The Authorization code grant (3LO) choice can be disabled if the AgentCore Gateway wasn’t created with MCP model 2025-11-25 or later. Right here, you could additionally present the return URL. Through the session binding course of after the authorization code stream, customers can be returned to this URL, each throughout implicit sync and gear invocation. You may override the return URL worth throughout invocation. For extra info, see Instance: Authorization code grant within the Amazon Bedrock AgentCore Developer Information. You may present scopes and extra parameters reminiscent of viewers when configuring the goal. These parameters are included within the request when AgentCore Identification reaches out to the authorization server’s /authorize endpoint.

After creating the goal, the goal can be in Wants authorization standing. At this level, admin customers are required to finish the authorization request, both instantly from the AWS console or by navigating to the authorization URL instantly. It’s essential to notice that if the stream is accomplished from the AWS console, session binding is dealt with robotically. If initiated from one other context, the admin is answerable for calling the CompleteResourceTokenAuth API instantly. For extra info, see the code pattern in GitHub.

That is how the consent stream appears to be like like when initiated from the AWS Console.

After a number of seconds you will note the goal is in Prepared standing with authorization standing Approved.

Present schema upfront throughout MCP Server targets creation

On this part, we introduce tips on how to present the schema upfront throughout MCP Server targets creation. That is the advisable strategy when human intervention isn’t potential throughout create/replace operations.

On this step, we create an Amazon Bedrock AgentCore Gateway and Goal and supply schema upfront in the course of the MCP Server targets creation. The method stays the identical. Throughout goal creation choice, choose Use pre-defined record instruments and paste the GitHub instruments definitions. You may copy the software definition from the GitHub repository.

The goal on this case turns into instantly prepared, with authorization standing No authorization required.

Demo

After profitable goal creation, both utilizing the implicit sync methodology or by offering the schema upfront, AgentCore Gateway customers can uncover and invoke instruments utilizing the MCP protocol. On this part, we have a look at the instruments/record and instruments/name flows from AgentCore Gateway.

1. The gateway person sends a instruments/record request to AgentCore Gateway with their inbound authorization token. As a result of software definitions have been cached throughout goal creation, AgentCore Gateway returns the cached software definitions instantly.
2. The gateway person sends instruments/name request to AgentCore Gateway with their inbound authorization token. This triggers the OAuth authorization code stream for the precise MCP server goal, as a result of AgentCore Gateway wants an entry token to name the MCP server on behalf of this person.
3. AgentCore Gateway requests a workload entry token from AgentCore Identification, passing the workload id and the person’s JWT from the inbound authorization header.
4. Utilizing the workload entry token, AgentCore Gateway requests an OAuth 2.0 entry token from the credential supplier. As a result of no legitimate token exists but for this person, the credential supplier returns an authorization URL and a session-URI as a substitute.
5. AgentCore Gateway passes the authorization URL and session URI again to the gateway person. The person opens the authorization URL of their browser, indicators in to the OAuth 2.0 authorization server, and grants the requested permissions. The pattern URL elicitation response from AgentCore Gateway is as follows:

{
“jsonrpc”: “2.0”,
“id”: 3,
“error”: {
“code”: -32042,
“message”: “This request requires extra info.”,
“information”: {
“elicitations”: [{
“mode”: “url”,
“elicitationId”: “”,
“url”: “/?request_uri=urn%3Aietf%3A…”,
“message”: “Please login to this URL for authorization.”
}]
}
}
}

6. After the person grants consent, the OAuth 2.0 authorization server sends an authorization code to the AgentCore Identification Credential Supplier’s registered callback endpoint.
7. The credential supplier redirects the person’s browser to the return URL with the session URI. The person’s software calls CompleteResourceTokenAuth, presenting the person’s JWT and the session-URI. The credential supplier validates that the person who initiated the authorization stream (Step 4) is similar person who accomplished consent.
8. After profitable session binding validation, the credential supplier exchanges the authorization code with the OAuth 2.0 authorization server for an OAuth 2.0 entry token. The credential supplier caches this token within the Token Vault underneath the workload id and person id.
9. When the gateway person points a instruments/name request once more, AgentCore Gateway will get the cached token, utilizing workload id and person id, from AgentCore Identification and makes use of that to name the MCP server.

Allow us to now have a look at a demo of the end-to-end stream the place we ship instruments/record and instruments/name requests to AgentCore Gateway.

Clear up

If you’re accomplished utilizing this resolution, be sure that to scrub up all of the sources. Observe the directions within the code repository.

Conclusion

On this publish, we demonstrated tips on how to join an OAuth-protected MCP server to Amazon Bedrock AgentCore Gateway utilizing the Authorization Code stream. By centralizing authentication by means of AgentCore Gateway, groups can handle credentials securely utilizing Amazon Bedrock AgentCore Identification whereas giving builders seamless entry to protected instruments from MCP shopper.

Whereas this instance focuses on the GitHub MCP server, the code repository contains integration examples for different fashionable third-party MCP servers, and a information for internet hosting your personal MCP server with authorization code stream assist on AgentCore Runtime as an AgentCore Gateway goal. We encourage you to discover these examples and adapt them to your group’s MCP server panorama.

Sources

To be taught extra, confer with the next sources:

Concerning the authors

Arko Dutta

Arko Dutta is a Software program Engineer at Amazon Net Companies, presently engaged on the AgentCore Gateway group. Throughout his time at Amazon, he has contributed throughout a number of organizations, together with Alexa Expertise, Vendor Flex, and API Gateway, earlier than becoming a member of the Bedrock AgentCore Gateway group. Exterior of labor, he enjoys mountaineering and touring.

Eashan Kaushik

Eashan Kaushik is a Specialist Options Architect AI/ML at Amazon Net Companies. He’s pushed by creating cutting-edge generative AI options whereas prioritizing a customer-centric strategy to his work. Earlier than this position, he obtained an MS in Pc Science from NYU Tandon College of Engineering. Exterior of labor, he enjoys sports activities, lifting, and operating marathons.

Sheetal Mohite

Sheetal Mohite is a Software program Engineer at Amazon Net Companies on the AgentCore Gateway group. Over the course of her tenure at Amazon, she has labored throughout a number of organizations, together with Shopper Robotics, and now contributes in the direction of constructing scalable infrastructure for Agentic AI methods. Exterior of labor, she enjoys CrossFit, occasional path runs and mountaineering.

Tanuja Joshi

Tanuja Joshi is a Software program Engineer at Amazon Net Companies on the AgentCore Gateway group. Because the begin of her tenure, she has been working within the agentic AI house, contributing to companies reminiscent of Bedrock Brokers. When not at work, she enjoys studying and mountain climbing.