AWS AgentCore — MCP 运行时 (Docker)

简介

此示例演示了如何部署带有 Neo4j MCP Docker 镜像的 AWS AgentCore 运行时。Neo4j MCP 服务器配置为 HTTP 传输，并通过 CDK 部署为 AgentCore 运行时。

您可以选择使用 AWS Marketplace 中的预构建镜像进行快速部署，或者从随附的 docker/Dockerfile 在本地构建 Docker 镜像。

核心功能

  • 预构建或本地 Docker 镜像：使用 AWS Marketplace 中的预构建 Neo4j MCP Docker 镜像，或从 docker/Dockerfile 在本地构建

  • IAM 身份验证：使用 AWS IAM 权限实现安全、公共的运行时访问

  • 基于标头的身份验证：Neo4j 凭据通过自定义的 X-Amzn-Bedrock-AgentCore-Runtime-Custom-Authorization 标头安全提供

  • 无服务器部署：完全托管的 AgentCore 运行时

  • CDK 基础设施：完整的“基础设施即代码”部署 — 无需手动进行 CLI 配置

先决条件

  • 具备 Bedrock 和 AgentCore 访问权限的 AWS 账户

  • 配置了适当凭据的 AWS CLI

  • 已安装 AWS CDK (npm install -g aws-cdk)

  • 已安装 uv (curl -LsSf https://astral.org.cn/uv/install.sh | sh)

  • 已安装并运行 Docker

第 1 节：从 AWS Marketplace 部署（推荐）

部署的最快途径。使用来自 AWS Marketplace 的预构建 Neo4j MCP 容器镜像 — 无需本地 Docker 构建。

克隆并安装

git clone https://github.com/neo4j-labs/neo4j-agent-integrations.git
cd neo4j-agent-integrations/aws-agentcore/samples/1-mcp-runtime-docker
uv sync
cp .env.sample .env

获取容器镜像 URI

  1. 转到 AWS Marketplace 并搜索 "Neo4j MCP Server"

  2. 订阅该列表并按照说明获取容器镜像 URI

配置环境

在您的 .env 文件中将 NEO4J_MCP_CONTAINER_URI 设置为从 Marketplace 获取的镜像 URI

# .env
NEO4J_URI=neo4j+s://demo.neo4jlabs.com:7687
NEO4J_DATABASE=companies
NEO4J_MCP_CONTAINER_URI=<marketplace-container-image-uri>

部署

./deploy.sh

CDK 将直接引用预构建的镜像 — 无需本地 Docker 构建。

测试运行时

独立演示脚本

部署后，deploy.sh 会自动查询 CloudFormation 堆栈输出并将 AGENTCORE_RUNTIME_ARN 写入 .env，以便演示客户端无需手动复制粘贴即可连接。运行演示：

cd demo
uv sync
uv run python demo.py

这将列出 MCP 工具，调用 get-schema，并运行代理查询。使用 --mode 运行特定步骤

uv run python demo.py --mode list    # list tools only
uv run python demo.py --mode call    # call get-schema
uv run python demo.py --mode agent   # run agent query (requires Bedrock model access)

Jupyter Notebook

打开 demo.ipynb 并将 arn 变量设置为 CDK 输出中的 Neo4jMcpRuntimeArn，然后运行笔记本。它使用 mcp_proxy_for_aws 和 strands 通过 IAM 签名请求进行连接，并使用 X-Amzn-Bedrock-AgentCore-Runtime-Custom-Authorization 标头来传递 Neo4j 凭据。

arn = "<Neo4jMcpRuntimeArn from CDK output>"
neo4j_user = "companies"
neo4j_password = "companies"

清理

cdk destroy Neo4jMCPRuntimeStack

第 2 节：构建并部署本地 Docker 镜像

如果您想自定义容器或无法访问 Marketplace 镜像，则可以从随附的 docker/Dockerfile 在本地构建 Docker 镜像。

克隆并安装

git clone https://github.com/neo4j-labs/neo4j-agent-integrations.git
cd neo4j-agent-integrations/aws-agentcore/samples/1-mcp-runtime-docker
uv sync
cp .env.sample .env

配置环境

从您的 .env 中省略 NEO4J_MCP_CONTAINER_URI — CDK 将在本地构建镜像

# .env
NEO4J_URI=neo4j+s://demo.neo4jlabs.com:7687
NEO4J_DATABASE=companies

部署

./deploy.sh

CDK 将从 docker/Dockerfile 在本地构建 Docker 镜像，将其推送到 ECR，并将其部署为 AgentCore 运行时。

测试运行时

独立演示脚本

部署后，deploy.sh 会自动查询 CloudFormation 堆栈输出并将 AGENTCORE_RUNTIME_ARN 写入 .env，以便演示客户端无需手动复制粘贴即可连接。运行演示：

cd demo
uv sync
uv run python demo.py

这将列出 MCP 工具，调用 get-schema，并运行代理查询。使用 --mode 运行特定步骤

uv run python demo.py --mode list    # list tools only
uv run python demo.py --mode call    # call get-schema
uv run python demo.py --mode agent   # run agent query (requires Bedrock model access)

Jupyter Notebook

打开 demo.ipynb 并将 arn 变量设置为 CDK 输出中的 Neo4jMcpRuntimeArn，然后运行笔记本。它使用 mcp_proxy_for_aws 和 strands 通过 IAM 签名请求进行连接，并使用 X-Amzn-Bedrock-AgentCore-Runtime-Custom-Authorization 标头来传递 Neo4j 凭据。

arn = "<Neo4jMcpRuntimeArn from CDK output>"
neo4j_user = "companies"
neo4j_password = "companies"

清理

cdk destroy Neo4jMCPRuntimeStack

架构设计

Architecture Diagram

组件

  1. AWS AgentCore 运行时

    • 托管代理执行环境

    • 内置情节记忆 (episodic memory)

    • 与框架无关的编排

  2. Neo4j MCP Docker 镜像

    • 来自 ECR 的预构建 MCP 服务器，或从 docker/Dockerfile 本地构建

    • 部署在 AgentCore 运行时中

    • 提供查询 Neo4j 的 MCP 工具

  3. 自定义授权标头

    • X-Amzn-Bedrock-AgentCore-Runtime-Custom-Authorization 标头

    • 动态凭据注入

    • 单次请求身份验证

    • 安全标头传输

  4. IAM 角色

    • 使用 IAM 身份验证的公共运行时访问

    • 细粒度权限控制

    • 用于工作负载身份的服务关联角色

  5. Neo4j 数据库

    • 演示实例：neo4j+s://demo.neo4jlabs.com:7687

    • 包含组织、人员、位置信息的公司数据库

深度分析

Docker 镜像配置

该示例支持两种部署模式

  1. 预构建 ECR 镜像 — 将 NEO4J_MCP_CONTAINER_URI 设置为预构建镜像 URI。AgentCore 直接引用它。这种方式更快，且使用经过测试的、带版本号的镜像。

  2. 本地 Docker 构建 — 省略 NEO4J_MCP_CONTAINER_URI。CDK 从 docker/Dockerfile 构建镜像，将其推送到 ECR，并自动配置运行时。

工作原理

  1. CDK 堆栈会检查上下文中是否提供了 neo4j_mcp_container_uri

  2. 如果已设置，CfnRuntime 直接引用预构建的 ECR 镜像 URI

  3. 如果未设置，CDK 使用 DockerImageAsset 从 docker/Dockerfile 构建并推送到 ECR

  4. AgentCore 在部署时注入环境变量并运行容器

  5. MCP 协议通信通过 HTTP 自动配置

身份验证流程

User/Agent Request
    ↓
[AWS IAM Authentication + Neo4j-Credentials via X-Amzn-Bedrock-AgentCore-Runtime-Custom-Authorization header]
    ↓
AgentCore Runtime (Public)
    ↓
Neo4j MCP Server (Configured with URI/DB only)
    ↓
[Extract Basic Auth from X-Amzn-Bedrock-AgentCore-Runtime-Custom-Authorization header]
    ↓
Neo4j Database

安全层

  1. IAM 身份验证：控制谁可以调用运行时

  2. 公共运行时：可通过 IAM 访问，无需 VPC

  3. MCP-Auth：Neo4j 凭据在每次调用时通过 X-Amzn-Bedrock-AgentCore-Runtime-Custom-Authorization 标头安全传递

  4. TLS 加密：到 Neo4j 的安全连接 (neo4j+s://)

可用的 MCP 工具

有关可用工具，请参阅 Neo4j MCP 服务器官方文档

CDK 堆栈组件

CDK 部署创建了

  • IAM 角色：适用于具有 Bedrock、ECR、CloudWatch 日志、X-Ray 和工作负载身份权限的 AgentCore 运行时

  • AgentCore `CfnRuntime` — 使用 MCP 协议、公共网络模式、IAM 身份验证和自定义标头允许列表进行配置，使用预构建的 ECR 镜像或本地构建的 Docker 镜像

环境变量

.env 文件支持 deploy.sh 的以下变量

变量 必填 描述

NEO4J_URI

是

Neo4j 连接 URI (例如 neo4j+s://demo.neo4jlabs.com:7687)

NEO4J_DATABASE

是

Neo4j 数据库名称 (例如 companies)

NEO4J_MCP_CONTAINER_URI

否

来自 ECR 的预构建 MCP Docker 镜像 URI。如果未设置，CDK 会从 docker/Dockerfile 构建本地 Docker 镜像。

CDK 上下文的默认值也提供在 cdk.json 中。当使用 deploy.sh 时，.env 的值会覆盖 cdk.json 中的默认值。您也可以在部署时使用 -c 标志进行覆盖

cdk deploy Neo4jMCPRuntimeStack \
  -c neo4j_uri=neo4j+s://your-instance:7687 \
  -c neo4j_database=neo4j

MCP Docker 容器在部署时配置了以下环境变量

  • NEO4J_URI - 数据库连接 URI (必填)

  • NEO4J_DATABASE - 数据库名称 (可选，默认为 neo4j)

  • NEO4J_READ_ONLY - 设置为 true 可将 MCP 服务器限制为只读操作

  • NEO4J_LOG_FORMAT - 日志格式，例如 text 或 json

  • NEO4J_HTTP_AUTH_HEADER_NAME - 用于传递 Basic Auth 凭据的 HTTP 标头名称 (设置为 X-Amzn-Bedrock-AgentCore-Runtime-Custom-Authorization)

  • NEO4J_HTTP_ALLOW_UNAUTHENTICATED_PING - 设置为 true 可允许未经身份验证的健康检查 ping

身份验证

凭据 (NEO4J_USERNAME, NEO4J_PASSWORD) 不存储在容器中。相反，它们在每次调用 MCP 工具时通过 X-Amzn-Bedrock-AgentCore-Runtime-Custom-Authorization 标头以 Base64 编码的 Basic Auth 值 (Basic <base64(user:password)>) 动态提供。

参考资料

AWS 文档

Neo4j 资源

CDK 说明

IAM 信任策略：混淆代理保护

AgentCore 运行时的 IAM 执行角色在其信任策略中包含了 aws:SourceAccount 和 aws:SourceArn 条件。这些条件防止了 混淆代理问题，即 AWS 服务可能被诱导代表非预期的账户或资源行事。

如果没有这些条件，跨任何 AWS 账户的任何 AgentCore 服务都可能尝试担任该运行时的执行角色。通过将信任范围限制为您特定的账户和 AgentCore ARN，只有您账户内的运行时才能担任该角色。

这遵循了 AWS 针对 AgentCore 运行时执行角色推荐的信任策略。

Marketplace 容器的跨账户 ECR 访问

运行时角色的 ECR 拉取权限 (ecr:BatchGetImage, ecr:GetDownloadUrlForLayer) 使用 "*" 作为资源，而不是限制为部署账户。这是必要的，因为来自 AWS Marketplace 的预构建容器镜像（例如 Neo4j MCP 服务器）托管在单独的供应商 ECR 账户中。如果将资源限制为仅部署账户，则在使用 Marketplace 容器时，AgentCore 会因“验证 ECR URI 时访问被拒绝”错误而失败。

© . This site is unofficial and not affiliated with Neo4j, Inc.