Add safe Net Search to Claude Desktop with Amazon Bedrock AgentCore

Claude Desktop on Amazon Bedrock offers highly effective AI help, however with out built-in internet search, responses are restricted to the mannequin’s coaching data cutoff. Once you want present info, comparable to latest documentation updates, stay pricing, or climate updates, the mannequin can’t retrieve it by itself.

Amazon Bedrock AgentCore is a platform to construct, join, and optimize brokers at scale, with any framework or mannequin. With AgentCore Gateway, a functionality of Amazon Bedrock AgentCore, you’ll be able to shut this data cutoff hole by connecting Claude Desktop to Net Search. Net Search is a totally managed, Mannequin Context Protocol (MCP)-compatible internet search functionality backed by an Amazon internet index that spans tens of billions of paperwork. All question site visitors stays inside AWS infrastructure, with no exterior API keys to handle and no queries leaving your boundary.

With Claude Desktop, you should utilize managed MCP servers to connect with an AgentCore Gateway with the Net Search goal enabled. On this publish, we stroll by the steps to arrange this integration and use JSON Net Token (JWT)-based inbound authentication to safe the communication.

Structure

Many enterprises working on AWS use AWS IAM Identification Middle for single sign-on (SSO) entry to their AWS accounts. On this walkthrough, we use AWS IAM Identification Middle because the authentication supply for the AgentCore Gateway. With this setup, Claude Desktop on Amazon Bedrock can invoke Net Search by a trusted, enterprise-managed id circulate. This method aligns with current organizational id governance. No separate credentials or third-party id suppliers are required.

To bridge AWS IAM Identification Middle with the AgentCore Gateway JWT-based authentication, we use Amazon Cognito as a federation layer with the OAuth 2.0 authorization code grant circulate. IAM Identification Middle handles person authentication by Safety Assertion Markup Language (SAML). Amazon Cognito points JWTs, and the AgentCore Gateway validates them on every request. The complete authentication chain stays inside AWS.

The next sequence diagram illustrates this authentication circulate.

Determine 1: Person authentication and authorization sequence diagram

Stipulations

To comply with together with the steps on this publish, you want the next:

• An AWS account with permissions to create AWS Identification and Entry Administration (IAM) roles and Amazon Bedrock AgentCore sources.
• Admin entry to your administration account in AWS Organizations (for AWS IAM Identification Middle configuration).
• AWS IAM Identification Middle preconfigured for SSO entry to AWS accounts.
• Claude Desktop arrange with Amazon Bedrock because the inference supplier.
• The AWS Command Line Interface (AWS CLI) v2 put in and configured.
• Python 3.10 or later.
• The Boto3 SDK up to date to the newest model.

Net Search on Amazon Bedrock AgentCore is at present out there within the US East (N. Virginia) AWS Area (us-east-1), Europe (Eire) Area (eu-west-1), and Asia Pacific (Tokyo) Area (ap-northeast-1). Confirm that your gateway is created in considered one of these Areas.

Configuration

The configuration entails organising the authentication chain (AWS IAM Identification Middle to Amazon Cognito to JWT) after which wiring the AgentCore Gateway into Claude Desktop. We stroll by every step within the following part.

Step 1: Create an Amazon Cognito person pool

In your goal AWS account, create an Amazon Cognito person pool that may function the OpenID Join (OIDC) token issuer for the AgentCore Gateway.

export AWS_REGION=

# Create Person Pool
aws cognito-idp create-user-pool 
  --pool-name "agentcore-websearch-pool" 
  --region $AWS_REGION 
  --auto-verified-attributes electronic mail 
  --schema '[{"Name":"email","Required":true,"Mutable":true,"AttributeDataType":"String"}]' 
  --username-attributes electronic mail 
  --username-configuration "CaseSensitive=false" 
  --mfa-configuration "OFF"

# Be aware the Pool ID
export USER_POOL_ID=$(aws cognito-idp list-user-pools --max-results 10 
  --region $AWS_REGION 
  --query "UserPools[?Name=='agentcore-websearch-pool'].Id" --output textual content)
