AWS AgentCore + Neo4j Integration

Overview

AWS AgentCore is Amazon’s framework-agnostic agent runtime and orchestration platform. It provides managed runtimes, gateway capabilities, episodic memory, and comprehensive observability for production agent deployments.

Key Features:

  • Framework-agnostic runtime (supports any Python/JavaScript framework)

  • Native MCP + A2A Protocol support

  • Multiple deployment models: Docker images, code-based (S3), and gateway proxying

  • IAM and OAuth 2.0 authentication

  • Comprehensive AWS CDK infrastructure-as-code support

Official Resources:

Samples

This directory contains three end-to-end samples, each demonstrating a different integration pattern between AWS AgentCore and Neo4j via the Neo4j MCP server. All samples are deployed with AWS CDK and use the public Neo4j companies demo database: neo4j+s://demo.neo4jlabs.com:7687 by default.

# Sample Pattern Auth Model Deployment

1

MCP Runtime - Docker

AgentCore Runtime with custom Docker image

IAM + per-request Neo4j credentials via custom header

ECR image built & pushed by CDK

2

Gateway - External MCP

AgentCore Gateway proxying to Fargate-hosted MCP

OAuth 2.0 → Lambda Interceptor → Basic Auth

ECS Fargate + ALB + custom domain

3

MCP Runtime - Neo4j Python SDK

AgentCore Runtime with code-based Python MCP server

IAM + Secrets Manager

Python bundle uploaded to S3 by CDK

Sample 1: MCP Runtime - Docker

Deploys the official Neo4j MCP Docker image as an AgentCore Runtime. The Docker image is extended locally, built and pushed to ECR by CDK, and run as a managed runtime. Neo4j credentials are passed per-request via the X-Amzn-Bedrock-AgentCore-Runtime-Custom-Authorization header.

→ Full documentation

Sample 2: Gateway - External MCP

Uses the AgentCore Gateway as a reverse proxy in front of an official Neo4j MCP server running on ECS Fargate behind a public ALB with a custom domain and TLS. A Lambda Request Interceptor translates inbound OAuth tokens into Neo4j Basic Auth credentials retrieved from Secrets Manager.

→ Full documentation

Sample 3: MCP Runtime - Neo4j Python SDK

Deploys a custom MCP server written in Python (FastMCP + Neo4j Python driver) as a code-based AgentCore Runtime. The Python source is bundled with dependencies via uv, uploaded to S3, and run directly - no Docker image needed. Neo4j credentials are loaded from Secrets Manager at startup.

→ Full documentation

Prerequisites

All samples require:

  • AWS Account with Bedrock and AgentCore access

  • AWS CLI configured with appropriate credentials

  • AWS CDK installed (npm install -g aws-cdk)

  • Python 3.9+

Sample 2 additionally requires a Route53 hosted zone and an ACM certificate for the custom domain.

Resources