Amazon EKS MCP Server Tool Configuration Reference - Amazon EKS
ExampleIAM permissionsEnvironment variablesArgumentsTools

Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

Amazon EKS MCP Server Tool Configuration Reference

This guide shows all the configurations available for the mcp-proxy-for-aws client-side tool that allows you to connect to the fully managed Amazon EKS MCP Server from your IDE.

Note

The Amazon EKS MCP Server is in preview release for Amazon EKS and is subject to change.

Example

{
  "mcpServers": {
    "eks-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://eks-mcp.us-west-2.api.aws/mcp",
        "--service",
        "eks-mcp",
        "--profile",
        "default",
        "--region",
        "us-east-1",
        "--read-only"
      ]
    }
  }
}

IAM permissions

The role used for connecting to the MCP server requires eks-mcp:InvokeMcp permissions for initialization and retrieving information about available tools. eks-mcp:CallReadOnlyTool is required for usage of read only tools and eks-mcp:CallPrivilegedTool is required for usage of full access (write) tools.

Environment variables

AWS_PROFILE (optional) AWS credentials profile name to use; can be overridden by the --profile command-line argument.

  • Example: export AWS_PROFILE=production

AWS_REGION (optional) AWS region for SigV4 signing; defaults to us-west-2 if not set.

  • Example: export AWS_REGION=us-east-1

Arguments

SigV4 MCP endpoint URL (required) The MCP endpoint URL to connect to.

--service (optional) AWS service name for SigV4 signing; auto-detected from the endpoint hostname if not provided.

  • Example: --service eks-mcp

--profile (optional) AWS credentials profile to use. Defaults to the AWS_PROFILE environment variable if not specified.

  • Example: --profile production

--region AWS region to use. Uses AWS_REGION environment variable if not set, defaults to us-east-1.

  • Example: --region us-west-2

--read-only (optional) Disable tools which may require write permissions (tools which DO NOT require write permissions are annotated with readOnlyHint=true). By default, all tools are enabled.

  • Example: --read-only

For more configuration options, see Configuration parameters.

Tools

The server exposes the following MCP tools.

Read only tools

This section describes the read-only tools available for the EKS MCP Server. Note that all read-only Kubernetes API operations can access both:

search_eks_documentation Search EKS documentation for up-to-date information and guidance. This tool provides access to the latest EKS documentation, including new features and recent enhancements that agents may not be aware of.

Parameters:

  • query (required): Your specific question or search query related to EKS documentation, features, or best practices.

  • limit (optional): Maximum number of documentation results to return (1-10). Default: 5.

search_eks_troubleshooting_guide Searches the EKS Troubleshoot Guide for troubleshooting information based on a query. It helps identify common problems and provides step-by-step solutions.

Parameters:

  • query (required): Your specific question or issue description related to EKS troubleshooting.

describe_eks_resource Retrieves detailed information about a specific EKS cluster resource including configuration, status, and metadata.

Parameters:

  • cluster_name (required): Name of the EKS cluster (required for cluster-scoped resources).

  • resource_type (required): The EKS resource type to describe. Valid values:

  • accessentry (requires cluster_name and resource_name as principalArn)

  • addon (requires cluster_name and resource_name as addon name)

  • cluster (requires cluster_name), nodegroup (requires cluster_name and resource_name as nodegroup name).

  • resource_name (optional): Name of the specific resource to describe (required for most resource types).

list_eks_resources Lists EKS resources of a specific type, returning a summary of all resources of the specified type that are accessible.

Parameters:

  • resource_type (required): The EKS resource type to list. Valid values:

  • accessentry (requires cluster_name)

  • addon (requires cluster_name)

  • cluster (no additional parameters required)

  • nodegroup (requires cluster_name).

  • cluster_name (optional): Name of the EKS cluster (required for cluster-scoped resources).

get_eks_insights Retrieves EKS cluster insights and recommendations for optimization. Provides actionable insights for security, performance, and cost optimization based on AWS best practices and cluster analysis.

