Connect Guru to Amazon Connect

Amazon Connect AI agents can call outside tools while your reps handle a contact. This guide connects those AI agents to Guru's MCP server, so when a rep asks the Connect assistant a question during a chat, the answer comes from your verified Guru content, with the source cards behind it.

Amazon Connect doesn't call MCP servers directly. Requests go through an Amazon Bedrock AgentCore gateway, which checks that the caller is your Connect instance, signs in to Guru with a stored API token, and passes the tool call along.

This guide covers the agent assist use case, where Guru helps your reps during chat contacts. Almost every step happens in a web interface: Guru, the AWS console, and your Amazon Connect admin website. One step, creating the gateway, requires a single command in AWS CloudShell, which runs in your browser with nothing to install. Where a step can also be done from the command line, the commands are in an expandable section.

Before you begin

You need the following access.

Collect these values as you go. You'll use them in several steps.

📘

Amazon Connect naming

In newer versions of the AWS console, Amazon Connect appears as Amazon Connect Customer in search results. Both names refer to the same service.

Step 1: Create a Guru API token

The gateway signs in to Guru as one Guru user, and every answer reflects what that user can see. Use a dedicated service user rather than a person's account, and give it read access only to the collections your reps should get answers from. That keeps internal-only content out of customer conversations and keeps the integration working when people leave.

Where: Guru, signed in as the service user.

1. Go to Manage, then Integrations, then API Access, or open https://app.getguru.com/manage/integrations/api-access directly.
2. Generate a user token and copy it somewhere safe. You need it in Step 5.

Step 2: Choose a Knowledge Agent

Guru's answer tool requires a Knowledge Agent, which decides which sources and collections an answer can draw from. Pick one that covers your support content, or create a dedicated one (for example, "Customer Support").

Where: Guru, then Agents.

1. Open the Knowledge Agent you want to use.
2. Copy its ID from the page URL in your browser. The URL looks like https://app.getguru.com/agents/e26e4851-ee18-473b-9b63-27b64dc92839, and the ID is everything after /agents/.
3. Ask it a question your reps commonly get, and confirm the answer is right. The AI agent in Connect will answer from the same content.

export GURU_USER="[email protected]"
export GURU_TOKEN="your-api-token"

curl -s -X POST https://mcp.api.getguru.com/mcp \
  -u $GURU_USER:$GURU_TOKEN \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"guru_list_knowledge_agents","arguments":{}}}'

[
  {
    "id": "e26e4851-ee18-473b-9b63-27b64dc92839",
    "name": "Customer Support",
    "sources": [],
    "collections": [
      {
        "name": "Support Policies",
        "id": "650c82c0-be6e-4d27-9f79-05288dd16488"
      }
    ]
  },
  ...
]

curl -s -X POST https://mcp.api.getguru.com/mcp \
  -u $GURU_USER:$GURU_TOKEN \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"guru_answer_generation","arguments":{"question":"How do I reset a customer password?","agentId":"YOUR_KNOWLEDGE_AGENT_ID"}}}'

Step 3: Create the gateway's IAM role

The gateway needs an IAM role to retrieve your Guru credential when it calls Guru. You create this role yourself because the gateway is created from CloudShell in Step 4, and the role the console creates automatically only works for console-created gateways.

Where: AWS console, then IAM, then Roles, then Create role.

1. Under Trusted entity type, choose Custom trust policy.
2. Replace the policy in the editor with the following, swapping in your Region and account ID:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "bedrock-agentcore.amazonaws.com" },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": { "aws:SourceAccount": "YOUR_ACCOUNT_ID" },
        "ArnLike": { "aws:SourceArn": "arn:aws:bedrock-agentcore:YOUR_REGION:YOUR_ACCOUNT_ID:gateway/guru-connect-gateway-*" }
      }
    }
  ]
}

3. Choose Next. Skip Add permissions by choosing Next again.
4. Set Role name to GuruConnectGatewayRole and choose Create role.

Now give the role permission to fetch the stored credential:

