name:: mcp
description:: MCP server and client development — scaffold, implement tools/resources/prompts, validate schemas, debug protocol compliance, and deploy with auth and rate limiting.
argument-hint:: [create|review|debug] [typescript|python] [description]

Build, review, or debug an MCP (Model Context Protocol) server or client.

Mode: create

Scaffold a production-ready MCP server.

Steps:

Ask for: language (TypeScript or Python), transport (stdio / HTTP+SSE), list of tools and resources needed
Generate project scaffold with correct SDK setup
Implement tool handlers with Zod (TypeScript) or Pydantic (Python) schema validation
Add resource providers and prompt templates as needed
Configure transport layer
Add error handling — return isError: true content, never throw unhandled exceptions to clients
Add authentication and rate limiting for HTTP transports
Provide MCP Inspector test commands and expected responses
Add deployment checklist (env vars, secrets, logging)

Reference: references/mcp.md → Protocol Fundamentals, TypeScript SDK, Python SDK

Mode: review

Review an existing MCP server or client implementation.

Evaluate in priority order:

Protocol compliance — JSON-RPC 2.0 correctness, proper capability negotiation, well-formed content arrays
Schema validation — all tool inputs validated with Zod/Pydantic; no z.any() or empty schemas
Security — no credentials in tool responses or resource content; auth on HTTP transports; rate limiting present
Error handling — errors return isError: true with a message, not unhandled exceptions
Transport — correct transport for the use case; no blocking sync code in async transports

Output: Critical (must fix) / Improvement (should fix) / Note (informational)

Reference: references/mcp.md → Security, Error Handling, Testing and Debugging

Mode: debug

Diagnose MCP protocol or integration failures.

Classify the failure:

Transport — connection refused, EOF, serialisation error
Protocol — malformed JSON-RPC, missing id, wrong method names
Schema — Zod/Pydantic validation rejection, unexpected input types
Handler — unhandled exception, timeout, wrong return shape
Integration — tool not appearing in host, capabilities mismatch

Evidence to collect:

# Run MCP Inspector to verify protocol compliance
npx @modelcontextprotocol/inspector node dist/index.js

# Smoke-test via stdio
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

# Check for schema errors
node -e "require('./dist/index.js')" 2>&1

Provide: observed symptom → likely root cause → evidence command → fix → validation step

Mode: configure-aws

Generate version-pinned, credential_process-backed MCP server configs for AWS services, with upfront cost warnings and CLI-first alternatives.

/platform-skills:mcp configure-aws [service|kit] [--profile <profile>] [--region <region>] [--host vscode|claude|both] [--scope global|workspace] [--multi-account]

Examples:

/platform-skills:mcp configure-aws eks-debug --profile prod-platform-eu --region eu-west-1 --host both
/platform-skills:mcp configure-aws eks --profile dev-sandbox --host vscode --scope workspace
/platform-skills:mcp configure-aws knowledge --host claude
/platform-skills:mcp configure-aws eks --profile prod-eu --region eu-west-1 --multi-account

Step 0: Gather Inputs (interactive — fires when any required value is missing)

When the user invokes configure-aws without arguments, or omits any required value, prompt for each missing piece one question at a time before proceeding.

Question 1 — Service or kit (skip if already provided as positional arg):

Which AWS service or starter kit do you need?

Services:
  eks         EKS cluster ops, nodegroups           (~2,000 tokens)
  cloudwatch  Logs, metrics, alarms                 (~1,750 tokens)
  prometheus  AMP metrics, rule groups              (~1,000 tokens)
  iam         IAM queries, read-only                (~1,500 tokens)
  bedrock-kb  Knowledge base retrieve + generate    (~750 tokens)
  docs        Real-time AWS documentation           (~500 tokens)
  api         All AWS services, catch-all           (~2,500 tokens)
  billing     Cost Explorer, budgets                (~1,000 tokens)
  serverless  SAM, Lambda lifecycle                 (~1,250 tokens)
  dynamodb    Table ops, queries                    (~1,250 tokens)

