ECS Service Connect for MCP Servers

Creating the Cloud Map namespace

Service Connect requires an HTTP Cloud Map namespace. You create it once per environment and reference it from all services:

# Create the namespace (HTTP, not DNS — Service Connect uses HTTP namespaces)
aws servicediscovery create-http-namespace \
  --name production \
  --description "MCP server services — production"

# Output: { "OperationId": "gv4g5meo7ndmeh4fqskygvk23d2fijwa-k9302yzd" }
# Wait for it to complete:
aws servicediscovery get-operation --operation-id gv4g5meo7ndmeh4fqskygvk23d2fijwa-k9302yzd

Associate the namespace with your ECS cluster so it becomes the default for all services in that cluster:

aws ecs put-cluster-capacity-providers \
  --cluster my-cluster \
  --capacity-providers FARGATE FARGATE_SPOT \
  --default-capacity-provider-strategy capacityProvider=FARGATE,weight=1 \
  --configuration '{
    "executeCommandConfiguration": {},
    "managedStorageConfiguration": {},
    "containerInsights": "enabled"
  }'

# Set the default Service Connect namespace on the cluster
aws ecs update-cluster \
  --cluster my-cluster \
  --service-connect-defaults namespace=production

In CDK:

import * as servicediscovery from 'aws-cdk-lib/aws-servicediscovery';
import * as ecs from 'aws-cdk-lib/aws-ecs';

const namespace = new servicediscovery.HttpNamespace(this, 'Namespace', {
  name: 'production',
});

const cluster = new ecs.Cluster(this, 'Cluster', {
  vpc,
  defaultCloudMapNamespace: { name: 'production', type: servicediscovery.NamespaceType.HTTP },
});

Client mode vs client-server mode

Client mode configuration

aws ecs create-service \
  --cluster my-cluster \
  --service-name mcp-server-svc \
  --task-definition mcp-server:3 \
  --desired-count 2 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-abc],securityGroups=[sg-abc],assignPublicIp=DISABLED}" \
  --service-connect-configuration '{
    "enabled": true,
    "namespace": "production"
  }'

With client mode, the MCP server container can reach http://mcp-auth.production directly — no DNS configuration needed. Calls are routed through the local proxy sidecar on each task.

Client-server mode configuration

aws ecs create-service \
  --cluster my-cluster \
  --service-name mcp-auth-svc \
  --task-definition mcp-auth:2 \
  --desired-count 2 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-abc],securityGroups=[sg-abc],assignPublicIp=DISABLED}" \
  --service-connect-configuration '{
    "enabled": true,
    "namespace": "production",
    "services": [{
      "portName": "http",
      "clientAliases": [{
        "port": 80,
        "dnsName": "mcp-auth"
      }]
    }]
  }'

The portName must match a port mapping name in the task definition. Add names to port mappings in the task definition:

{
  "containerDefinitions": [{
    "name": "mcp-auth",
    "portMappings": [{
      "name": "http",
      "containerPort": 3000,
      "protocol": "tcp",
      "appProtocol": "http"
    }]
  }]
}

The appProtocol field enables HTTP/2 optimizations in the proxy and is required for the detailed per-request metrics to appear in CloudWatch.

Security group rules for Service Connect

The proxy sidecar listens on an ephemeral port (32768–65535) for inbound connections. Tasks in client mode connect to the proxy on that port. If your tasks are in different security groups, the inbound rule must allow the full ephemeral range:

# Allow Service Connect proxy traffic between tasks
aws ec2 authorize-security-group-ingress \
  --group-id sg-mcp-auth \
  --protocol tcp \
  --port 32768-65535 \
  --source-group sg-mcp-server

Within the same security group, self-referential rules cover this automatically. If you separate services into different security groups, the ephemeral port range rule is mandatory — without it, the proxy connection attempt silently times out and calls fail after the connection timeout (default 10s).

Service Connect metrics in CloudWatch

The proxy sidecar automatically emits metrics to CloudWatch under the AWS/ECS/ManagedScaling and custom ECS/ContainerInsights/ServiceConnect namespaces. No instrumentation code required:

Metrics are dimensioned by DiscoveryName (the service DNS name), ServiceName, and ClusterName — you can build a per-service-to-service connection dashboard without any custom instrumentation.

Common failures