AWS Builder Center
Add Web Search to Claude Cowork with AgentCore Gateway

Add Web Search to Claude Cowork with AgentCore Gateway

Give Claude Cowork a web search tool via Amazon Bedrock AgentCore Gateway: Cognito OAuth setup, the MCP connector, and CloudWatch verification.

Claude Cowork can be extended with tools through the Model Context Protocol (MCP). Amazon Bedrock AgentCore Gateway can publish capabilities — including a managed web search target — as an MCP server. Connect the two and Cowork gains a web search tool that runs through infrastructure you own, is authenticated by your own identity provider, and is fully logged in Amazon CloudWatch.
The convenient part: when you create an AgentCore Gateway with JWT inbound authorization, the console provisions an Amazon Cognito user pool for you — pool, app client, hosted sign-in domain, and a resource server with a scope. You do not build identity from scratch. What you do need are three small changes to that generated pool so a person can sign in interactively, and then a connector in Cowork.
All identifiers in this post are placeholders. Substitute your own values for anything in  <angle brackets> .

How the pieces fit together

Cowork speaks MCP to your gateway's endpoint over streamable HTTP. You will find the exact endpoint on the gateway's detail page in the console: an HTTPS address containing your gateway ID and region, ending in the path  /mcp . Copy it from there rather than assembling it by hand.
The end-to-end flow:
  1. You add the gateway to Cowork as an OAuth-authenticated MCP connector.
  1. On first use, Cowork opens the Cognito hosted sign-in page in your browser and completes an authorization code flow with PKCE.
  1. Cowork sends the resulting access token as a bearer token on every MCP request.
  1. The gateway's JWT authorizer validates the token's client and scope, then runs the web search target.
  1. Results return to your Cowork session as ordinary tool output.

Prerequisites

  • An AWS account with permission to create an AgentCore Gateway and edit Amazon Cognito resources.
  • Claude Cowork installed, with access to its Connectors settings.
  • The AWS CLI, if you prefer commands to console clicks. Both are shown.

Step 1: Create the gateway with JWT inbound authorization

In the AWS Management Console, open Amazon Bedrock AgentCore, go to Gateways, and choose Create gateway. Give it a name, add your web search target, and for inbound authorization choose the JWT / OAuth option rather than IAM. Accept the option to create a new Cognito user pool (this is the quick-create path) and finish creating the gateway.
When it completes, note the gateway's MCP endpoint URL — it ends in  /mcp .
The console has now created a set of Cognito resources on your behalf, with generated names:
Resource
Generated name pattern
Purpose
User pool
 my-user-pool-<suffix> 
Holds identities and issues tokens
App client
 my-client-<suffix> 
The OAuth client, with a client secret
Hosted domain
 my-domain-<suffix> 
Serves the sign-in and token endpoints
Resource server
named after your gateway
Owns the custom scope
Custom scope
 <gateway-name>/genesis-gateway:invoke 
What the gateway authorizes on
The gateway's authorizer is already wired to this pool: it holds the pool's OpenID Connect discovery URL, the app client ID in its allowed clients, and the scope above in its allowed scopes. You do not need to touch the authorizer.
One thing to understand about what was generated: the app client is configured for machine-to-machine access — the  client_credentials  grant, with a client secret and the custom scope, and no callback URL. That is right for a backend service calling the gateway, but a person cannot sign in with it. Steps 2 through 4 fix that.
To find the generated names, open Amazon Cognito, choose User pools, and look for the  my-user-pool-<suffix>  entry. Note its User pool ID (of the form  <region>_xxxxxxxxx ); you will need it below.

Step 2: Confirm self-service sign-up is disabled

This pool gates access to your gateway, so users should be created deliberately by an administrator rather than by anyone who reaches the sign-in page.
In the console: open the user pool, select the Sign-up tab, and look at Self-service sign-up. Choose Edit and clear the Enable self-registration checkbox if it is set.
To verify from the CLI — a value of  true  means only administrators can create users, which is what you want:
aws cognito-idp describe-user-pool \
--user-pool-id <user-pool-id> --region <region> \
--query 'UserPool.AdminCreateUserConfig.AllowAdminCreateUserOnly'

