controld-blade-mcp

MCP server for Control-D DNS filtering and privacy management. 23 tools covering profiles, filters, services, custom rules, devices, and analytics.

Install

uv sync

Configure

Transport policy. The default stdio transport needs no token. The http transport is a manual loopback path only: the server refuses to start unless CONTROLD_MCP_API_TOKEN is set and CONTROLD_MCP_HOST is loopback (127.0.0.1/::1/localhost). Control-D tools mutate DNS-filtering policy — never expose this surface unauthenticated or on a public interface.

Usage

Claude Code

{
  "mcpServers": {
    "controld": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/controld-blade-mcp", "controld-blade-mcp"],
      "env": {
        "CONTROLD_API_KEY": "your-api-key"
      }
    }
  }
}

Stallari

Automatically configured via the pack system. See stallari-plugin.yaml.

Tools (23)

Read (12)

Write (11, gated)

Development

make install-dev    # Install with dev dependencies
make test           # Run unit tests
make check          # Lint + format check + type check
make test-cov       # Tests with coverage

Token Efficiency

Responses use compact pipe-delimited format. Typical costs:

Conformance & hardening (DD-385)

• Audit surface (CONV-29 / S-AUD-001). Every tool appends a canonical _meta: {...} JSON tail on the success path via stallari-mcp-helpers (append_meta/meta_envelope). Write tools carry target_id + rows_affected. Gate / confirm / error returns stay plain (no tail). All 23 tools verify match under stallari-mcp-lint --strict.
• Risk class (DD-280). The catalog entry declares per-tool risk_class: 12 read_only, 9 external_side_effect, 2 high_risk (cd_rule_delete, cd_access_update — both write+confirm).
• Transport (DD-242). http transport is bearer-mandatory + loopback-only (see Transport policy above); stdio is the default.
• Readiness: production — live-hardening certification PASSED (v0.4.0). The DD-385 live-capture audit ran against a real Control-D account and fixed 12 wire-fidelity defects a 100%-green mocked suite passed straight through — every formatter read keys the API doesn't emit (stats.rules vs profile.rule.count, flat do vs action.do, top-level filter status vs per-levels[], device_type vs icon, …); cd_rules 400'd on every default call (/rules/0); update_service silently no-op'd without a required status field; format_write_result crashed on the bare-list delete response; spoof/redirect rules rendered without their target (via nests under action.via for rules, unlock_location for services). The mocks now encode the captured wire shapes, and all read + write paths are live-verified (incl. cd_access_update on a throwaway device, spoof→IP / redirect→location rules, and the profile options render). 13 defects fixed.

Licence

MIT