Amazon Bedrock Knowledge Base Retrieval MCP Server

MCP server for accessing Amazon Bedrock Knowledge Bases

Features

Discover knowledge bases and their data sources

• Find and explore all available knowledge bases
• Search for knowledge bases by name or tag
• List data sources associated with each knowledge base

Query knowledge bases with natural language

• Retrieve information using conversational queries
• Get relevant passages from your knowledge bases
• Access citation information for all results

Filter results by data source

• Focus your queries on specific data sources
• Include or exclude specific data sources
• Prioritize results from specific data sources

Agentic retrieval on managed knowledge bases

• Plan a multi-step retrieval strategy and synthesise a cited answer
• Search several knowledge bases in one call
• Optional condensed trace of the agent's planning and retrieval steps
• Managed knowledge bases only; the tool rejects other types with a clear message

Reach ACL-protected content

• Pass user_id to retrieve content from ACL-aware data sources (SharePoint, OneDrive, Confluence with per-document ACLs)
• Without it, that content is inaccessible, and agentic retrieval's full-document expansion step fails with "UserContext is required for ACL-aware data sources"
• Results are filtered to what that user is authorised to see

Support both managed and vector knowledge bases

• Works with vector knowledge bases (type: VECTOR) and managed knowledge bases (type: MANAGED)
• The knowledge base type is detected automatically and the correct Retrieve configuration is sent (vectorSearchConfiguration or managedSearchConfiguration)
• Data-source filtering uses the metadata key appropriate to the knowledge base type
• The ListKnowledgeBases tool reports each knowledge base's type

Rerank results

• Improve relevance of retrieval results
• Use Amazon Bedrock reranking capabilities
• Sort results by relevance to your query

Prerequisites

Installation Requirements

1. Install uv from Astral or the GitHub README
2. Install Python using uv python install 3.10

AWS Requirements

1. AWS CLI Configuration: You must have the AWS CLI configured with credentials and an AWS_PROFILE that has access to Amazon Bedrock and Knowledge Bases
2. Amazon Bedrock Knowledge Base: You must have at least one Amazon Bedrock Knowledge Base with the tag key mcp-multirag-kb with a value of true
3. IAM Permissions: Your IAM role/user must have appropriate permissions to:
   • List and describe knowledge bases
   • Access data sources
   • Query knowledge bases

Reranking Requirements

If you intend to use reranking functionality, your Bedrock Knowledge Base needs additional permissions:

1. Your IAM role must have permissions for both bedrock:Rerank and bedrock:InvokeModel actions
2. The Amazon Bedrock Knowledge Bases service role must also have these permissions
3. Reranking availability differs per model: amazon.rerank-v1:0 is not offered in us-east-1, while cohere.rerank-v3-5:0 is. The server validates the (region, model) pair and fails fast with a clear message. Please refer to the official documentation for an up to date list of supported regions.
4. Enable model access for the available reranking models in the specified region.

Agentic Retrieval Requirements

The AgenticQueryKnowledgeBases tool calls AgenticRetrieveStream, which is supported for managed knowledge bases only (type: MANAGED). It plans a retrieval strategy and, unless you pass generate_response=false, invokes a foundation model to write a cited answer.

1. Your IAM role needs bedrock:AgenticRetrieveStream on the knowledge base, in addition to the permissions listed above
2. Because it invokes a foundation model, it costs materially more per call than QueryKnowledgeBases. Pass generate_response=false for retrieval without synthesis
3. RetrieveAndGenerate is not supported for managed knowledge bases, so agentic retrieval with generate_response=true is the way to get a generated answer from one

Controlling Reranking

Reranking can be globally enabled or disabled using the BEDROCK_KB_RERANKING_ENABLED environment variable:

• Set to false (default): Disables reranking for all queries unless explicitly enabled
• Set to true: Enables reranking for all queries unless explicitly disabled

The environment variable accepts various formats:

• For enabling: 'true', '1', 'yes', or 'on' (case-insensitive)
• For disabling: any other value or not set (default behavior)

This setting provides a global default, while individual API calls can still override it by explicitly setting the reranking parameter.

For detailed instructions on setting up knowledge bases, see:

• Create a knowledge base
• Managing permissions for Amazon Bedrock knowledge bases
• Permissions for reranking in Amazon Bedrock

Installation

Kiro	Cursor	VS Code

Configure the MCP server in your MCP client configuration (e.g., for Kiro, edit ~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "awslabs.bedrock-kb-retrieval-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.bedrock-kb-retrieval-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "your-profile-name",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR",
        "KB_INCLUSION_TAG_KEY": "optional-tag-key-to-filter-kbs",
        "BEDROCK_KB_RERANKING_ENABLED": "false"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Windows Installation

For Windows users, the MCP server configuration format is slightly different:

{
  "mcpServers": {
    "awslabs.bedrock-kb-retrieval-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "awslabs.bedrock-kb-retrieval-mcp-server@latest",
        "awslabs.bedrock-kb-retrieval-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

or docker after a successful docker build -t awslabs/bedrock-kb-retrieval-mcp-server .:

# fictitious `.env` file with AWS temporary credentials
AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk

  {
    "mcpServers": {
      "awslabs.bedrock-kb-retrieval-mcp-server": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "--interactive",
          "--env",
          "FASTMCP_LOG_LEVEL=ERROR",
          "--env",
          "KB_INCLUSION_TAG_KEY=optional-tag-key-to-filter-kbs",
          "--env",
          "BEDROCK_KB_RERANKING_ENABLED=false",
          "--env",
          "AWS_REGION=us-east-1",
          "--env-file",
          "/full/path/to/file/above/.env",
          "awslabs/bedrock-kb-retrieval-mcp-server:latest"
        ],
        "env": {},
        "disabled": false,
        "autoApprove": []
      }
    }
  }

NOTE: Your credentials will need to be kept refreshed from your host

Limitations

• Results with IMAGE content type are not included in the KB query response.
• The reranking parameter requires additional permissions, Amazon Bedrock model access, and is only available in specific regions.