Parameters:

  • cluster_name (required): Name of the EKS cluster.

  • category (optional): Optional category to filter insights by (e.g., "MISCONFIGURATION" or "UPGRADE_READINESS").

  • insight_id (optional): Optional ID of a specific insight to get detailed information for.

  • next_token (optional): Optional token for pagination to get the next set of results.

get_eks_vpc_config Retrieves VPC configuration for an EKS cluster, including subnets, route tables, and network connectivity.

Parameters:

  • cluster_name (required): Name of the EKS cluster to get VPC configuration for.

  • vpc_id (optional): ID of the specific VPC to query (optional, will use cluster VPC if not specified).

get_k8s_events Retrieves Kubernetes events related to specific resources for troubleshooting and monitoring.

Parameters:

  • cluster_name (required): Name of the EKS cluster where the resource is located.

  • kind (required): Kind of the involved object (e.g., "Pod", "Deployment", "Service"). Must match the resource kind exactly.

  • name (required): Name of the involved object to get events for.

  • namespace (optional): Namespace of the involved object. Required for namespaced resources (like Pods, Deployments). Not required for cluster-scoped resources (like Nodes, PersistentVolumes).

get_pod_logs Retrieves logs from pods in an EKS cluster with filtering options.

Parameters:

  • cluster_name (required): Name of the EKS cluster where the pod is running.

  • namespace (required): Kubernetes namespace where the pod is located.

  • pod_name (required): Name of the pod to retrieve logs from.

  • container_name (optional): Name of the specific container to get logs from. Required only if the pod contains multiple containers.

  • limit_bytes (optional): Maximum number of bytes to return. Default: 10KB (10240 bytes).

  • previous (optional): Return previous terminated container logs (defaults to false). Useful to get logs for pods that are restarting.

  • since_seconds (optional): Only return logs newer than this many seconds. Useful for getting recent logs without retrieving the entire history.

  • tail_lines (optional): Number of lines to return from the end of the logs. Default: 100.

list_api_versions Lists all available API versions in the specified Kubernetes cluster.

Parameters:

  • cluster_name (required): Name of the EKS cluster.

list_k8s_resources Lists Kubernetes resources of a specific kind in an EKS cluster.

Parameters:

  • cluster_name (required): Name of the EKS cluster where the resources are located.

  • kind (required): Kind of the Kubernetes resources to list (e.g., 'Pod', 'Service', 'Deployment'). Use the list_api_versions tool to find available resource kinds.

  • api_version (required): API version of the Kubernetes resources (e.g., 'v1', 'apps/v1', 'networking.k8s.io/v1'). Use the list_api_versions tool to find available API versions.

  • field_selector (optional): Field selector to filter resources (e.g., 'metadata.name=my-pod,status.phase=Running'). Uses the same syntax as kubectl’s --field-selector flag.

  • label_selector (optional): Label selector to filter resources (e.g., 'app=nginx,tier=frontend'). Uses the same syntax as kubectl’s --selector flag.

  • namespace (optional): Namespace of the Kubernetes resources to list. If not provided, resources will be listed across all namespaces (for namespaced resources).

read_k8s_resource Retrieves detailed information about a specific Kubernetes resource in an EKS cluster.

Parameters:

  • api_version (required): API version of the Kubernetes resource (e.g., "v1", "apps/v1", "networking.k8s.io/v1").

  • cluster_name (required): Name of the EKS cluster where the resource is located.

  • kind (required): Kind of the Kubernetes resource (e.g., "Pod", "Service", "Deployment").

  • name (required): Name of the Kubernetes resource to read.

  • namespace (optional): Namespace of the Kubernetes resource. Required for namespaced resources. Not required for cluster-scoped resources (like Nodes, PersistentVolumes).

generate_app_manifest Generates standardized Kubernetes deployment and service manifests for containerized applications.