Step 3: Enable interactive login on the app client

Now convert the generated app client from machine-to-machine to interactive sign-in. Three changes are needed: add the authorization code grant, add the  openid  scope, and register a callback URL.
Before you edit, decide the callback URL, because it must match exactly. Cowork completes sign-in on a local loopback address, and its redirect URI has four parts: the  http  scheme, the host  localhost , a port, and the path  /callback . Written out, it takes this shape:
localhost:<port>/callback
Pick a port and keep it fixed — for example  8765  — and use the identical value in Cognito and in the Cowork connector later. Cognito compares redirect URIs by exact string match and permits plain  http  only for  localhost . Three rules follow:
  • Use  localhost , not  127.0.0.1 .
  • Include the  /callback  path. Registering just the host and port, with no path, will not match.
  • Use the same port on both sides. If the port varies between sign-in attempts, the match breaks.
In the console:
  1. Open the user pool and select the App clients tab, then open the generated  my-client-<suffix>  client.
  1. Find the Login pages (or Hosted UI) section and choose Edit.
  1. Under Allowed callback URLs, add the loopback callback: the  http  scheme, then  localhost:<port>/callback , substituting the port you chose.
  1. Under OAuth 2.0 grant types, select Authorization code grant, and clear Client credentials.
  1. Under OpenID Connect scopes, select openid. Leave the existing custom scope  <gateway-name>/genesis-gateway:invoke  selected.
  1. Save changes.
The equivalent CLI command. The callback is assembled from a variable so you set the port in one place:
SCHEME=http
CALLBACK="$SCHEME://localhost:8765/callback"

aws cognito-idp update-user-pool-client \
--user-pool-id <user-pool-id> \
--client-id <client-id> \
--allowed-o-auth-flows-user-pool-client \
--allowed-o-auth-flows code \
--allowed-o-auth-scopes openid "<gateway-name>/genesis-gateway:invoke" \
--callback-urls "$CALLBACK" \
--supported-identity-providers COGNITO \
--region <region>
Confirm the result:
aws cognito-idp describe-user-pool-client \
--user-pool-id <user-pool-id> --client-id <client-id> --region <region> \
--query 'UserPoolClient.{Flows:AllowedOAuthFlows,Scopes:AllowedOAuthScopes,Callbacks:CallbackURLs}'
You are looking for  Flows  containing  code ,  Scopes  containing both  openid  and the custom scope, and  Callbacks  listing your exact callback URL.
One note before moving on: this client can no longer do machine-to-machine calls. Removing  client_credentials  breaks any backend service authenticating with this client. If you have one, create a second app client for Cowork instead and add its client ID to the gateway authorizer's allowed clients.

Copy the client ID and client secret

The client that AgentCore generated is a confidential client — it has a client secret, and changing the grant type does not remove it. Cognito therefore requires client authentication at the token exchange, so Cowork must present that secret alongside the PKCE code verifier. This catches people out, because a desktop application is more commonly a public client with no secret at all.
On the same app client page in the console:
  1. Copy the Client ID.
  1. Next to Client secret, choose Show client secret and copy the value.
Keep both to hand for step 5 — you will paste them into the connector. Treat the secret like any other credential: it is not a public identifier, so avoid pasting it into shared documents or tickets. If your Cowork deployment supports sourcing the value from a helper script or secret store rather than typing it in, prefer that.
If you would rather not manage a secret at all, create a new app client as a public client with no secret (PKCE only), give it the authorization code grant, the  openid  scope, the custom scope, and the same callback URL, then add its client ID to the gateway authorizer's allowed clients. Both approaches work; this post continues with the generated confidential client.

Step 4: Create a user in the user pool

Interactive sign-in needs an actual account, and with self-registration disabled you create it as an administrator.
In the console: open the user pool, select the Users tab, and choose Create user. Enter a username, optionally an email address, and either set a password or let Cognito generate a temporary one. If you check Mark email address as verified, you avoid a verification step at first sign-in.
The equivalent CLI commands — the second one sets a permanent password so the first sign-in does not require a password change:
aws cognito-idp admin-create-user \
--user-pool-id <user-pool-id> \
--username <username> \
--message-action SUPPRESS \
--region <region>

