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

Amazon Bedrock AgentCore Gateway supplies 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 submit, we stroll via easy methods to configure AgentCore Gateway to hook up with an OAuth-protected MCP server utilizing the Authorization Code movement.

Utilizing AgentCore Gateway as an MCP server endpoint

As organizations scale their AI agent deployments, the variety of MCP servers that every staff 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 device.

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 via 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 movement via 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 tip 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 accessible to them.
• Admin person – The person that manages and maintains Amazon Bedrock AgentCore Gateway. This person is chargeable for attaching MCP servers, instruments, or APIs to the AgentCore Gateway in order that AgentCore gateway customers can devour them.
• MCP server – On this submit, we assume that the MCP server is protected by an OAuth 2.0 Authorization Code movement, 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 submit apply particularly to MCP servers that require user-delegated authorization.

How Authorization Code movement works

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

1. Implicit sync throughout MCP Server goal creation

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

2. Present schema upfront throughout MCP Server targets creation

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

Notice: As a result of device schemas are offered upfront with this technique, the SynchronizeGatewayTargets operation isn’t supported. You’ll be able to change a goal between Methodology 1 and Methodology 2 by updating the goal configuration.

Because of this AgentCore Gateway customers can name checklist/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 movement is simply triggered when a Gateway person invokes a device 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 device catalog (cached instruments) with out authenticating to each MCP server and solely full the movement for the precise server whose device 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 chargeable for calling the CompleteResourceTokenAuth API, presenting each the person’s id and the session-URI. AgentCore Identification validates that the person who began the movement is similar person who accomplished it earlier than exchanging the authorization code for an entry token. This helps keep away from a state of affairs the place a person by chance shares the authorization URL, and another person completes the consent, which might grant entry tokens to the incorrect social gathering. 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 device invocation.

Resolution overview

On this submit, we present easy methods to connect the GitHub MCP server to Amazon Bedrock AgentCore Gateway utilizing Methodology 1 (admin-initiated sync throughout goal creation) and Methodology 2 (offering the device schema upfront throughout goal creation). The accompanying code is accessible in this repository.

Stipulations

You should comply with the next conditions together with this submit.

1. GitHub OAuth Apps setup
   • Go to https://github.com/settings/apps → New GitHub App
     
     
   • Fill in particulars:
     1. GitHub App identify: AgentCore Gateway GitHub MCP
     2. Homepage URL (The total URL to your GitHub App’s web site): The Homepage URL seems as a clickable hyperlink when person see your OAuth app, letting them study 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’ll come again and alter this worth.
     4. Superior Settings: Right here we go over the advisable defaults. Nevertheless, please guarantee to comply with safety finest practices primarily based in your organizations polices.
        1. Expire person authorization tokens: Disable – If enabled, it will permit AgentCore Identification to robotically refresh tokens for the person.
        2. Request person authorization (OAuth) throughout set up: Disable.
        3. Machine Circulate: Disable – Permits authorization on gadgets that don’t have a browser (for instance, CLI instruments, good TVs, CI environments).
        4. Webhook: Disable.
        5. Consumer permissions:  Use case dependent, preserve it default for now – These are granted when the person goes via the OAuth authorization movement. Solely request what you want, customers see these permissions on the consent display and extreme permissions cut back belief.

• • Select Create GitHub App.
  • Ensure that to notice down the app Consumer ID (completely different to the App ID).
  • Below your Oauth app basic settings, select Generate a brand new shopper secret. Ensure that to notice down the shopper secret as GitHub solely exhibits it as soon as upon creation.

2. IAM permissions: You want acceptable IAM permissions to run the code from this weblog submit. These are the minimal IAM permissions required.
3. Code repository: First clone the GitHub repository, after which open github-mcp-server.ipynb. We suggest following the console directions on this weblog submit to grasp the ideas after which take 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’ll 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 provider you created and replace the Authorization callback URL.
      
      

Implicit sync throughout MCP Server goal creation

On this part, we’ll introduce how implicit sync throughout MCP Server goal creation works. Ensure that the AgentCore Gateway execution function has GetWorkloadAccessTokenForUserId and CompleteResourceTokenAuth permissions. First, let’s begin by understanding the movement.

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 hook up with and which credential supplier to make use of for acquiring OAuth 2.0 tokens. This identical movement 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 supplies 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 movement (step 3) is similar person who accomplished consent. This revents token hijacking if the authorization URL was by chance shared. If the movement was initiated from the AWS Console, this step is dealt with robotically. If initiated from one other context, the admin is chargeable 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 checklist the instruments on MCP server goal; returned device definitions from the goal are cached at AgentCore Gateway.

Notice {that a} subsequent replace or synchronization to the goal gained’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 should use MCP model 2025-11-25 or later. Maintain all the things 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 conditions part.

Below further configuration, make certain to pick Authorization code grant (3LO). The Authorization code grant (3LO) choice will likely be disabled if the AgentCore Gateway wasn’t created with MCP model 2025-11-25 or later. Right here, you should additionally present the return URL. Through the session binding course of after the authorization code movement, customers will likely be returned to this URL, each throughout implicit sync and power invocation. You’ll be able to override the return URL worth throughout invocation. For extra info, see Instance: Authorization code grant within the Amazon Bedrock AgentCore Developer Information. You’ll be able to 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 will likely 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 movement is accomplished from the AWS console, session binding is dealt with robotically. If initiated from one other context, the admin is chargeable for calling the CompleteResourceTokenAuth API instantly. For extra info, see the code pattern in GitHub.

That is how the consent movement appears 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 easy methods to present the schema upfront throughout MCP Server targets creation. That is the advisable method 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 checklist instruments and paste the GitHub instruments definitions. You’ll be able to copy the device 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 technique or by offering the schema upfront, AgentCore Gateway customers can uncover and invoke instruments utilizing the MCP protocol. On this part, we take a look at the instruments/checklist and instruments/name flows from AgentCore Gateway.

1. The gateway person sends a instruments/checklist request to AgentCore Gateway with their inbound authorization token. As a result of device definitions have been cached throughout goal creation, AgentCore Gateway returns the cached device definitions instantly.
2. The gateway person sends instruments/name request to AgentCore Gateway with their inbound authorization token. This triggers the OAuth authorization code movement 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.",   
          "knowledge": {
            "elicitations": [{
               "mode": "url",
               "elicitationId": "<ID>",     
			   "url": "<identity_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 movement (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 take a look at a demo of the end-to-end movement the place we ship instruments/checklist and instruments/name requests to AgentCore Gateway.

Clear up

If you’re performed utilizing this resolution, make certain to scrub up all of the sources. Comply with the directions within the code repository.

Conclusion

On this submit, we demonstrated easy methods to join an OAuth-protected MCP server to Amazon Bedrock AgentCore Gateway utilizing the Authorization Code movement. By centralizing authentication via 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 consists of integration examples for different fashionable third-party MCP servers, and a information for internet hosting your individual MCP server with authorization code movement 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 study extra, confer with the next sources:

In regards to the authors