MCP & scanners

MCP servers and scanner engines are enabled in Settings, never installed by a pack. This page covers the SDK seams packs can reference; for server setup, see MCP servers. Catalog merge, trust gates, and the error contract are in mcp.md.

Server catalog and tool policy

Three layers merge, project over device over distro:

command: defines a local stdio server; url: defines streamable HTTP. Device entries may use stdio env, or HTTP bearer / headers / OAuth. Project entries are limited to credential-free loopback HTTP — no stdio, no secrets, no non-loopback URLs.

Agent tool registration reads the device catalog. A project-declared server is visible in that project’s Settings and reachable by Test connection; it never becomes a callable host tool.

Typed result bindings

A device-scope pack can ship mcp_bindings/ — a JSON Schema plus field paths that project a tool’s result into typed facts your rules evaluate. Project desired state cannot add, disable, or own mcp_bindings units.

# mcp_bindings/widget.yaml
id: widget
server_id: fixture
tool_name: widget
schema:
  type: object
  required: [status]
  properties:
    status: { type: string }
fields:
  - key: widget_status
    type: string
    path: /status
  - key: is_ready
    type: bool
    path: /status
    equals: ready

when: mcp_schema_matched && mcp_field_bool("is_ready")

Duplicate fact keys across binding units fail closed at validate. Generic MCP facts (mcp_server_enabled, mcp_call_ok, mcp_error_code, …) are always available without a binding.

Scanner integration

Scanners follow the same polarity: enabling and running them is a Settings decision. Packs must not ship scanner engines — they may only declare requires_scanners to gate guidance until the operator enables a named scanner. A project may enable a known scanner by id ({repo}/.paintedwolf/scanners.yaml — id + enabled only) but can’t define one.

See Security scanners for the bundled catalog. Install check: pw scan engines check. Snapshot and watch policy live in scan-supply-chain.md.