aws cognito-idp admin-set-user-password \
--user-pool-id <user-pool-id> \
--username <username> \
--password '<strong-password>' \
--permanent \
--region <region>
If you leave the user with a temporary password instead, their status stays  FORCE_CHANGE_PASSWORD  and Cognito prompts them to choose a new password during the first sign-in. Both paths work; just know which one you chose before you test.

Step 5: Add the connector in Cowork

Open Cowork's settings and go to the Connectors section. Add a connector and choose the blank template — that gives you an empty MCP server form rather than a preconfigured third-party service.
One caution: Cowork also ships a built-in connector named Web search that accepts a custom provider URL. Do not put your gateway URL there. That provider expects a plain HTTP endpoint taking a  { "q": "..." }  POST and returning a  results[]  array, which is not the MCP protocol your gateway speaks. The blank template is the right starting point.
Fill in the form as follows. Field labels vary slightly between Cowork versions; the underlying setting name is given in parentheses where it helps.
Field
Value
Name
 AgentCore Web Search 
Transport
Streamable HTTP ( http )
Server URL ( url )
Your gateway's MCP endpoint, copied from the gateway detail page (HTTPS, ending in  /mcp )
Authentication
OAuth (enable the OAuth option rather than static headers)
Authorization server / issuer ( oauth.authorizationServer )
Your user pool's OpenID Connect issuer — see the note below the table for where to find it
Client ID ( oauth.clientId )
The generated client's ID
Client secret ( oauth.clientSecret )
The generated client's secret — required, because the generated client is confidential
Scope ( oauth.scope )
 openid <gateway-name>/genesis-gateway:invoke 
Callback host ( oauth.callbackHost )
 localhost 
Callback port ( oauth.callbackPort )
 8765  — the same port you registered in step 3
Append offline_access ( oauth.appendOfflineAccess )
Off / No
Three details that matter:
  • Finding the issuer value. Open your user pool in the console and look at the Token signing key URL on the overview page. Your issuer is that value with the trailing discovery path removed — that is, everything up to and including your user pool ID. Enter the issuer only: Cowork appends the OpenID Connect discovery path itself when it fetches the pool's metadata, so do not include any  .well-known  suffix.
  • Leave  offline_access  off. Amazon Cognito does not implement an  offline_access  scope, and requesting it makes the authorize call fail with  invalid_scope . Cognito issues a refresh token for the authorization code flow regardless, so sessions still persist without re-authenticating.
  • The scope must include both  openid , so the interactive OIDC sign-in works, and the custom scope, so the token satisfies the gateway authorizer's allowed scopes.
If the connector form displays the exact redirect URI it will use, compare it against what you registered in step 3 and make them identical.

Step 6: Test the connection and sign in

Use the connector's Test this connection action. It performs a real MCP  initialize  and  tools/list  against the gateway using the credentials you entered, which exercises the entire chain in one click.
What you should see:
  1. Your browser opens the Cognito hosted sign-in page, served from the domain on your user pool.
  1. Sign in with the username and password from step 4. If you left a temporary password in place, Cognito now asks you to set a new one.
  1. The browser redirects to the loopback address  localhost:<port>/callback , where Cowork is listening, and the page reports that sign-in is complete.
  1. Cowork exchanges the authorization code for tokens and calls the gateway.
  1. The test result reports the round-trip latency and lists the tools the gateway exposes.
A returned tool list is meaningful confirmation, not just a reachability check: the gateway only answers  tools/list  for a request whose token it accepted. Sign-in, token validation, and authorization all passed.
The web search tool is now available in your Cowork sessions, and the token refreshes silently, so you are not asked to sign in again each session. If you want to control how the tool is approved at call time, the connector's tool permission settings let you pre-approve it or require confirmation per call.

Step 7: Enable observability and verify the calls

Gateway tool invocations are data-plane traffic, so they never appear in AWS CloudTrail. To see them, enable observability on the gateway, which delivers application logs to CloudWatch Logs.
This is configured as a CloudWatch log delivery: your gateway is the delivery source with log type  APPLICATION_LOGS , and a CloudWatch log group is the destination. Expressed with an SDK, which makes each piece explicit:
import boto3

