# Secure Agent MCP Gateway

SOC alert triage with an MCP-to-MCP **security gateway**: the agent never
talks to real tools directly. Every `tools/list` / `tools/call` is scoped
and authorized by role (`viewer` | `operator` | `admin`).

```
main.py (agent)  →  gateway  →  mcp_server (tools)
```

More detail: [gateway/README.md](gateway/README.md).

## Quick start (local)

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# edit .env — set LLM_API_KEY (never commit .env)
```

### Three role services (local)

```bash
# 1) Viewer — reputation lookups only
python main.py --mcp --role viewer --alert sample_alert.json

# 2) Operator — triage / summarize / notify (no block or escalate)
python main.py --mcp --role operator --alert sample_alert.json

# 3) Admin — full tool set through the gateway
python main.py --mcp --role admin --alert sample_alert.json
```

Deterministic path (no MCP / no gateway):

```bash
python main.py --alert sample_alert.json
```

Policy-only check:

```bash
python -m gateway.policy
```

## Docker deploy

Requires Docker + Compose. Secrets stay outside the image:

```bash
cp .env.example .env
# set LLM_API_KEY in .env
```

### Build

```bash
docker compose build
# or:
docker build -t secure-agent-mcp-gateway:latest .
```

### Three services (one role each)

Same image; different `GATEWAY_ROLE`. Each container runs the full chain
(`main` → `gateway` → `mcp_server`) for that role.

```bash
# 1) Viewer
docker compose run --rm triage-viewer

# 2) Operator
docker compose run --rm triage-operator

# 3) Admin
docker compose run --rm triage-admin
```

Or start by service name:

```bash
docker compose up triage-viewer
docker compose up triage-operator
docker compose up triage-admin
```

Pass the key without a file:

```bash
LLM_API_KEY=sk-... docker compose run --rm triage-admin
```

### Plain Docker (no Compose)

```bash
docker build -t secure-agent-mcp-gateway:latest .

docker run --rm \
  -e LLM_API_KEY \
  -e LLM_MODEL=gpt-4o-mini \
  -e GATEWAY_ROLE=viewer \
  secure-agent-mcp-gateway:latest \
  python main.py --mcp --role viewer --alert sample_alert.json

docker run --rm -e LLM_API_KEY -e GATEWAY_ROLE=operator \
  secure-agent-mcp-gateway:latest \
  python main.py --mcp --role operator --alert sample_alert.json

docker run --rm -e LLM_API_KEY -e GATEWAY_ROLE=admin \
  secure-agent-mcp-gateway:latest \
  python main.py --mcp --role admin --alert sample_alert.json
```

## Environment

| Variable | Purpose |
|----------|---------|
| `LLM_API_KEY` | Required for agent / findings summary |
| `LLM_MODEL` | Default `gpt-4o-mini` |
| `LLM_PROVIDER` | Default `openai` |
| `GATEWAY_ROLE` | `viewer` \| `operator` \| `admin` |

`.env` is gitignored. Only `.env.example` is committed.

## Roles (policy)

| Role | Can use |
|------|---------|
| `viewer` | `check_ip_reputation` |
| `operator` | reputation, triage, summarize, notify |
| `admin` | all tools including `block_ip` + `escalate_alert` |

Defined in `gateway/policy.yaml`.