Parameters:

  • app_name (required): Name of the application. Used for deployment and service names, and for labels.

  • image_uri (required): Full ECR image URI with tag (e.g., 123456789012.dkr.ecr.region.amazonaws.com/repo:tag). Must include the full repository path and tag.

  • load_balancer_scheme (optional): AWS load balancer scheme. Valid values:

  • "internal" (private VPC only)

  • "internet-facing" (public access).

  • Default: "internal".

  • cpu (optional): CPU request for each container (e.g., "100m" for 0.1 CPU cores, "500m" for half a core). Default: "100m".

  • memory (optional): Memory request for each container (e.g., "128Mi" for 128 MiB, "1Gi" for 1 GiB). Default: "128Mi"

  • namespace (optional): Kubernetes namespace to deploy the application to. Default: "default".

  • port (optional): Container port that the application listens on. Default: 80

  • replicas (optional): Number of replicas to deploy. Default: 2

get_cloudwatch_logs Queries CloudWatch logs with filtering based on the input parameters and support for standard log groups used for EKS cluster observability.

Parameters:

  • cluster_name (required): Name of the EKS cluster where the resource is located. Used to construct the CloudWatch log group name.

  • resource_type (required): Resource type to search logs for. Valid values: +"pod", "node", "container", "cluster". This determines how logs are filtered.

  • log_type (required): Log type to query. Valid values:

  • "application": Container/application logs

  • "host": Node-level system logs

  • "performance": Performance metrics logs

  • "control-plane": EKS control plane logs

  • "your-log-group-name": Provide a custom CloudWatch log group name directly.

  • resource_name (optional): Resource name to search for in log messages (e.g., pod name, node name, container name). Used to filter logs for the specific resource.

  • minutes (optional): Number of minutes to look back for logs. Default: 15. Ignored if start_time is provided. Use smaller values for recent issues, larger values for historical analysis.

  • start_time (optional): Start time in ISO format (e.g., "2023-01-01T00:00:00Z"). If provided, overrides the minutes parameter.

  • end_time (optional): End time in ISO format (e.g., "2023-01-01T01:00:00Z"). If not provided, defaults to current time.

  • fields (optional): Custom fields to include in the query results (defaults to "@timestamp, @message"). Use CloudWatch Logs Insights field syntax.

  • filter_pattern (optional): Additional CloudWatch Logs filter pattern to apply. Uses CloudWatch Logs Insights syntax (e.g., "ERROR", "field=value").

  • limit (optional): Maximum number of log entries to return. Use lower values (10-50) for faster queries, higher values (100-1000) for more comprehensive results. Higher values may impact performance.

get_cloudwatch_metrics Retrieves CloudWatch metrics and data points for EKS cluster monitoring and performance analysis. Handles Container Insights metrics, custom metrics, and configurable time periods and dimensions.

Parameters:

  • cluster_name (required): Name of the EKS cluster to get metrics for.

  • dimensions (required): Dimensions to use for the CloudWatch metric query as a JSON string. Must include appropriate dimensions for the resource type and metric (e.g., '{"ClusterName": "my-cluster", "PodName": "my-pod", "Namespace": "default"}').

  • metric_name (required): Metric name to retrieve. Common examples:

  • cpu_usage_total: Total CPU usage

  • memory_rss: Resident Set Size memory usage

  • network_rx_bytes: Network bytes received

  • network_tx_bytes: Network bytes transmitted

  • namespace (required): CloudWatch namespace where the metric is stored. Common values:

  • "ContainerInsights": For container metrics

  • "AWS/EC2": For EC2 instance metrics

  • "AWS/EKS": For EKS control plane metrics

  • minutes (optional): Number of minutes to look back for metrics. Default: 15. Ignored if start_time is provided.

  • start_time (optional): Start time in ISO format (e.g., "2023-01-01T00:00:00Z"). If provided, overrides the minutes parameter.

  • end_time (optional): End time in ISO format (e.g., "2023-01-01T01:00:00Z"). If not provided, defaults to current time.

  • limit (optional): Maximum number of data points to return. Higher values (100-1000) provide more granular data but may impact performance. Default: 50.

  • period (optional): Period in seconds for the metric data points. Default: 60 (1 minute). Lower values (1-60) provide higher resolution but may be less available.

  • stat (optional): Statistic to use for the metric aggregation. Default: "Average". Valid values:

  • Average: Mean value during the period

  • Sum: Total value during the period

  • Maximum: Highest value during the period

  • Minimum: Lowest value during the period

  • SampleCount: Number of samples during the period.