logs = boto3.client("logs", region_name="<region>")

log_group = "/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/<gateway-id>"
logs.create_log_group(logGroupName=log_group)

source = logs.put_delivery_source(
name="<gateway-id>-logs-source",
logType="APPLICATION_LOGS",
resourceArn="arn:aws:bedrock-agentcore:<region>:<account-id>:gateway/<gateway-id>",
)

destination = logs.put_delivery_destination(
name="<gateway-id>-logs-destination",
deliveryDestinationType="CWL",
deliveryDestinationConfiguration={
"destinationResourceArn": f"arn:aws:logs:<region>:<account-id>:log-group:{log_group}"
},
)

logs.create_delivery(
deliverySourceName=source["deliverySource"]["name"],
deliveryDestinationArn=destination["deliveryDestination"]["arn"],
)
Now ask Cowork something that requires a search, and tail the log group:
aws logs tail \
"/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/<gateway-id>" \
--follow --region <region>
A healthy invocation writes a clear lifecycle at  INFO :
Started processing request (method=tools/call, name=...WebSearch, clientInfo=claude-desktop-3p)
Received request for tools/call method
Executing tool ...WebSearch from target <target-id>
Successfully processed request
Each entry carries a  request_id  and  trace_id  for correlation, the  requestBody  shows the actual search query, and  clientInfo  identifies Cowork as the caller.  isError: false  on every line means the token was accepted and the search ran.
To watch only failures:
aws logs filter-log-events \
--log-group-name "/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/<gateway-id>" \
--filter-pattern '"isError":true' --region <region>
Request and response bodies are logged in full, including search queries and returned page content. Set a retention period on the log group and treat it as you would any log containing user activity.

Troubleshooting reference

Symptom
Cause
Fix
 error=redirect_mismatch  on the Cognito page
The registered callback does not exactly match what Cowork sent — missing  /callback , wrong host, or a different port
Register the loopback callback exactly:  http  scheme,  localhost:<port>/callback . Use  localhost , not  127.0.0.1 , and the same port in Cognito and Cowork
 unauthorized_client 
The app client still has only the  client_credentials  grant
Select Authorization code grant and add the  openid  scope (step 3)
 invalid_scope 
 offline_access  was requested; Cognito has no such scope
Turn off the append offline_access option
 invalid_client  at token exchange
The generated client is confidential and its secret was not entered
Enter the client secret in the connector
Sign-in page loads but no account works
No user exists in the pool, and self-registration is disabled
Create a user as an administrator (step 4)
Prompted to change password at first sign-in
The user still has a temporary password
Expected. Set the new password, or pre-set a permanent one with  admin-set-user-password --permanent 
 401 Unauthorized  from the gateway
The gateway is not validating tokens from this pool
Confirm the gateway was created with JWT inbound authorization against this user pool
 403 Forbidden  after a successful sign-in
The token is valid, but its client or scope is not accepted
Confirm the client ID is in the authorizer's allowed clients and the custom scope is in both the client and the connector
Test succeeds, but no logs appear
Observability is not enabled; data-plane calls are absent from CloudTrail
Create an  APPLICATION_LOGS  delivery to a CloudWatch log group (step 7)

Key takeaways

  • Creating the gateway with JWT inbound authorization gives you the whole Cognito setup — pool, client, hosted domain, resource server, and scope — already wired to the authorizer. Reuse it rather than building identity by hand.
  • The generated app client is machine-to-machine. Interactive sign-in needs three edits: the authorization code grant, the  openid  scope, and a registered callback URL.
  • The generated client keeps its secret after conversion, so enter that secret in the connector. And remember that removing  client_credentials  breaks any backend caller using the same client.
  • Create a user explicitly. With self-registration disabled, there is no account to sign in with until an administrator makes one.
  • The callback URL is matched exactly:  localhost  only, the  /callback  path included, and one pinned port used on both sides.
  • Enable observability. Tool invocations never reach CloudTrail, and the application log group is what shows you the query, the target, and whether the token was accepted.
With the connector in place, your AgentCore Gateway web search tool appears in Cowork as a first-class tool — authenticated by users in your own directory, authorized by scope, and observable in CloudWatch.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article