Connectivity

Neptune endpoint types

Default port: 8182 (Neptune Database), 443 (Neptune Analytics via SDK)

Option 1: Connect from AWS CloudShell (no EC2 required)

CloudShell VPC environments let you connect directly without a bastion host.

Step 1 — Create a VPC CloudShell environment

1. Open CloudShell in the AWS Console
2. Choose Actions → Create VPC Environment
3. Select the VPC, subnet, and security group that has inbound access on port 8182 to your Neptune cluster
4. Choose Create — CloudShell restarts inside your private subnet

Step 2 — Install the Neptune client

Step 3 — Connect to Neptune

Create conf/neptune-remote.yaml:

⚠️ CloudShell sessions time out after 30 minutes of inactivity. Reinstall the client after a timeout.

Option 2: Connect from Lambda

Neptune runs in a VPC. Your Lambda function must also be in the same VPC.

Lambda VPC configuration

Important: Neptune requires SSL/TLS (TLS 1.2+) for ALL connections. IAM authentication with SigV4 signing automatically uses encrypted connections. There is no option to connect over unencrypted protocols.

Python Lambda handler (Gremlin)

Production default — IAM auth: This basic handler shows the raw Gremlin connection and assumes IAM database authentication is disabled (dev/test only). For production, enable IAM auth on the cluster and SigV4-sign every request — see the “IAM authentication (recommended for production)” section below, which is the pattern to copy. An unauthenticated connection only works when IAM auth is disabled, which is not recommended for production.

Lambda security group rules

⚠️ Reference security groups by ID, not CIDR range. This is the most common misconfiguration.

Option 3: Connect from EC2

EC2 gives persistent client installations unlike CloudShell.

EC2 requirements:

• Same VPC as Neptune (or VPC peering)
• Security group with outbound TCP 8182 to Neptune
• Neptune security group with inbound TCP 8182 from EC2 security group

IAM authentication (recommended for production)

Neptune supports IAM database authentication. When enabled, connections require a Signature Version 4 signed request.

Credentials: use ephemeral credentials, never long-lived IAM user access keys. Prefer IAM roles — for Lambda, attach the execution role with Neptune access; for local development, use aws sso login or aws sts assume-role. The helper below resolves whatever credentials the environment provides via boto3.Session(), so it works with role/STS credentials automatically.

Enable IAM auth on the cluster:

After enabling IAM auth, also enable CloudWatch Logs for auditing:

This logs all authentication and query execution events for monitoring.

Option 4: Connect to Neptune Analytics

Neptune Analytics uses a different SDK and connection model than Neptune Database. It does NOT use WebSocket or port 8182. Instead, use the boto3 neptune-graph client.

Endpoint format

Example: g-abc123def4.us-east-1.neptune-graph.amazonaws.com

Connection via boto3 SDK (recommended)

Public vs private connectivity

• Private (default): Graph is only accessible from within the VPC via a private endpoint. Requires VPC endpoint or same-VPC access.
• Public: Graph is accessible over the internet. Enable at creation or update later. All requests must be signed with SigV4 (IAM auth is mandatory).

Equivalent AWS CLI invocation:

Key differences from Neptune Database

Option 5: Neptune Notebooks (interactive exploration)

For data science, exploration, and visualization, use Neptune Notebooks via Amazon SageMaker or the local graph-notebook package.

SageMaker Neptune Notebook

1. In the Neptune console, choose Notebooks → Create notebook
2. Select your Neptune cluster
3. The notebook auto-configures VPC connectivity and installs graph-notebook
4. Use %%gremlin or %%opencypher magic commands to query directly

Local graph-notebook

In Jupyter:

Neptune Notebooks provide built-in graph visualization — useful for exploring graph structure, debugging traversals, and presenting results.

Option 6: Neptune MCP Servers (agent integration)

Neptune provides two MCP (Model Context Protocol) servers that give AI agents direct access to Neptune without managing connections manually:

• Neptune MCP Query Server — agents run openCypher and Gremlin queries against Neptune Database and Neptune Analytics, and fetch graph schema. No WebSocket or SDK setup required from the agent side.
• Neptune MCP Memory Server — agents store and retrieve knowledge graphs against Neptune for persistent memory across sessions.

These are useful when the “client” connecting to Neptune is an AI agent framework (e.g., Strands AI Agents SDK or other MCP-compatible tools) rather than application code. The MCP servers handle connection management, authentication, and query execution internally.

When to use MCP servers vs. direct connection:

• Use MCP servers when an AI agent needs to query or write to Neptune as part of its workflow
• Use direct connection (Options 1–5 above) when application code connects to Neptune

Troubleshooting connectivity

See troubleshooting.md for the full list. Most common:

Common Mistakes

1. Using CIDR instead of security group ID — always reference SGs by ID.
2. Wrong protocol — use wss:// for Gremlin WebSocket, https:// for HTTP.
3. Forgetting VPC for Lambda — Lambda must be in same VPC as Neptune Database.
4. Using Gremlin client for Neptune Analytics — Analytics uses boto3 SDK, not WebSocket.
5. Not enabling IAM auth with public endpoints — public endpoints require IAM.

Additional Resources

• AWS docs: “Connecting to Neptune”, “Neptune public endpoints”, “Neptune Analytics connecting”
• Related sub-skills: troubleshooting (connection errors), analytics-vs-database (which SDK)
• Tool: graph-notebook (pip install graph-notebook) for Jupyter exploration

Security considerations

• VPC isolation: Neptune Database is VPC-only by design. A misconfigured VPC, route table, or security group can either break connectivity or, if over-permissive, widen exposure. Restrict inbound to the specific client security groups that need access; do not open 0.0.0.0/0.
• Audit logging: Enable AWS CloudTrail for Neptune control-plane API calls, and enable Neptune audit logs (--enable-cloudwatch-logs-exports '["audit"]') so connection and query activity is recorded.
• IAM auth in production: Use IAM auth (SigV4-signed requests) for all production connections. It is mandatory for Neptune Analytics and for public Neptune Database endpoints; enable it on private Database clusters as well.
• No unauthenticated public exposure: Never enable a public Neptune endpoint without IAM auth. Public endpoints expose the service to the internet, so authentication and tightly-scoped security groups are required, not optional.