echo "Person Pool ID: $USER_POOL_ID"

# Create a website (have to be globally distinctive)
aws cognito-idp create-user-pool-domain 
  --domain "" 
  --user-pool-id $USER_POOL_ID 
  --region $AWS_REGION

Save these values for later steps:

• Person Pool ID: $USER_POOL_ID.
• Area: .auth..amazoncognito.com.
• Viewers: urn:amazon:cognito:sp:.
• ACS URL: https://.auth..amazoncognito.com/saml2/idpresponse.

Step 2: Configure IAM Identification Middle SAML utility

In your AWS Organizations administration account, create a SAML utility that federates with Cognito:

1. Open IAM Identification Middle console.
2. Select Purposes, Add utility, I’ve an utility I wish to arrange, SAML 2.0, after which Subsequent.
3. Fill within the following particulars:
   1. Show title: AgentCore Net Search.
   2. Choose Manually kind your metadata worth.
      1. ACS URL: https://.auth..amazoncognito.com/saml2/idpresponse.
      2. Viewers: urn:amazon:cognito:sp:.
   3. Obtain the SAML metadata XML file and select Submit.
   4. After the applying is created, edit the attribute mappings and insert the next values:
      1. Topic, ${person:topic}, Format: Persistent.
      2. Electronic mail, ${person:electronic mail}, Format: Primary.
   5. Assign the customers or teams that might have entry to Net Search.

Step 3: Wire SAML IdP into Cognito

Again within the goal account, register IAM Identification Middle as a SAML id supplier in your Cognito person pool:

# Add IAM Identification Middle as SAML IdP
METADATA=$(cat /path/to/downloaded-metadata.xml)

aws cognito-idp create-identity-provider 
  --user-pool-id $USER_POOL_ID 
  --provider-name "IAMIdentityCenterIdP" 
  --provider-type SAML 
  --provider-details " python3 -c 'import sys,json; print(json.dumps(sys.stdin.learn()))')" 
  --attribute-mapping '{"electronic mail": "electronic mail"}' 
  --region $AWS_REGION

Step 4: Create Cognito app shopper for Amazon Bedrock AgentCore

Create an app shopper with a shopper secret. Claude Desktop makes use of this shopper to provoke the OAuth circulate, which authenticates the person by IAM Identification Middle and obtains a JWT for the AgentCore Gateway:

aws cognito-idp create-user-pool-client 
  --user-pool-id $USER_POOL_ID 
  --client-name "agentcore-websearch-client" 
  --generate-secret 
  --supported-identity-providers "IAMIdentityCenterIdP" 
  --callback-urls '["http://localhost:53280/callback"]' 
  --allowed-o-auth-flows code 
  --allowed-o-auth-scopes "openid" "electronic mail" "profile" 
  --allowed-o-auth-flows-user-pool-client 
  --region $AWS_REGION

Be aware the Consumer ID and Consumer Secret from the output. These are your utility shopper ID and secret.

Step 5: Configure AgentCore Gateway with Net Search device

On this step, we create a brand new AgentCore Gateway with Inbound Auth Sort as JSON Net Tokens (JWT). For this configuration, we use the Cognito person pool ID and utility shopper ID that have been created within the prior steps.

Run the next Python script to create the gateway with the required configurations, changing all placeholders with precise values out of your setting.

import boto3
import json
import time

session = boto3.Session(region_name="your-region")
iam_client = session.shopper("iam")
gateway_client = session.shopper("bedrock-agentcore-control")

ACCOUNT_ID = "your-target-aws-account-id"
ROLE_NAME = "websearch-gateway-role"
GATEWAY_NAME = "websearch-gateway"
COGNITO_DISCOVERY_URL = "https://cognito-idp..amazonaws.com//.well-known/openid-configuration"
COGNITO_CLIENT_ID = ""

# --- Step 1: Create IAM execution position ---
trust_policy = {
    "Model": "2012-10-17",
    "Assertion": [{
        "Effect": "Allow",
        "Principal": {"Service": "bedrock-agentcore.amazonaws.com"},
        "Action": "sts:AssumeRole",
        "Condition": {
            "StringEquals": {"aws:SourceAccount": ACCOUNT_ID}
        }
    }]
}