Starter kits (pre-bundled):
  eks-debug   eks + cloudwatch                      (~3,750 tokens)
  observe     cloudwatch + prometheus               (~2,750 tokens)
  knowledge   docs + bedrock-kb                     (~1,250 tokens)
  deploy      api + serverless                      (~3,750 tokens)
  cost        billing                               (~1,000 tokens)

Enter service or kit name:

Question 2 — Host (skip if --host provided):

Which tool are you configuring for?
  1. VS Code
  2. Claude Code
  3. Both

Enter 1, 2, or 3:

Question 3 — AWS profile (skip if --profile provided):

Read ~/.aws/config, list available profiles with type and environment tag (from ~/.aws-profile-tags.yaml if present):

Which AWS profile should MCP servers use?

Available profiles (from ~/.aws/config):
  prod-platform-eu   SSO          [prod]     123456789
  staging-assume     assumed-role [staging]  456789123
  dev-sandbox        SSO          [dev]      987654321

Enter profile name (or press enter for no profile — uses ambient credentials):

If ~/.aws/config is not readable or has no profiles, show: Could not read ~/.aws/config. Enter profile name manually (or press enter to skip):

Question 4 — Region (skip if --region provided):

Detect the profile's region field from ~/.aws/config and offer it as the default:

AWS region? [detected from profile 'prod-platform-eu': eu-west-1]
Press enter to accept or type a different region:

If no region is detected in the profile: AWS region? (e.g. us-east-1):

Question 5 — Scope (VS Code only; skip if --scope provided):

VS Code config scope?
  1. Workspace — .vscode/mcp.json (this project only)
  2. Global    — applies to all VS Code windows

Enter 1 or 2:

Question 6 — Multi-account (eks service only; skip if --multi-account provided or service is not eks):

Generate named instances for all prod-tagged profiles? (multi-account mode)
  This creates eks-prod-eu, eks-prod-us, etc. from ~/.aws-profile-tags.yaml.
  Requires ~/.aws-profile-tags.yaml with env: prod entries.

[y/N]:

After collecting all answers, confirm before proceeding:

Summary:
  Service/kit : eks-debug (eks + cloudwatch)
  Host        : both (VS Code + Claude Code)
  Profile     : prod-platform-eu
  Region      : eu-west-1
  VS Code scope: workspace

Proceeding with cost check...

Then continue with Steps 1–4 below using the collected values.

Step 1: Cost Warning

Before generating any config, show tool count and token cost. If total exceeds 5,000 tokens, flag it:

Servers requested: eks-mcp-server + cloudwatch-mcp-server

  awslabs.eks-mcp-server           ~40 tools   ~2,000 tokens
  awslabs.cloudwatch-mcp-server    ~35 tools   ~1,750 tokens
  ──────────────────────────────────────────────────────────
  Total                            ~75 tools   ~3,750 tokens

✓ Within recommended budget (<5,000 tokens). Continue? [y/N]

If over 5,000 tokens:

⚠ Over budget — ~8,500 tokens will be consumed by tool definitions before any conversation.
  This will noticeably compress available context for reasoning.
  Recommended: split into separate sessions, one kit per task.
  Continue anyway? [y/N]

Step 2: CLI-First Check

For simple single-service requests, show the CLI alternative before generating MCP config:

💡 For common EKS queries, the AWS CLI costs zero context:

  aws eks list-clusters --profile prod-platform-eu --region eu-west-1
  aws eks describe-cluster --name my-cluster --profile prod-platform-eu --region eu-west-1
  aws eks list-nodegroups --cluster-name my-cluster --profile prod-platform-eu

MCP adds value when the AI needs to chain calls — e.g., list clusters → describe all nodegroups →
correlate with CloudWatch alarms → identify degraded nodes → suggest remediation.

Is that the task you need? [y to continue with MCP / n to use CLI]

Step 3: credential_process Check

Before generating the config, check whether the target profile in ~/.aws/config has credential_process configured:

Has credential_process → generate config with AWS_PROFILE env var (credential_process handles refresh)
No credential_process → warn and emit both the MCP config AND the recommended ~/.aws/config stanza:

