VPC Connections

Connect MCP servers to your private infrastructure via AWS PrivateLink.

Overview

VPC Connections establish secure connectivity between CorpAI’s EKS cluster (where MCP pods run) and private services in your existing VPC (e.g., ClickHouse, GitHub Enterprise, or other internal services).

You do not need to create a new VPC. This guide shows you how to expose an existing service in your VPC via AWS PrivateLink so CorpAI can connect to it securely.

Architecture

After CorpAI onboarding, you have two VPCs in your AWS account:

VPC Connections link these two VPCs via AWS PrivateLink:

Customer VPC components (you create):

CorpAI VPC components (auto-provisioned):

Availability Zone requirement

Your NLB must be deployed in at least one Availability Zone that overlaps with the CorpAI-provisioned VPC’s private subnets.

To find CorpAI’s AZs: VPC Console → Subnets → filter by tag ManagedBy=corpai-terraform

Prerequisites

Before starting, ensure you have:

• An existing VPC with your service running (e.g., ClickHouse on EC2)
• The VPC ID of that existing VPC (find it in VPC Console )
• At least 2 private subnets in different Availability Zones (required for NLB)
• Your service’s port number (e.g., 8443 for ClickHouse HTTPS, 9440 for native TLS)
• Your VPC CIDR block (find it in VPC Console → Your VPCs → IPv4 CIDR column)

Tag all resources with corpai: privatelink for easy identification.

1. Create IAM Policy

Add this policy to your corpai-cross-account-access role:

1. Go to AWS IAM Console  → Policies → Create policy
2. Select JSON editor and paste the policy below
3. Name it CorpAIPrivateServiceConnectivity
4. Go to your corpai-cross-account-access role → Add permissions → Attach policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DescribeResources",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeVpcEndpoints",
        "ec2:DescribeVpcEndpointServices"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CreateVpcEndpoint",
      "Effect": "Allow",
      "Action": "ec2:CreateVpcEndpoint",
      "Resource": [
        "arn:aws:ec2:*:*:vpc-endpoint/*",
        "arn:aws:ec2:*:*:vpc/*",
        "arn:aws:ec2:*:*:subnet/*",
        "arn:aws:ec2:*:*:security-group/*"
      ]
    },
    {
      "Sid": "DeleteCorpAIManagedEndpoints",
      "Effect": "Allow",
      "Action": "ec2:DeleteVpcEndpoints",
      "Resource": "arn:aws:ec2:*:*:vpc-endpoint/*",
      "Condition": {
        "StringEquals": {
          "ec2:ResourceTag/ManagedBy": "corpai"
        }
      }
    },
    {
      "Sid": "CreateSecurityGroup",
      "Effect": "Allow",
      "Action": "ec2:CreateSecurityGroup",
      "Resource": [
        "arn:aws:ec2:*:*:security-group/*",
        "arn:aws:ec2:*:*:vpc/*"
      ]
    },
    {
      "Sid": "ManageCorpAIManagedSecurityGroups",
      "Effect": "Allow",
      "Action": [
        "ec2:DeleteSecurityGroup",
        "ec2:AuthorizeSecurityGroupIngress"
      ],
      "Resource": "arn:aws:ec2:*:*:security-group/*",
      "Condition": {
        "StringEquals": {
          "ec2:ResourceTag/ManagedBy": "corpai"
        }
      }
    },
    {
      "Sid": "TagNewResources",
      "Effect": "Allow",
      "Action": "ec2:CreateTags",
      "Resource": [
        "arn:aws:ec2:*:*:vpc-endpoint/*",
        "arn:aws:ec2:*:*:security-group/*"
      ],
      "Condition": {
        "StringEquals": {
          "ec2:CreateAction": ["CreateVpcEndpoint", "CreateSecurityGroup"]
        }
      }
    }
  ]
}

Security notes:

• Delete/modify actions are restricted to resources tagged ManagedBy: corpai
• Your existing security groups and VPC endpoints cannot be modified

2. Create NLB and Endpoint Service

Create these resources in your existing VPC (where your service runs), in the same AWS region as your CorpAI deployment.

Important: Do NOT create these in the CorpAI-provisioned VPC. You’ll select your existing VPC (the one containing your ClickHouse EC2 or other service) in each step below.

Step 1: Create a Security Group

1. Go to EC2 → Security Groups 
2. Click “Create security group”
3. Name: corpai-[service]-nlb-sg, replace [service] with the name of your service (e.g., corpai-clickhouse-nlb-sg)
4. Description: Security group for [service] NLB PrivateLink
5. VPC: Select YOUR EXISTING VPC (the one where your service runs, NOT the CorpAI-provisioned VPC)
   • Look for the VPC containing your EC2 instance
   • Do NOT select the VPC tagged ManagedBy=corpai-terraform