1. Open GuruConnectGatewayRole from the roles list.
2. Choose Add permissions, then Create inline policy, then switch the editor to JSON.
3. Replace the policy with the following, swapping in your Region and account ID:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetWorkloadAccessToken",
        "bedrock-agentcore:GetResourceApiKey"
      ],
      "Resource": "arn:aws:bedrock-agentcore:YOUR_REGION:YOUR_ACCOUNT_ID:*"
    },
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:YOUR_REGION:YOUR_ACCOUNT_ID:secret:bedrock-agentcore-identity!default/*"
    }
  ]
}

4. Choose Next, name the policy GuruConnectGatewayAccess, and choose Create policy.

The trust policy only lets gateways whose names start with guru-connect-gateway use this role, which matches the gateway you create in Step 4.

export ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

cat > trust.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "bedrock-agentcore.amazonaws.com" },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": { "aws:SourceAccount": "$ACCOUNT_ID" },
        "ArnLike": { "aws:SourceArn": "arn:aws:bedrock-agentcore:$AWS_REGION:$ACCOUNT_ID:gateway/guru-connect-gateway-*" }
      }
    }
  ]
}
EOF

cat > permissions.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetWorkloadAccessToken",
        "bedrock-agentcore:GetResourceApiKey"
      ],
      "Resource": "arn:aws:bedrock-agentcore:$AWS_REGION:$ACCOUNT_ID:*"
    },
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:$AWS_REGION:$ACCOUNT_ID:secret:bedrock-agentcore-identity!default/*"
    }
  ]
}
EOF

aws iam create-role \
  --role-name GuruConnectGatewayRole \
  --assume-role-policy-document file://trust.json \
  --query Role.Arn --output text

aws iam put-role-policy \
  --role-name GuruConnectGatewayRole \
  --policy-name GuruConnectGatewayAccess \
  --policy-document file://permissions.json

Step 4: Create the gateway

❗️

This step requires CloudShell

The Create gateway wizard in the AgentCore console creates a gateway without the MCP protocol type. Amazon Connect rejects those gateways in Step 8 with "Access URL for MCP server applications must be a valid Bedrock Agent Core Gateway URL," and the setting can't be changed after creation. The command below is the only step in this guide that can't be done in the console.

Where: AWS CloudShell. Open it from the CloudShell link in the bottom-left of the AWS console, and confirm the Region in the top-right matches your Connect instance.

Copy the command below, replace https://example-corp.my.connect.aws on the first line with your Connect access URL (no trailing slash), then paste it into CloudShell and press Enter:

export CONNECT_URL="https://example-corp.my.connect.aws"
export ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

aws bedrock-agentcore-control create-gateway \
  --name guru-connect-gateway \
  --role-arn "arn:aws:iam::$ACCOUNT_ID:role/GuruConnectGatewayRole" \
  --protocol-type MCP \
  --protocol-configuration '{"mcp":{"supportedVersions":["2025-03-26","2025-06-18","2025-11-25"]}}' \
  --authorizer-type CUSTOM_JWT \
  --authorizer-configuration "{\"customJWTAuthorizer\":{\"discoveryUrl\":\"$CONNECT_URL/.well-known/openid-configuration\",\"allowedAudience\":[\"placeholder\"]}}" \
  --query '{gatewayId:gatewayId,gatewayUrl:gatewayUrl,status:status}' \
  --no-cli-pager

The response shows the new gateway:

{
  "gatewayId": "guru-connect-gateway-qwd65lce62",
  "gatewayUrl": "https://guru-connect-gateway-qwd65lce62.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp",
  "status": "CREATING"
}

Copy the gatewayId. Confirm gatewayUrl ends in /mcp; that's how you know the gateway has the MCP protocol type. If the command fails with an error about the role, wait 30 seconds and run it again, since new IAM roles can take a few seconds to become usable.

What the command sets up:

Keep CloudShell open if you plan to encode your credential there in the next step.

Step 5: Store the Guru credential

The gateway sends your credential to Guru as a Basic authorization header, which needs your email and token joined by a colon and base64-encoded. Encode them in CloudShell, which is already open from Step 4:

printf '%s' '[email protected]:YOUR_API_TOKEN' | base64 | tr -d '\n'

Copy the output. Don't paste your token into an online base64 tool, since that sends your credential to a third-party site.

printf '%s' '[email protected]:YOUR_API_TOKEN' | base64 | tr -d '\n'

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('[email protected]:YOUR_API_TOKEN'))

Where: AWS console, then Amazon Bedrock AgentCore, then Identity in the left navigation.

1. Under Outbound Auth, choose Add Outbound Auth, then Add API key.
2. Set Name to guru-mcp.
3. Keep API key only selected.
4. Paste the base64 value as the key. Don't add the word Basic; you set that prefix in Step 7.
5. Choose Add.

Step 6: Set the gateway's allowed audience

Amazon Connect includes the gateway ID in every request, and the gateway rejects requests whose audience doesn't match.

Where: AWS console, then Amazon Bedrock AgentCore, then Gateways, then guru-connect-gateway.

1. Wait for the gateway's Status to show Ready.
2. In the Inbound Auth section, choose Edit.
3. Replace placeholder under Allowed audiences with your gateway ID, for example guru-connect-gateway-qwd65lce62.
4. Leave Allowed clients, Allowed scopes, and Custom claims empty, and save.

Step 7: Add Guru as the gateway target

Where: The same gateway page. Scroll to Targets and choose Add.

Expand Additional configurations and set the header:

Leave everything else at its default and save. The target should show Ready with a Last synced time, which means AWS connected to Guru and saved Guru's tool list.

❗️

Check the credential after any target edit

Editing a target in the console can clear its outbound auth settings. Whenever you edit the guru target, expand Additional configurations and confirm the API key, header, parameter name, and prefix are still set before you save.

Step 8: Register the gateway with Amazon Connect

Where: AWS console, then Amazon Connect, then Integrations in the left navigation, then Add integration.

1. Set Display name to Guru.
2. Under Integration type, choose MCP server.
3. Under Gateway, select guru-connect-gateway.
4. Under Instance association, select your Connect instance. Only instances that match the gateway's discovery URL appear.
5. Choose Add integration.

Step 9: Create a security profile for the AI agent

Connect controls which tools an AI agent can call with security profiles, the same way it controls what reps can do. Grant only Guru's read tools. Guru's MCP server also includes tools that create and edit content, and a contact center AI agent shouldn't have them.

Where: Your Connect admin website (the access URL from Before you begin), then Users, then Security profiles, then Add new security profile.

1. Name the profile Guru AI Agent.
2. Scroll to Tools. Guru's tools appear with names like guru___guru_answer_generation.
3. Check Access on these five tools only:

4. Save the profile.

If no Guru tools appear, open the guru target in AgentCore and confirm its listing mode is Default and it shows a Last synced time, then refresh the security profile page.

Step 10: Give your reps the same tool access

For agent assist, Connect only lets the AI agent call a tool if the rep it's helping also has access to that tool. If you skip this step, the AI agent silently won't use Guru for your reps.

Where: Connect admin website, then Users.

Choose one approach:

1. Add the profile to your reps. In User management, add the Guru AI Agent profile to each rep alongside their existing profile. Users can have more than one profile, and permissions combine.
2. Edit your reps' existing profile. In Security profiles, open the profile your reps use (often Agent), choose Edit, and check Access on the same five Guru tools under Tools. If Tools doesn't appear, turn off Show enabled only.

Step 11: Create the AI agent

Where: Connect admin website, then AI agent designer, then AI agents, then Create AI agent.

1. Set Name to Guru-Agent-Assist. Names can't contain spaces.
2. Set AI Agent type to Orchestration. It's the only type that can call outside tools.
3. Under Copy from existing, choose AgentAssistanceOrchestrator, the built-in agent assist template.
4. Leave Description empty, since descriptions can't contain spaces, and choose Create.

On the agent's edit page:

1. Under Security Profiles, select Guru AI Agent.
2. Under Tools, remove Retrieve and GenerateNotes. They come from the template, and leaving Retrieve in place lets the AI agent search Amazon Connect's built-in knowledge base instead of Guru.
3. Choose Add tool, keep Add existing AI Tool, and set Namespace to gateway_ followed by your gateway ID, for example gateway_guru-connect-gateway-qwd65lce62.
4. Add the five Guru tools from Step 9, one at a time. Leave User Confirmation off for each, since they only read content.
5. When you add guru___guru_answer_generation, also set:

6. Save, then Publish the agent.

❗️

The agentId override is required

Guru's answer tool fails with "Required argument 'agentId' is missing or blank" when no Knowledge Agent is specified, and the AI agent doesn't reliably supply one on its own. Without the override, the Connect assistant tells reps it can't generate an answer.

You can add more overrides on the same tool. Setting collectionIds limits answers to specific Guru collections, which helps keep internal-only content out of customer conversations even if the Knowledge Agent covers more.

Step 12: Make it the default agent assist AI agent

Where: Connect admin website, then AI agent designer, then AI agents, then the Default AI Agent Configurations section.

Find the Agent Assistance row, choose the edit icon, and select Guru-Agent-Assist.

Step 13: Attach the AI agent in your contact flow

AI agents only run on contacts that pass through a flow with a Connect assistant block. Add two blocks to the chat flow your customers use, before the contact goes to a queue. If you're testing first, create a new flow with the blocks below and route a test chat through it.

Where: Connect admin website, then Routing, then Flows. Open your existing chat flow, or choose Create flow.

1. Set recording, analytics, and processing behavior. Set the action to Set recording and analytics behavior and the channel to Chat. Under Enable conversational analytics, check Enable conversational analytics. Under Configure conversational analytics, set Analytics Language to your language. Redaction, sentiment, and summaries are optional. This gives the AI agent the live conversation to work from.
2. Connect assistant. Under Select a domain, keep Set manually with the preselected domain. Under AI Agent - Agent Assistance, choose Select AI Agent, select Guru-Agent-Assist, and select the version you just published.
3. Connect Connect assistant's Success branch to the rest of your flow (for a new flow, Set working queue, then Transfer to queue).
4. Connect Connect assistant's Error branch to Set working queue as well, so customers still reach a rep if the AI agent fails to load.
5. Connect every remaining error branch to Disconnect, then Publish the flow.

When you change the AI agent later, publish a new version of it, then update the version in this block and publish the flow again.

Step 14: Test the integration

Where: Your Connect admin website's test chat page, at your access URL followed by /test-chat, for example https://example-corp.my.connect.aws/test-chat.

1. In another tab, open Workspaces, then Agent Workspace, and set your status to Available. Your user needs a routing profile that includes the queue your flow uses, with chat enabled.
2. On the test chat page, choose Test Settings, select your flow, leave Alias / Version empty, and choose Apply.
3. Choose the chat icon on the simulated website and send a customer message.
4. In the Agent Workspace, accept the chat. Don't use Activate the Contact Control Panel on the test chat page; that panel doesn't include the Connect assistant.
5. In the Connect assistant panel, ask a question your Knowledge Agent can answer.

The assistant posts a short "checking" note, then an answer drawn from your Guru content. In Guru, open the AI Agent Center to see the same question logged with its answer and source cards.

📘

Test during a contact

The Connect assistant's question box also works when no contact is open, but those questions go to Amazon Connect's built-in Manual Search agent, not to Guru. They return "Sorry, I am unable to assist you with this request" with a Related articles link. Always test with an active chat routed through your flow.

Troubleshooting

The gateway's logs show exactly where a failing request stops. Turn them on before you troubleshoot an AI agent that can't reach Guru.

Turn on logs. AWS console, then Amazon Bedrock AgentCore, then Gateways, then guru-connect-gateway, then Log deliveries and tracing. On the Gateway tab, choose Add, select Amazon CloudWatch Logs, keep APPLICATION_LOGS and the default log group, set the output format to JSON, and choose Add.

Read the logs. Ask a question in a test chat and wait a minute. Then open CloudWatch, then Log groups, and open the group ending in your gateway ID (it starts with /aws/vendedlogs/bedrock-agentcore/gateway/). Open the newest log stream and search for error.

aws logs tail /aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/YOUR_GATEWAY_ID \
  --since 10m | grep -i error

Maintain the integration