> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sector8.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Guard MCP Server

> Govern Claude Code and MCP-compatible agent tool calls with fail-closed enforcement and forensic telemetry.

## What it does

The Guard MCP Server intercepts Claude Code tool calls before OS execution. It governs
`bash`, `read_file`, `write_file`, and `web_fetch` by routing each call through the
Sector8 Admission Controller.

This is not a separate policy path. The MCP server uses the same guard engine, invariants,
evidence hashing, and telemetry model as the rest of the Guard Module.

## Installation

Primary path after installing the SDK:

```bash theme={null}
pip install sector8-sdk
```

Then run:

```bash theme={null}
sector8-guard install
```

This writes `.claude/settings.json` for the current project and preserves existing
settings keys.

The installer writes a relative command entry that targets the checked-in MCP server
launcher from the repo root. On Windows it prefers the `.cmd` wrapper when present.

Manual fallback:

```json theme={null}
{
  "mcpServers": {
    "sector8-guard": {
      "command": "python",
      "args": ["sector8-backend/scripts/mcp_stdio_server.py"],
      "env": {
        "SECTOR8_API_KEY": "${SECTOR8_API_KEY}",
        "SECTOR8_CLIENT_ID": "${SECTOR8_CLIENT_ID}"
      }
    }
  }
}
```

On Windows, replace the args path with the `.cmd` wrapper if present:

```json theme={null}
{
  "mcpServers": {
    "sector8-guard": {
      "command": "scripts/run_sector8_guard_mcp.cmd",
      "args": []
    }
  }
}
```

## How it works

```text theme={null}
Claude Code tool call
        |
        v
Guard MCP Server
        |
        v
Admission Controller
  |- pre-filter
  |- rate and multi-turn checks
  |- tool registration and capability checks
  |- BOLA and BFLA checks
  |- semantic and segmented-input checks
  |- request-risk checks
        |
   +----+----+
   |         |
   v         v
 DENY      ALLOW
   |         |
   |         +-- tool executes
   +-- tool never executes
```

The Guard MCP Server uses the same Admission Controller as the REST API. Policy,
telemetry, and forensic records are unified across both paths.

## Security guarantees

### Fail-closed on guard exception

If any unhandled exception occurs in the evaluation path, the decision is `DENY`. The tool
does not execute.

Returned denial:

* `reason_code: GUARD_INTERNAL_ERROR`
* non-empty `evidence_hash`
* `has_forensic_payload: true`
* `decision_trace_id`
* `policy_version_id`

There is no fail-open path.

### Forensic completeness on deny

Every denied MCP response includes:

* `decision`
* `reason_code`
* `evidence_hash`
* `has_forensic_payload`
* `decision_trace_id`
* `policy_version_id`

This is enforced by the deny invariant in CI.

### Authorization is enforced, not advisory

The admission path enforces:

* tool registration
* capability checks
* object-level authorization (BOLA)
* function-level authorization (BFLA)
* semantic threat scoring
* segmented-input safety
* request-risk checks such as SSRF and sensitive path access
* admission rate limiting

## Governed tools

| Tool         | What gets checked                                                                                                                   |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `bash`       | shell injection, destructive commands, obfuscated command payloads, rate limiting                                                   |
| `read_file`  | sensitive paths, object ownership, authorization                                                                                    |
| `write_file` | content safety, authorization, object scoping                                                                                       |
| `web_fetch`  | SSRF, private IP ranges, localhost, DNS resolution to private targets, unsupported schemes, URL credentials, external domain policy |

## `web_fetch` protections

`web_fetch` is not guarded by a simple hostname allowlist.

The current request-risk path blocks:

* raw private IP targets
* loopback and localhost
* link-local targets such as `169.254.169.254`
* DNS results that resolve to private IP space
* unsupported URL schemes
* URL credentials
* non-allowlisted external domains

This is designed to stop common SSRF paths, including cloud metadata access.

## Example - blocked call

```json theme={null}
{
  "decision": "DENY",
  "tool_name": "bash",
  "reason_code": "MCP_SHELL_INJECTION_BLOCKED",
  "evidence_hash": "bdbde1558fb883573b0f6e8630ccba1edaf6bed8cb035fa6a48912809149f287",
  "has_forensic_payload": true,
  "decision_trace_id": "32819155-d21a-49c8-9509-79338d980fa9",
  "policy_version_id": "0dbca364d66447469637bafa2282e635124fcb99eecd6383038e3b652577ebc7"
}
```

## Example - allowed call

```json theme={null}
{
  "decision": "ALLOW",
  "tool_name": "bash",
  "evidence_hash": "4cb7f786d1f3b57e6f98f3e60d2eb6b81c402d6d3efeb6c9551049f7c14df2f0",
  "has_forensic_payload": false,
  "decision_trace_id": "17e797c0-eb5c-4f97-b4a1-2d3e4f5a6b7c",
  "result": {
    "stdout": "hello",
    "stderr": "",
    "exit_code": 0
  }
}
```

## Verify the connection

Inside Claude Code:

```text theme={null}
/mcp
```

You should see `sector8-guard` as a connected server.

Then test one allow and one deny:

```text theme={null}
Use the sector8-guard MCP server to run bash: echo hello
Use the sector8-guard MCP server to run bash: rm -rf /
```

Expected:

* `echo hello` -> `ALLOW`
* `rm -rf /` -> `DENY`

## Fleet deployment

Distribute `.claude/settings.json` through the repo or developer environment management.
Each engineer then gets governed tool execution with the same denial schema and forensic
model.

## Non-MCP agents

MCP-compatible agents are covered natively. Non-MCP tool callers, including containerized
Codex CLI integrations, use the SDK adapter and `POST /api/v1/evaluate`.

See the [non-MCP integration guide](/guides/non-mcp-integration) for the container
pattern, required environment variables, and enforcement examples.