permissions_policy = {
    "Model": "2012-10-17",
    "Assertion": [
        {
            "Sid": "GetGateway",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:GetGateway",
            "Resource": f"arn:aws:bedrock-agentcore:us-east-1:{ACCOUNT_ID}:gateway/*"
        },
        {
            "Sid": "GetConfigBundle",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:GetConfigurationBundleVersion",
            "Resource": f"arn:aws:bedrock-agentcore:us-east-1:{ACCOUNT_ID}:configuration-bundle/*"
        },
        {
            "Sid": "InvokeWebSearch",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:InvokeWebSearch",
            "Resource": "arn:aws:bedrock-agentcore:us-east-1:aws:tool/web-search.v1"
        }
    ]
}

strive:
    iam_client.create_role(
        RoleName=ROLE_NAME,
        AssumeRolePolicyDocument=json.dumps(trust_policy),
        Description="Execution position for internet search AgentCore gateway",
    )
    print(f"✓ Function '{ROLE_NAME}' created.")
besides iam_client.exceptions.EntityAlreadyExistsException:
    print(f"✓ Function '{ROLE_NAME}' already exists, reusing.")

iam_client.put_role_policy(
    RoleName=ROLE_NAME,
    PolicyName="websearch-gateway-policy",
    PolicyDocument=json.dumps(permissions_policy),
)
print(f"✓ Inline coverage hooked up to '{ROLE_NAME}'.")

# --- Step 2: Create the gateway ---
response = gateway_client.create_gateway(
    title=GATEWAY_NAME,
    description="AgentCore gateway with managed Net Search connector",
    roleArn=f"arn:aws:iam::{ACCOUNT_ID}:position/{ROLE_NAME}",
    protocolType="MCP",
    protocolConfiguration={
        "mcp": {
            "supportedVersions": ["2025-03-26"],
        }
    },
    authorizerType="CUSTOM_JWT",
    authorizerConfiguration={
        "customJWTAuthorizer": {
            "discoveryUrl": COGNITO_DISCOVERY_URL,
            "allowedClients": [COGNITO_CLIENT_ID],
        }
    },
)
gateway_id = response["gatewayId"]
gateway_url = response.get("gatewayUrl")
print(f"✓ Gateway created: {gateway_id}")
print(f" URL: {gateway_url}")

# --- Step 3: Look ahead to gateway to change into READY ---
print(" Ready for gateway to achieve READY standing...", finish="", flush=True)
for i in vary(40):  # as much as ~10 minutes
    resp = gateway_client.get_gateway(gatewayIdentifier=gateway_id)
    standing = resp.get("standing")
    if standing == "READY":
        print(f" READY (after {(i+1)*15}s)")
        break
    elif standing == "FAILED":
        print(f"n✗ Gateway entered FAILED standing.")
        causes = resp.get("statusReasons", [])
        for r in causes:
            print(f" Motive: {r}")
        exit(1)
    print(".", finish="", flush=True)
    time.sleep(15)
else:
    print(f"n✗ Gateway didn't attain READY inside 10 minutes (final standing: {standing})")
    exit(1)

# --- Step 4: Connect the managed Net Search connector goal ---
gateway_client.create_gateway_target(
    gatewayIdentifier=gateway_id,
    title="web-search-tool",
    description="Managed Net Search connector",
    targetConfiguration={
        "mcp": {
            "connector": {
                "supply": {"connectorId": "web-search"},
                "configurations": [{"name": "WebSearch", "parameterValues": {}}],
            }
        }
    },
    credentialProviderConfigurations=[
        {"credentialProviderType": "GATEWAY_IAM_ROLE"}
    ],
)
print("✓ Net search goal hooked up.")
print()
print("=" * 60)
print(f" Gateway ID: {gateway_id}")
print(f" Gateway URL: {gateway_url}")
print(f" Auth: CUSTOM_JWT (Cognito)")
print(f" Goal: web-search (managed connector)")
print("=" * 60)

