<!-- mcp-name: io.github.infraveilhq/control-plane -->

# Infraveil MCP server

A hardened, self-hosted [Model Context Protocol](https://modelcontextprotocol.io)
server that lets your own AI agent **query and govern your Infraveil control
plane in-loop** — read the governed state of your backend, and file deploy and
remediation requests that always pass through human approval.

It is built on the same principle as the rest of Infraveil: **trust by
inspection, not assertion.** This server adds no new authority and no new auth
surface. It signs every request with the token your agent already holds, and it
**verifies the control plane's signed responses in return** — so neither side
can be forged on the wire. You can read every line here and diff the signing
code against the published agent source; they are the same scheme.

## Why this exists

The MCP ecosystem's security is, bluntly, bad — most public MCP servers require
no auth at all. An MCP server that hands an AI agent operational reach into your
backend is exactly the thing that should *not* be unauthenticated. This one:

- **Signs both directions** (HMAC-SHA256 over a canonical request/response,
  keyed by your per-agent token; nonce + timestamp replay protection).
- **Cannot apply a change by itself.** `request_deploy` and `remediate` enqueue
  a request into the control plane's human-approval queue and return the
  approval URL. There is no code path here that mutates your infrastructure.
- **Is least-privilege.** The token is scoped to one client/agent; tenancy is
  enforced by the control plane. This process holds no more authority than the
  agent already running on the host.

## Install

```bash
pip install infraveil-mcp
```

## Configure

The server reuses your existing Infraveil agent identity — it never mints
credentials. Either set the environment variables:

```bash
export INFRAVEIL_BASE_URL=https://api.infraveil.com
export INFRAVEIL_CLIENT_ID=...
export INFRAVEIL_AGENT_ID=...
export INFRAVEIL_AGENT_TOKEN=...        # your agent's existing token
```

…or point it at your rendered agent source and let it read the ids and token
straight out of the file you can already inspect:

```bash
export INFRAVEIL_AGENT_FILE=/opt/infraveil/agent.py
```

### Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "infraveil": {
      "command": "infraveil-mcp",
      "env": {
        "INFRAVEIL_BASE_URL": "https://api.infraveil.com",
        "INFRAVEIL_CLIENT_ID": "...",
        "INFRAVEIL_AGENT_ID": "...",
        "INFRAVEIL_AGENT_TOKEN": "..."
      }
    }
  }
}
```

## Tools

**Read (no side effects):**

| Tool | What it returns |
| --- | --- |
| `get_agent_status` | Fleet/agent state: online/offline, heartbeats, CPU/mem/disk, deploy state |
| `get_security_findings` | Active security policy + recent security events |
| `get_request_trace` | Recent request/operation traces and outcomes |
| `query_runtime_truth_graph` | Authoritative host ↔ agent ↔ service ↔ policy snapshot |

**Governed (enqueue for human approval — never auto-applied):**

| Tool | What it does |
| --- | --- |
| `evaluate_deploy_gate` | Reports whether a proposed change would pass policy. Read-only. |
| `request_deploy` | Files a deploy request into the approval queue; returns request id + approval URL |
| `remediate` | Files a remediation proposal (respects your blocked categories); returns id + approval URL |

## Verify it yourself

1. Read [`infraveil_mcp/client.py`](infraveil_mcp/client.py). The request-signing
   and response-verification code is plain stdlib `hmac`/`hashlib`.
2. Diff it against the published Infraveil agent source (`_signed_headers`,
   `verify_response_signature`). They implement the same protocol.
3. Run the test suite: `pytest tests/`. It transcribes the *server's* verifier
   and asserts this client's signatures are accepted and tampering is rejected.

## License

[AGPL-3.0-or-later](LICENSE). The control plane (central authority graph,
multi-tenant policy, audit/evidence store) is the commercial product; the code
that runs on your machine is open because you should never have to trust code
you can't read.