6. Inbound rule: Custom TCP, Port = your service port, Source = your VPC CIDR
7. Outbound rule: Delete the default “All traffic” rule, then add Custom TCP, Port = your service port, Destination = your service’s security group
8. Add tag: Key = corpai, Value = privatelink
9. Click “Create security group”

Step 2: Create a Target Group

1. Go to EC2 → Target Groups 
2. Click “Create target group”
3. Target type: Instances (or IP addresses if your service uses container networking)
4. Name: corpai-[service]-tg (e.g., corpai-clickhouse-tg)
5. Protocol: TCP
6. Port: Your service port (e.g., 8443 for ClickHouse HTTPS)
7. VPC: Select YOUR EXISTING VPC (same VPC as Step 1)
8. Health check: TCP for basic port check, or HTTP with your service’s health endpoint
9. Add tag: Key = corpai, Value = privatelink
10. Click “Next”, then register your targets:
    • Select your EC2 instance(s) running the service
    • Enter the port your service listens on
    • Click “Include as pending below”
    • Verify it appears in the targets table
11. Click “Create target group”

Step 3: Create a Network Load Balancer

1. Go to EC2 → Load Balancers 
2. Click “Create load balancer” → Network Load Balancer
3. Name: corpai-[service]-nlb (e.g., corpai-clickhouse-nlb)
4. Scheme: Internal (important - do NOT use internet-facing)
5. VPC: Select YOUR EXISTING VPC (same VPC as previous steps)
6. Mappings: Select private subnets in your existing VPC
   • Must select at least 2 subnets in different Availability Zones
   • These should be the subnets where your service can be reached
7. Security groups: Select the security group from Step 1
8. Listeners: Add TCP : [your port] → forward to your target group
9. Add tag: Key = corpai, Value = privatelink
10. Click “Create load balancer”
11. Wait for state to become Active (~2 minutes)
12. Select your NLB → Attributes tab → Edit → Enable Cross-zone load balancing

Note: If you modify target group settings after creation, deregister and re-register your targets to ensure changes take effect.

Step 4: Create a VPC Endpoint Service

1. Go to VPC → Endpoint Services 
2. Click “Create endpoint service”
3. Name: corpai-[service]-endpoint-svc, replace [service] with the name of your service
4. Load balancer type: Network
5. Select your NLB from the dropdown
6. Supported Regions: Leave empty (same-region only)
7. Acceptance required: Uncheck for auto-accept, or leave checked to manually approve
8. Enable private DNS name: Leave unchecked
9. Supported IP address types: IPv4
10. Add tag: Key = corpai, Value = privatelink
11. Click “Create”
12. Copy the Service name (e.g., com.amazonaws.vpce.us-east-1.vpce-svc-abc123)

3. Register in CorpAI

1. Go to Settings → Infrastructure → VPC Connections
2. Click Add Connection
3. Enter the VPC Endpoint Service name you copied (e.g., com.amazonaws.vpce.us-east-1.vpce-svc-abc123)
4. Enter the port your service listens on
5. Add a display name (e.g., “ClickHouse Production”)
6. Click Create Connection

What happens behind the scenes:

When you register a connection, CorpAI automatically:

1. Creates a VPC Endpoint in the CorpAI-provisioned VPC (the one with EKS)
2. Creates a security group allowing traffic on your specified port
3. Connects to your VPC Endpoint Service via AWS PrivateLink

The connection status will show as pending_acceptance until you accept it in AWS (next step).

4. Accept the Connection

If you enabled “Acceptance required” on your Endpoint Service:

1. Go to VPC → Endpoint Services 
2. Select your endpoint service → Endpoint Connections tab
3. You should see a pending connection from CorpAI’s VPC
4. Select the pending connection → Actions → Accept endpoint connection request
5. Return to CorpAI and click Refresh to update status

The connection status should change from pending_acceptance to available.

5. Use the Endpoint DNS

Once the connection shows Available, copy the endpoint DNS and use it as the host when configuring service credentials:

1. Go to Settings → Service Credentials
2. Add credentials for your service (e.g., ClickHouse)
3. Use the endpoint DNS as the host value (not your EC2’s private IP)
   • The endpoint DNS looks like: vpce-0abc123def456.vpce-svc-xyz789.us-east-1.vpce.amazonaws.com

Note: Initial PrivateLink requests may take 10-15 seconds while the connection warms up.

Next

Management →