
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:
- You add the gateway to Cowork as an OAuth-authenticated MCP connector.
- On first use, Cowork opens the Cognito hosted sign-in page in your browser and completes an authorization code flow with PKCE.
- Cowork sends the resulting access token as a bearer token on every MCP request.
- The gateway's JWT authorizer validates the token's client and scope, then runs the web search target.
- 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>/callbackPick 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, not127.0.0.1.
- Include the
/callbackpath. 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:
- Open the user pool and select the App clients tab, then open the generated
my-client-<suffix>client.
- Find the Login pages (or Hosted UI) section and choose Edit.
- Under Allowed callback URLs, add the loopback callback: the
httpscheme, thenlocalhost:<port>/callback, substituting the port you chose.
- Under OAuth 2.0 grant types, select Authorization code grant, and clear Client credentials.
- Under OpenID Connect scopes, select openid. Leave the existing custom scope
<gateway-name>/genesis-gateway:invokeselected.
- Save changes.
The equivalent CLI command. The callback is assembled from a variable so you set the port in one place:
SCHEME=httpCALLBACK="$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:
- Copy the Client ID.
- 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-knownsuffix.
- Leave
offline_accessoff. Amazon Cognito does not implement anoffline_accessscope, and requesting it makes the authorize call fail withinvalid_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:
- Your browser opens the Cognito hosted sign-in page, served from the domain on your user pool.
- 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.
- The browser redirects to the loopback address
localhost:<port>/callback, where Cowork is listening, and the page reports that sign-in is complete.
- Cowork exchanges the authorization code for tokens and calls the gateway.
- 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 methodExecuting tool ...WebSearch from target <target-id>Successfully processed requestEach 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
openidscope, 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_credentialsbreaks 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:
localhostonly, the/callbackpath 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.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article