MCP Server

Governance & Security

fai applies a 6-layer governance chain to every MCP tool call. Most layers are active with no configuration — secure by default.

---

Tool Exposure (Layer 1)

Control which tools MCP clients can discover and call. Hidden tools never appear in tools/list and return a protocol error if called directly.

Add to ~/.fai/config.json:

{
  "MCP": {
    "ExposedTools": "all",
    "HiddenTools": ["fai_agent_run", "fai_agent_apply"]
  }
}

HiddenTools always takes precedence. Set ExposedTools to an array to create an explicit allowlist.

---

Rate Limiting (Layer 2)

Token bucket limiter — 100 req/min with 20-request burst by default. Exceeded requests get a retry message, not a silent drop.

{
  "MCP": {
    "RateLimit": {
      "RequestsPerMinute": 60,
      "BurstAllowance": 10,
      "PerClientTracking": false
    }
  }
}

---

Authentication (Layer 3)

Disabled by default. Enable when using fai --share or any public-facing deployment.

Environment variable (stdio clients — set in MCP client config):

{
  "mcpServers": {
    "fai": {
      "command": "fai",
      "args": ["--mcp=stdio"],
      "env": { "FAI_MCP_API_KEY": "fai_your_key_here" }
    }
  }
}

HTTP clients send Authorization: Bearer <key>.

OAuth 2.1 support (scope-per-client) is coming in a future release.

---

Scope Tiers (Layer 4)

Scope	Grants
session:read	Orientation, workspace reads, agent list, docs
session:write	All read + session capture tools
session:agent	All write + agent coordination tools
session:admin	All tools

Currently, all authenticated callers receive full scope. Per-client scope enforcement via OAuth 2.1 is planned.

---

Audit Log (Layer 5)

Every tool call writes one entry to ~/.fai/mcp-audit.jsonl.

{
  "Timestamp": "2026-03-27T12:00:00.000Z",
  "CorrelationId": "uuid",
  "Tool": "fai_guide",
  "ParamsHash": "sha256-hex",
  "Status": "success",
  "LatencyMs": 42
}

Params are never logged — only a SHA-256 hash. Status is one of: success · error · rate_limited · unauthorized · denied.

---

Data Filter (Layer 6)

Automatically redacts secrets from tool results before they reach the AI client.

Built-in: Bearer tokens · OpenAI keys (sk-) · fai keys (fai_) · GitHub tokens (ghp_) · private keys · passwords.

Add custom patterns:

{
  "MCP": {
    "DataFilter": {
      "Enabled": true,
      "CustomPatterns": ["CORP_SECRET_[A-Z0-9]{32}"]
    }
  }
}

---

Resilience

Circuit Breaker → Retry (3 attempts) → Timeout (60s) wraps every tool call. The circuit opens after 3 consecutive failures and probes again after 30 seconds.

---

What's Next

• MCP server — transport modes, tools, resources, prompts
• Getting started — first fai session