Skip to main content

Connect an Amazon Bedrock AgentCore Gateway

For a Studio user, with an AWS or identity administrator, who has an Amazon Bedrock AgentCore Gateway and wants agents to call its tools. Choose the sign-in the gateway uses, set it up in two places (the gateway's side and Studio), and test.

Before you start: the gateway's URL, https://<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com/mcp, reachable from your Studio (Data connectors for a private deployment), and the MCP connector basics (MCP connector).

Sign in with Entra ID client credentials​

Use this when the gateway's inbound authorisation is a JSON Web Token (JWT) authoriser that trusts Microsoft Entra ID. Studio gets a token with a client ID and secret and keeps it until shortly before it expires.

  1. In Entra ID, register the API the gateway will accept tokens for, and note its Application (client) ID and its Application ID URI (for example api://<application-id>). Make sure the registration issues version 2.0 access tokens: the token's ver claim reads 2.0.
  2. Register a second application for Studio, add a client secret, and give it permission to call the API as an application. An administrator grants consent. Note its Directory (tenant) ID, Application (client) ID and the secret value.
  3. On the gateway, set the JWT authoriser's discovery URL to https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration and its allowed audiences to the API's Application (client) ID, which is what the token carries in aud. Leave allowed clients empty: it checks a client_id claim, and Entra ID tokens name the caller in azp, so the gateway would refuse a valid token with 403.
  4. In Studio, open Data Connectors, click Create Connector, choose MCP Server, name it, and enter the gateway URL as MCP Server URL.
  5. Under Authentication Configuration, set Sign-in method to Sign in with client credentials and fill:
    • Token URL: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
    • Scope: api://<application-id>/.default (the Application ID URI, then /.default)
    • Audience (optional): leave blank for Entra ID
    • Client authentication: Send in the request body
    • Client ID and Client secret from step 2
  6. Click Test Connection.

Sign in as each person with Entra ID (on behalf of the user)​

Use this when the gateway's JWT authoriser trusts Microsoft Entra ID and each call must carry the person who asked, not a shared service identity. Each person connects once with Connect Microsoft account; Studio keeps their refresh token and, for each call, exchanges it for an access token for the gateway's API, so the token the gateway receives is that person's own delegated token. The gateway sees who they are in the token's oid and tid claims, and the Studio app that acted for them in azp. Studio's own sign-in does not give it a Microsoft token, which is why each person connects once.

  1. In Entra ID, register the API the gateway will accept tokens for, as in the client credentials steps above. Add a delegated scope to it, for example access_as_user (full form api://<application-id>/access_as_user), and make sure the registration issues version 2.0 access tokens.
  2. Register a second application for Studio, the on-behalf-of app, and add a client secret. Give it permission to call your API with that delegated scope, and have an administrator grant consent. Note its Directory (tenant) ID, Application (client) ID and the secret value. A person whose consent is missing sees "Your organisation has not yet allowed this app to act for you. Ask your Microsoft Entra administrator to grant consent."
  3. On the app's Authentication page add a Web redirect URI for this Studio. It is the same for every connector, and Studio shows it in three places: the connector form's Redirect URI, the connector's page, and Sign-in redirect URI on the deployment's Overview in Organisations (Deployment detail). It has the form https://<your Studio address>/data-connector/connectors/oauth/callback. Add one for each Studio that will use the app.
  4. On the gateway, set the JWT authoriser's discovery URL to https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration and its allowed audiences to the API's Application (client) ID. Leave allowed clients empty, as for client credentials.
  5. In Studio, create an MCP Server connector with the gateway URL, and set Sign-in method to Sign in with Microsoft (each person). Fill Directory (tenant) ID and Application (client) ID (the on-behalf-of app), Client secret, and Scope with the API's delegated scope. The tenant and client IDs are part of the connector, so they travel with it through a Library; the secret does not. Studio asks for the offline_access, openid and profile permissions as well, so do not enter them in Scope.
  6. Save, then press Connect Microsoft account and sign in with the Microsoft account you use for Studio. Click Test with my account: it lists the gateway's tools using your own token. Refresh tools and choose the tools agents may use (Choose the tools agents may use).

Everyone who uses the connector repeats step 6 with their own account. A person who has not connected sees the connect card in chat (Each person signs in to an MCP connector). When Microsoft asks for a new sign-in (for example a Conditional Access rule, an expired session or a changed password), the connector shows Connect again and the person signs in again; if Microsoft names an extra requirement, Studio asks for it on the next Connect Microsoft account. A rejected client secret reads "The token endpoint rejected the client ID or secret." and is for the connector's owner to fix.

Sign in with AWS IAM​

Use this when the gateway's inbound authorisation is AWS IAM. Studio signs each request with AWS Signature Version 4, so you paste no secret. There are two ways to give Studio an identity: the role you create in the gateway's account (recommended, with an External ID Studio generates), or this Studio's own role for a gateway that allows it in a resource policy.

  1. In Studio, create an MCP Server connector as above with the gateway URL, and set Sign-in method to AWS IAM. Region is read from the gateway URL when you leave it blank, and Signing service stays blank for bedrock-agentcore.
  2. Choose Assume a role, and enter the Role ARN of a role in the account that owns the gateway (create it in the next step if it does not exist; you can enter its ARN first).
  3. Click Show Role setup. It shows the External ID (unique to this connector; required by the trust policy), the Trust policy (the role's trust relationship) and an Example permission policy for the role, each with Copy.
  4. In AWS, set the role's trust relationship to the trust policy, so only this Studio can assume it and only with the External ID, and attach the permission policy. It allows the single action bedrock-agentcore:InvokeGateway on your gateway's ARN.
  5. Click Test Connection.

To use this Studio's own role instead, choose Use this Studio's role. Show Role setup then gives This Studio's role and an Example resource policy for the gateway that lets that role invoke it. This works only for an AgentCore Gateway URL.

What you should see​

Passed. "Connected to server; n tools found." Under Tools, choose which tools agents may use and which ask before running, then click Discover Tools & Enrich Guide, accept the guide and click Create Connector (v1) (Choose the tools agents may use). Agents then call the gateway's tools directly; the token or signature is made by Studio and never reaches their code.

If the test fails​

You seeCheck
"The token endpoint rejected the client ID or secret (error)."The client ID, secret and tenant in the token URL; the secret has not expired.
"The server rejected the credentials (401)."The gateway's discovery URL and allowed audiences match the token's iss and aud; the token is version 2.0.
"The server accepted the credentials but refused access (403)."For Entra ID, allowed clients is empty and allowed audiences is set; the caller has permission on the API. For AWS IAM, the permission policy allows bedrock-agentcore:InvokeGateway on this gateway.
"Your sign-in for this connector has expired or its settings changed. Connect your account again."The person presses Connect Microsoft account again, using the account they use for Studio.
"Studio could not assume the role role ARN (403). Check that its trust policy allows this Studio and requires the External ID shown in Role setup."The role's trust policy is the one Role setup shows, with this connector's External ID.

Notes​

  • Rotate the client secret by opening the connector, choosing Update, entering the new client ID and secret and saving a new version; blank keeps the stored value.
  • A connector shared through a Library arrives without its credential: add your own, or for an assumed role add this Studio's External ID to the role's trust policy (Libraries and sharing).