Connecting to privately hosted tools

Private connections overview

AWS DevOps Agent can be extended with custom Model Context Protocol (MCP) tools and other integrations that give the agent access to internal systems such as private package registries, self-hosted observability platforms, internal documentation APIs, and source control instances (see: Configuring capabilities for AWS DevOps Agent). These services often run inside an Amazon Virtual Private Cloud (Amazon VPC) with restricted or no public internet access, which means AWS DevOps Agent can't reach them by default.

Private connections for AWS DevOps Agent let you securely connect your Agent Space to services running in your VPC without exposing them to the public internet. Private connections work with any integration that needs to reach a private endpoint, including MCP servers, self-hosted Grafana or Splunk instances, and source control systems like GitHub Enterprise Server and GitLab Self-Managed.

How private connections work

A private connection creates a secure network path between AWS DevOps Agent and a target resource in your VPC. Under the hood, AWS DevOps Agent uses Amazon VPC Lattice to establish this secure private connectivity path. VPC Lattice is an application networking service that lets you connect, secure, and monitor communication between applications across VPCs, accounts, and compute types, without managing the underlying network infrastructure.

When you create a private connection, the following occurs:

The resource gateway is fully managed by AWS DevOps Agent and appears as a read-only resource in your account (named aidevops-{your-private-connection-name}). You don't need to configure or maintain it. The only resources created in your VPC are ENIs in the subnets you specify. These ENIs serve as the entry point for private traffic and are managed entirely by the service. They don't accept inbound connections from the internet, and you retain full control over their traffic through your own security groups.

Security

Private connections are designed with multiple layers of security:

Architecture

The following diagram shows the network path for a private connection.

In this architecture:

Create a private connection

You can create a private connection using the AWS Management Console or the AWS CLI.

Prerequisites

Before creating a private connection, verify that you have the following:

Private connections are account-level resources. After you create a private connection, you can reuse it across multiple integrations and Agent Spaces that need to reach the same host.

Create a private connection using the console

The connection status changes to Create in progress. This process can take up to 10 minutes. When the status changes to Active, the network path is ready.

If the status changes to Create failed, verify the following:

Create a private connection using the AWS CLI

Run the following command to create a private connection. Replace the placeholder values with your own.

aws devops-agent create-private-connection \
    --name my-mcp-tool-connection \
    --mode '{
        "serviceManaged": {
            "hostAddress": "mcp.internal.example.com",
            "vpcId": "vpc-0123456789abcdef0",
            "subnetIds": [
                "subnet-0123456789abcdef0",
                "subnet-0123456789abcdef1"
            ],
            "securityGroupIds": [
                "sg-0123456789abcdef0"
            ],
            "portRanges": ["443"]
        }
    }'

The response includes the connection name and a status of CREATE_IN_PROGRESS:

{
    "name": "my-mcp-tool-connection",
    "status": "CREATE_IN_PROGRESS",
    "resourceGatewayId": "rgw-0123456789abcdef0",
    "hostAddress": "mcp.internal.example.com",
    "vpcId": "vpc-0123456789abcdef0"
}

To check the connection status, use the describe-private-connection command:

aws devops-agent describe-private-connection \
    --name my-mcp-tool-connection

When the status is ACTIVE, your private connection is ready to use.

Use a private connection with a capability provider

To use a private connection, you can link to it during the registration of a capability provider. Supported capabilities that can be used with private connections include: GitHub, GitLab, MCP Server, and Grafana. You can perform this step using the AWS Management Console or the AWS CLI.

Use a private connection with a capability provider using the console

In the AWS DevOps Agent console, private connections can be linked to a capability during registration by selecting the "Connect to endpoint using a private connection" option.

Use a private connection with a capability provider using the AWS CLI

You can register capabilities with a private connection by including the private-connection-name argument. Below is an example of registering an MCP Server with API Key authorization using the my-mcp-tool-connection private connection. Replace the placeholder values with your own.

aws devops-agent register-service \
    --service mcpserver \
    --private-connection-name my-mcp-tool-connection \
    --service-details '{
        "mcpserver": {
            "name": "my-mcp-tool",
            "endpoint": "https://mcp.internal.example.com",
            "authorizationConfig": {
                "apiKey": {
                    "apiKeyName": "api-key",
                    "apiKeyValue": "secret-value",
                    "apiKeyHeader": "x-api-key"
                }
            }
        }
    }' \
    --region us-east-1

Verify a private connection

After the private connection reaches the Active state and has been utilized by a capability provider, verify that AWS DevOps Agent can reach your target service:

If the connection fails, check the following:

Delete a private connection

You can delete unused private connections using the AWS Management Console or the AWS CLI.

Delete a private connection using the console

The private connection will be displayed with a status of "Removing connection" while AWS DevOps Agent removes the managed resource gateway and ENIs from your VPC. After deletion completes, the connection no longer appears in your list of private connections.

Delete a private connection using the AWS CLI

aws devops-agent delete-private-connection \
    --name my-mcp-tool-connection

The response returns a status of DELETE_IN_PROGRESS. AWS DevOps Agent removes the managed resource gateway and ENIs from your VPC. After deletion completes, the connection no longer appears in your list of private connections.

Advanced setup using existing VPC Lattice resources

If your organization already uses Amazon VPC Lattice and manages your own resource configurations, you can create a private connection in self-managed mode. Instead of having AWS DevOps Agent create a resource gateway for you, you provide the Amazon Resource Name (ARN) of an existing resource configuration that points to your target service.

This approach is useful when you:

To create a self-managed private connection with the AWS CLI:

aws devops-agent create-private-connection \
    --name my-advanced-connection \
    --mode '{
        "selfManaged": {
            "resourceConfigurationId": "arn:aws:vpc-lattice:us-east-1:123456789012:resourceconfiguration/rcfg-0123456789abcdef0"
        }
    }'

For more details on setting up VPC Lattice resource gateways and resource configurations, see the Amazon VPC Lattice User Guide.

Related topics