You now have an AgentCore Gateway with Net Search device, with JWT-based inbound authorization.

Step 6: Configure Claude Desktop

Use the steps within the Claude Desktop configuration documentation to entry the configuration window for Claude Desktop with Amazon Bedrock. After you open it, select Connectors and Extensions, then select Add server, after which select Clean.

The next screenshot reveals the configuration window with these choices.

Determine 2: Claude Desktop connector configuration window

Enter the next particulars:

1. Identify: websearchtool.
2. Transport: Streamable HTTP.
3. URL: Enter the gateway useful resource URL for the AgentCore Gateway created in Step 5.
4. OAuth: Convey your individual shopper.
5. Consumer ID: Enter the shopper ID for the app shopper created in Step 4.
6. Consumer Secret: Enter the shopper secret for the app shopper created in Step 4.
7. Authorization Server: Enter ["https://.auth..amazoncognito.com/oauth2/authorize"].
8. Scope: openid.
9. Callback host: localhost.
10. Callback port: 53280.

Once you’re executed, select sign up and check. This could open a browser so that you can authenticate, redirecting you to your AWS IAM Identification Middle SSO login. Enter your credentials to authenticate. If profitable, you must see a message comparable to, “Authorization full. You possibly can shut this tab and return to Claude.”

Again in Claude Desktop, you must see a profitable MCP registration message like within the following picture.

Determine 3: Profitable MCP server registration in Claude Desktop

Claude Desktop will now uncover the WebSearchTool by the MCP instruments/checklist name. It invokes the device mechanically each time the mannequin wants present info from the online.

Testing and validation

In your most popular interface (for instance, Chat or Cowork), ship a question that requires Claude Desktop to retrieve the newest outcomes. It’s best to see a device execution approval field, indicating that Claude has efficiently found the Net Search device. On approval, you must see the online search outcomes included within the response.

Determine 4: Net Search device execution approval dialog

The dialog reveals the question Claude needs to run and presents three choices: Deny, Permit for this job, or Permit as soon as. On approval, Net Search outcomes are included within the response.

Clear up

If you happen to created sources whereas following alongside, carry out the next steps to delete them:

# Delete the gateway goal
aws bedrock-agentcore-control delete-gateway-target --gateway-identifier  --target-id  --region $AWS_REGION

# Delete the gateway (provided that it was created for this walkthrough)
aws bedrock-agentcore-control delete-gateway --gateway-identifier  --region $AWS_REGION

# Delete the IAM coverage (provided that it was created for this walkthrough)
aws iam delete-role-policy --role-name websearch-gateway-role --policy-name websearch-gateway-policy

# Delete the IAM position (provided that it was created for this walkthrough)
aws iam delete-role --role-name websearch-gateway-role

# Delete the Cognito utility shopper
aws cognito-idp delete-user-pool-client --user-pool-id $USER_POOL_ID --client-id  --region $AWS_REGION

# Delete the Cognito id supplier
aws cognito-idp delete-identity-provider --user-pool-id $USER_POOL_ID --provider-name IAMIdentityCenterIdP --region $AWS_REGION

# Delete the Cognito pool area
aws cognito-idp delete-user-pool-domain --user-pool-id $USER_POOL_ID --domain  --region $AWS_REGION

# Delete the cognito pool
aws cognito-idp delete-user-pool --user-pool-id $USER_POOL_ID --region $AWS_REGION

Lastly, within the IAM Identification Middle console within the administration account, delete the SAML utility you created in Step 2.

Conclusion

On this publish, we walked by integrating Net Search on AgentCore with Claude Desktop. Whereas this walkthrough makes use of AWS IAM Identification Middle because the id supplier, the identical sample works with any SAML or OIDC-compatible id supplier. You possibly can substitute your current IdP by configuring it as a federation supply in Amazon Cognito. This method closes the online search hole with out introducing third-party dependencies, and all queries keep inside your AWS boundary.

To get began, comply with the steps above to arrange the combination in your individual setting. For superior gateway configurations, see the AgentCore Gateway Developer Information. To be taught extra about Net Search, see the Net Search documentation.

In regards to the creator