get_eks_metrics_guidance Get CloudWatch metrics guidance for specific resource types in EKS clusters. Useful for the agent when determining the correct dimensions to use with the get_cloudwatch_metrics tool.

Parameters:

  • resource_type (required): Type of resource to get metrics for (cluster, node, pod, namespace, service).

get_policies_for_role Retrieves all policies attached to a specified IAM role, including assume role policy, managed policies, and inline policies.

Parameters:

  • role_name (required): Name of the IAM role to get policies for. The role must exist in your AWS account.

Full access (write) tools

This section describes the read-only tools available for the EKS MCP Server. Note that (as of "today") all write Kubernetes API operations can access only:

  • Public clusters (endpointPublicAccess=true)

manage_k8s_resource Manages a single Kubernetes resource with write operations (create, update, patch, or delete).

Parameters:

  • operation (required): Operation to perform on the resource. Valid values:

  • create: Create a new resource

  • replace: Replace an existing resource

  • patch: Update specific fields of an existing resource

  • delete: Delete an existing resource

  • Note: Use read_k8s_resource for reading resources and list_k8s_resources for listing multiple resources.

  • cluster_name (required): Name of the EKS cluster where the resource is located or will be created.

  • kind (required): Kind of the Kubernetes resource (e.g., "Pod", "Service", "Deployment").

  • api_version (required): API version of the Kubernetes resource (e.g., "v1", "apps/v1", "networking.k8s.io/v1").

  • body (optional): Resource definition as a JSON string. Required for create, replace, and patch operations. For create and replace, this should be a complete resource definition. For patch, this should contain only the fields to update.

  • name (optional): Name of the Kubernetes resource. Required for all operations except create (where it can be specified in the body).

  • namespace (optional): Namespace of the Kubernetes resource. Required for namespaced resources. Not required for cluster-scoped resources (like Nodes, PersistentVolumes).

apply_yaml Applies Kubernetes YAML manifests to an EKS cluster.

Parameters:

  • cluster_name (required): Name of the EKS cluster where the resources will be created or updated.

  • namespace (required): Kubernetes namespace to apply resources to. Will be used for name-spaced resources that do not specify a namespace.

  • yaml_content (required): YAML content to apply to the cluster. Can contain multiple documents separated by '---'.

  • force (optional): Whether to update resources if they already exist (similar to kubectl apply). Set to false to only create new resources.

manage_eks_stacks Manages EKS CloudFormation stacks with operations for generating templates, deploying, describing, and deleting EKS clusters and their underlying infrastructure. Cluster creation typically takes 15-20 minutes to complete. For deploy and delete operations, the stack must have been created by this tool (i.e., tagged with CreatedBy=EksMcpServer).

Parameters:

  • cluster_name (required): Name of the EKS cluster (for generate, deploy, describe and delete operations). This name will be used to derive the CloudFormation stack name and will be embedded in the cluster resources.

  • operation (required): Operation to perform. Valid values:

  • generate: Generate a CloudFormation template

  • deploy: Deploy a CloudFormation stack (requires template_content)

  • describe: Describe/read a CloudFormation stack (read-only)

  • delete: Delete a CloudFormation stack

  • template_content (optional): CloudFormation template content (for deploy operations). This should be the complete YAML or JSON template content. Supports both single resources and multi-document YAML content separated by '---'.

add_inline_policy Adds a new inline policy to an IAM role.

Parameters:

  • permissions (required): Permissions to include in the policy as JSON strings representing IAM policy statements. Can be either a single JSON string or an array of JSON strings.

  • policy_name (required): Name of the inline policy to create. Must be unique within the role.

  • role_name (required): Name of the IAM role to add the policy to. The role must exist.