⚠ Profile 'prod-platform-eu' does not have credential_process configured.
  MCP servers using this profile will fail silently when the SSO token expires (TTL: ~8h).

  Add this to ~/.aws/config for automatic credential refresh:

  [profile prod-platform-eu]
  # ... existing fields ...
  credential_process = granted credential-process --profile prod-platform-eu

  See: references/aws-mcp-profiles.md → credential_process Pattern

Step 4: Config Generation

Emit ready-to-paste JSON for the target host(s). Always version-pin. Always set both AWS_PROFILE and AWS_REGION. Always include an _account comment.

VS Code (.vscode/mcp.json):

{
  "mcpServers": {
    "eks-prod-eu": {
      "command": "uvx",
      "args": ["awslabs.eks-mcp-server==VERSION", "--region", "eu-west-1"],
      "env": {
        "AWS_PROFILE": "prod-platform-eu",
        "AWS_REGION": "eu-west-1"
      },
      "_account": "Account: 123456789 | Env: prod | Permission: PowerUser"
    },
    "cloudwatch-prod-eu": {
      "command": "uvx",
      "args": ["awslabs.cloudwatch-mcp-server==VERSION"],
      "env": {
        "AWS_PROFILE": "prod-platform-eu",
        "AWS_REGION": "eu-west-1"
      },
      "_account": "Account: 123456789 | Env: prod | Permission: PowerUser"
    }
  }
}

Claude Code (~/.claude/settings.json → mcpServers):

{
  "eks-prod-eu": {
    "command": "uvx",
    "args": ["awslabs.eks-mcp-server==VERSION", "--region", "eu-west-1"],
    "env": {
      "AWS_PROFILE": "prod-platform-eu",
      "AWS_REGION": "eu-west-1"
    },
    "_account": "Account: 123456789 | Env: prod | Permission: PowerUser"
  }
}

Replace VERSION with the current version from PyPI:

pip index versions awslabs.eks-mcp-server 2>/dev/null | head -1

Multi-Account Mode (`--multi-account`)

When --multi-account is passed for the eks service, generate distinct named instances for each prod-tagged profile in ~/.aws-profile-tags.yaml:

{
  "mcpServers": {
    "eks-prod-eu": {
      "command": "uvx",
      "args": ["awslabs.eks-mcp-server==VERSION", "--region", "eu-west-1"],
      "env": { "AWS_PROFILE": "prod-platform-eu", "AWS_REGION": "eu-west-1" },
      "_account": "123456789 | prod-eu"
    },
    "eks-prod-us": {
      "command": "uvx",
      "args": ["awslabs.eks-mcp-server==VERSION", "--region", "us-east-1"],
      "env": { "AWS_PROFILE": "prod-platform-us", "AWS_REGION": "us-east-1" },
      "_account": "234567890 | prod-us"
    }
  }
}

Show updated token cost after generating multi-instance config.

AWS MCP Server Catalog

Kit / Service	Package	~Tokens	Use case
`eks`	`awslabs.eks-mcp-server`	~2,000	Cluster ops, nodegroups
`cloudwatch`	`awslabs.cloudwatch-mcp-server`	~1,750	Logs, metrics, alarms
`prometheus`	`awslabs.prometheus-mcp-server`	~1,000	AMP metrics, rule groups
`iam`	`awslabs.iam-mcp-server`	~1,500	IAM queries (read-only)
`bedrock-kb`	`awslabs.bedrock-kb-retrieval-mcp-server`	~750	KB retrieve + generate
`docs`	`awslabs.aws-documentation-mcp-server`	~500	Real-time AWS docs
`api`	`awslabs.aws-api-mcp-server`	~2,500	All AWS services (catch-all)
`billing`	`awslabs.billing-cost-management-mcp-server`	~1,000	Cost Explorer, budgets
`serverless`	`awslabs.aws-serverless-mcp-server`	~1,250	SAM, Lambda lifecycle
`dynamodb`	`awslabs.dynamodb-mcp-server`	~1,250	Table ops, queries

Starter kits (pass kit name instead of service):

Kit	Servers	~Tokens
`eks-debug`	eks + cloudwatch	~3,750
`observe`	cloudwatch + prometheus	~2,750
`knowledge`	docs + bedrock-kb	~1,250
`deploy`	api + serverless	~3,750
`cost`	billing	~1,000