AWS Ghost Developer — MCP Serverless Agent

Version: 1.0

An MCP (Model Context Protocol) server running on AWS Lambda that acts as a secure proxy between an AI assistant (Claude, Cursor) and your AWS infrastructure. It gives the AI read-only access to your systems so it can help investigate incidents without needing human copy-paste of logs.

---

What it does (v1.0)

This version focuses on triage — collecting raw data from two sources fast enough that an AI can summarize what is failing and where.

| Tool | What it answers | |---|---| | list_dlqs | "Which Dead Letter Queues have messages piling up?" | | inspect_dlq_payload | "What do those failed messages look like?" | | search_log_groups | "Which CloudWatch log groups exist for this service?" | | get_error_traces | "What errors appeared in these log groups recently?" |

Honest scope

v1.0 helps an AI identify symptoms (error messages, failed payloads) but does not determine root cause automatically. It is most useful for:

On-call triage at odd hours — reduce time-to-data from 30+ minutes to under a minute
Letting a junior engineer hand off context to an AI before escalating
Situations where copy-pasting logs manually is the main bottleneck

It does not (yet) cover: X-Ray service maps, deployment correlation, infrastructure metrics.

---

Architecture

Claude / Cursor
      │  HTTPS + x-api-key header
      ▼
API Gateway (HTTP API)
      │
      ▼  Lambda Authorizer (validates API key via Secrets Manager)
      ▼
Lambda: mcp-router
      ├── SQS   → list_dlqs, inspect_dlq_payload
      └── Logs  → search_log_groups, get_error_traces

Two CloudFormation stacks:

aws-ghost-developer-secrets-{env} — manages the API key in Secrets Manager
aws-ghost-developer-{env} — Lambda, API Gateway, IAM roles (deployed via SAM)

---

Prerequisites

AWS CLI configured (aws configure)
AWS SAM CLI (pip install aws-sam-cli)
Python 3.12+
openssl (available on macOS/Linux by default; on Windows use Git Bash or WSL)

---

Setup

1. Clone and install dependencies

git clone <repo-url>
cd aws-ghost-developer
pip install -r requirements.txt

2. Configure region in samconfig.toml

Open samconfig.toml and update the region to match where you want to deploy:

[default.deploy.parameters]
region = "ap-southeast-1"   # change this to your target region

Note: bootstrap.sh reads AWS_DEFAULT_REGION at runtime, but sam deploy also picks up region from samconfig.toml. Keep them in sync to avoid deploying to the wrong region.

3. Run bootstrap (one command does everything)

export AWS_DEFAULT_REGION=ap-southeast-1   # must match samconfig.toml
./scripts/bootstrap.sh prod

This will:

Generate a cryptographically secure API key
Deploy infra/secrets.yaml to store the key in Secrets Manager
Build and deploy the SAM stack
Print the MCP endpoint URL and config snippet

For other environments:

./scripts/bootstrap.sh dev
./scripts/bootstrap.sh staging

At the end you will see output like:

  {
    "mcpServers": {
      "aws-ghost-developer": {
        "url": "https://<api-id>.execute-api.ap-southeast-1.amazonaws.com/mcp",
        "transport": "http",
        "headers": {
          "x-api-key": "<generated-key>"
        }
      }
    }
  }

Copy the url and x-api-key values — you will need them in the next step.

4. Add to your MCP client

Claude Code CLI (recommended)

claude mcp add --transport http aws-ghost-developer \
  https://<api-id>.execute-api.<region>.amazonaws.com/mcp \
  --header "x-api-key:<your-generated-key>"

Verify it was added:

claude mcp get aws-ghost-developer

Claude Desktop (macOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aws-ghost-developer": {
      "url": "https://<api-id>.execute-api.<region>.amazonaws.com/mcp",
      "transport": "http",
      "headers": {
        "x-api-key": "<your-generated-key>"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project root (or the global Cursor MCP config):

{
  "mcpServers": {
    "aws-ghost-developer": {
      "url": "https://<api-id>.execute-api.<region>.amazonaws.com/mcp",
      "transport": "http",
      "headers": {
        "x-api-key": "<your-generated-key>"
      }
    }
  }
}

---

Usage examples

Once connected, you can ask the AI naturally:

"Check if there are any failed messages in our SQS queues for the payment service"

"Look at the dead letter queue for order-processor and tell me what's failing"

"Find the CloudWatch logs for the auth service and show me errors from the last hour"

"Search log groups for 'checkout' and query them for 5xx errors in the last 30 minutes"

---

Project structure

aws-ghost-developer/
├── src/
│   ├── handler.py              # Lambda entrypoint, MCP JSON-RPC router
│   ├── authorizer.py           # Lambda authorizer — validates x-api-key
│   ├── transport/
│   │   └── sse.py              # MCP response/error formatters
│   ├── tools/
│   │   ├── __init__.py         # Tool registry
│   │   ├── list_dlqs.py        # List SQS Dead Letter Queues
│   │   ├── inspect_dlq.py      # Peek at DLQ messages
│   │   ├── search_log_groups.py # Discover CloudWatch log groups
│   │   └── get_error_traces.py  # Query Logs Insights (async-safe)
│   └── utils/
│       ├── redact.py           # Auto-redact secrets from responses
│       └── secrets.py          # Secrets Manager wrapper with TTL cache
├── infra/
│   └── secrets.yaml            # CloudFormation — Secrets Manager stack
├── scripts/
│   ├── bootstrap.sh            # Full setup: secrets + SAM deploy
│   └── gen-secret.sh           # Secrets only (for key rotation)
├── tests/
│   └── unit/
├── template.yaml               # SAM template — Lambda + API Gateway
├── samconfig.toml              # SAM deploy defaults
└── requirements.txt

---

Security

All tools are read-only. No write/delete permissions are granted.
API key is stored in AWS Secrets Manager, never in environment variables.
The Lambda authorizer validates every request using constant-time comparison.
IAM role follows least-privilege — each permission is scoped to the minimum required action.
DLQ messages are peeked with a 30-second visibility timeout and never deleted.
Sensitive values (passwords, tokens) in message payloads are automatically redacted before being returned to the AI.

---

Rotating the API key

./scripts/gen-secret.sh prod

Then update mcp_config.json with the new key. No redeployment needed.

---

Running tests

pip install pytest
python -m pytest tests/unit/ -v

---

Roadmap

v1.0 covers triage. Planned for future versions:

v1.1 — X-Ray service map (get_service_map) to trace which service in a chain is failing
v1.2 — Deployment correlation (get_recent_deployments) via CloudTrail to link errors to releases
v2.0 — Multi-region support, structured RCA report generation

ghost-dev-mcp