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

# MCP Integration

> Use Rafter security tools with any MCP-compatible agent platform

# MCP Integration

Rafter runs as a standard [MCP server](https://modelcontextprotocol.io/) over stdio, exposing security tools to **any MCP-compatible client**—Cursor, Windsurf, Claude Desktop, Cline, and others.

No API key required. All tools run locally.

## Setup

### 1. Install Rafter CLI

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @rafter-security/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @rafter-security/cli
  ```

  ```bash pip theme={null}
  pip install rafter-cli
  ```
</CodeGroup>

### 2. Add to Your MCP Client

Add Rafter to your MCP client's server configuration:

<CodeGroup>
  ```json Claude Desktop theme={null}
  // ~/Library/Application Support/Claude/claude_desktop_config.json
  {
    "mcpServers": {
      "rafter": {
        "command": "rafter",
        "args": ["mcp", "serve"]
      }
    }
  }
  ```

  ```json Cursor theme={null}
  // .cursor/mcp.json
  {
    "mcpServers": {
      "rafter": {
        "command": "rafter",
        "args": ["mcp", "serve"]
      }
    }
  }
  ```

  <Note>
    **Cursor users hitting a sandbox prompt:** prefer the per-project install — `rafter agent init --local --with-cursor` — which writes to `./.rafter/` and `./.cursor/` instead of `$HOME`. Global install (`rafter agent init --with-cursor`) requires elevated permissions if Cursor's sandbox restricts writes to your home directory.
  </Note>

  ```json Windsurf theme={null}
  // ~/.codeium/windsurf/mcp_config.json
  {
    "mcpServers": {
      "rafter": {
        "command": "rafter",
        "args": ["mcp", "serve"]
      }
    }
  }
  ```

  ```json Generic MCP Client theme={null}
  {
    "rafter": {
      "command": "rafter",
      "args": ["mcp", "serve"]
    }
  }
  ```
</CodeGroup>

### 3. Restart Your Client

Restart the MCP client to load Rafter's tools. You should see four tools and two resources available.

## Tools

Rafter exposes four read-only security tools over MCP.

### `scan_secrets`

Scan files or directories for hardcoded secrets and credentials.

| Parameter | Type   | Required | Description                                    |
| --------- | ------ | -------- | ---------------------------------------------- |
| `path`    | string | Yes      | File or directory path to scan                 |
| `engine`  | string | No       | `auto` (default), `betterleaks`, or `patterns` |

Returns an array of scan results with file paths, pattern names, severity levels, and redacted matches.

<Accordion title="Example Response">
  ```json theme={null}
  [
    {
      "file": "src/config.ts",
      "matches": [
        {
          "pattern": "AWS Access Key",
          "severity": "critical",
          "line": 12,
          "redacted": "AKIA****"
        }
      ]
    }
  ]
  ```
</Accordion>

### `evaluate_command`

Evaluate whether a shell command is allowed by Rafter security policy.

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| `command` | string | Yes      | Shell command to evaluate |

Returns whether the command is allowed, its risk level, and whether it requires approval.

<Accordion title="Example Response">
  ```json theme={null}
  {
    "allowed": false,
    "risk_level": "critical",
    "requires_approval": false,
    "reason": "Matches blocked pattern: rm -rf /"
  }
  ```
</Accordion>

### `read_audit_log`

Read Rafter audit log entries with optional filtering.

| Parameter    | Type   | Required | Description                                                                              |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------------------- |
| `limit`      | number | No       | Maximum entries to return (default: 20)                                                  |
| `event_type` | string | No       | Filter: `command_intercepted`, `secret_detected`, `content_sanitized`, `policy_override` |
| `since`      | string | No       | ISO 8601 timestamp — only entries after this time                                        |

### `get_config`

Read Rafter configuration (full config or a specific key).

| Parameter | Type   | Required | Description                                                             |
| --------- | ------ | -------- | ----------------------------------------------------------------------- |
| `key`     | string | No       | Dot-path config key (e.g. `agent.commandPolicy`). Omit for full config. |

## Resources

Two read-only resources expose Rafter's current state.

| URI               | Description                                                                    |
| ----------------- | ------------------------------------------------------------------------------ |
| `rafter://config` | Current Rafter configuration (JSON)                                            |
| `rafter://policy` | Active security policy — merged `.rafter.yml` + `~/.rafter/config.json` (JSON) |

## How It Works

The MCP server wraps Rafter's existing CLI classes:

* `scan_secrets` uses `RegexScanner` (built-in 21+ patterns) with automatic fallback from Betterleaks (v0.8.0+; gitleaks successor)
* `evaluate_command` uses `CommandInterceptor` with policy-driven risk assessment
* `read_audit_log` reads from `~/.rafter/audit.jsonl`
* `get_config` reads from `~/.rafter/config.json` merged with `.rafter.yml`

All tools are **read-only**. Configuration changes go through the CLI (`rafter agent config set`).

## Configuration

The MCP server uses the same configuration as all other Rafter commands. Set up your security policy once and it applies everywhere:

```bash theme={null}
# Initialize Rafter (creates ~/.rafter/config.json)
rafter agent init

# Customize policy
rafter agent config set agent.riskLevel moderate
rafter agent config set agent.commandPolicy.mode approve-dangerous
```

Or use a `.rafter.yml` policy file in your project root. See [Policy File](/guides/agent-security/policy-file) for details.

## Verify Installation

After adding Rafter to your MCP client, test that tools are working:

1. Ask the agent to scan a directory for secrets
2. Ask it to evaluate whether `rm -rf /` is safe
3. Ask it to show your Rafter configuration

If the agent can call these tools, Rafter is connected.

## Compared to Pretool Hooks

|              | MCP Server                   | Pretool Hooks                          |
| ------------ | ---------------------------- | -------------------------------------- |
| **Platform** | Any MCP client               | Claude Code only                       |
| **Model**    | Agent calls tools explicitly | Hooks intercept before every tool call |
| **Trust**    | Agent chooses to use tools   | Agent cannot bypass hooks              |
| **Setup**    | Add to MCP config            | `rafter agent init --with-claude-code` |

For maximum security on Claude Code, use **both**: pretool hooks for enforcement + MCP tools for agent-initiated scans. For other platforms, the MCP server is the primary integration path.

## What's Next?

<CardGroup cols={2}>
  <Card title="Secret Scanning" icon="key" href="/guides/agent-security/secret-scanning">
    21+ secret patterns detected
  </Card>

  <Card title="Policy File" icon="file-shield" href="/guides/agent-security/policy-file">
    Define per-project security policies
  </Card>

  <Card title="Command Reference" icon="book" href="/guides/agent-security/reference">
    Full CLI reference
  </Card>
</CardGroup>