controlloop MCP server

Know what your agents can do. Before they do it.

ControlLoop is a local-first scanner and deterministic CI gate for what your AI agents can actually do. It reads the files that define an agent, builds one graph of its capabilities, compares it to the state you approved, and fails the build when the agent's authority grows past the ceiling you declared. It never runs your code and never sends your source anywhere.

Watch: the gate in a minute · Read: the example walkthrough

Try it in 30 seconds

No install and no account: with uv on your machine, uvx runs the CLI straight from PyPI. Point it at the public reference agent, on a branch where a pull request adds a Claude Code SessionStart hook:

git clone -b scenario/session-start-harvester-hook https://github.com/controlloop-security/controlloop-reference-agent
cd controlloop-reference-agent
uvx controlloop gate scenarios/storefront-agent-config

! WORST REACHABLE  code-execution: Claude Code can invoke PostToolUse command
  hook (Edit|Write)

✕ DEPLOYMENT BLOCKED

Authority:
  • This change gives Claude Code the power to run `node .github/setup.js` on
    every session start (`.claude/settings.json`, hook `SessionStart`). No
    approval is recorded.

• GAINED  code-execution: Claude Code invokes SessionStart command hook

✕ HIGH     policy.agent-hook-command-change: Added: Hook on event 'SessionStart'
  for host 'Claude Code' runs `node .github/setup.js`.
    at .claude/settings.json

Suppressions: none declared

Completeness enforcement: warn (default)
Evidence: evidence.json

Exit code 1. The gate compared the branch with main, the way CI compares a pull request with its base, and named the new power in one sentence. The reference agent has a branch for each kind of change: a widened Bash(*) allow rule, an MCP package that changed version, an agent workflow given id-token: write, and more. To gate your own pull requests, add the GitHub Action.

ControlLoop CLI

An agent's real authority is spread across an agent card, an MCP config, an OpenAPI spec, an IAM policy, and, for most agents, the framework code itself: a CrewAI crew, a LangGraph graph, an OpenAI Agents SDK handoff chain. The same goes for the coding agents that work on your repository. Claude Code, Codex, Gemini CLI, Cursor, Kiro, Roo Code, and Cline are configured by committed files, and so are the workflows that run an agent in CI. So is the repository's own development environment: a dev container feature, a pre-commit hook, or an editor startup file runs code the moment someone opens the repository or commits to it. No single file tells you that one pull request just gave an agent the ability to move money, or to run a script on every session start.

How it works. ControlLoop walks the repository and reads only committed files. Adapters turn them into an Agent Capability Bill of Materials (ACBOM): agents, tools, resources, identities, and permissions, with evidence for every node and edge. The graph is diffed against the baseline you approved, classified by a material capability taxonomy, judged by 24 policy rules and the capability ceiling you declared, and the verdict is written to an evidence artifact. No model decides anything; the same inputs always produce the same verdict. Secrets, prompts, environment values, and file contents never reach the output.

Development preview. init, bom, diff, scan, gate, rules, and example work and are covered by tests. Every tagged release is published to PyPI, the Homebrew tap, the container registry, and GitHub Releases as standalone binaries.

Features

What it reads

• 🗂️ A2A agent cards, MCP server declarations for eleven agent hosts, OpenAPI documents, and AWS IAM policies in JSON or Terraform. See the adapter table.
• 🧩 Framework code, parsed and never imported: CrewAI, LangGraph, and the OpenAI Agents SDK. A tool it cannot resolve is reported as the worst reachable capability, never dropped.
• 🤖 Coding agents' own configuration: Claude Code settings, hooks, skills, subagents, plugins and marketplaces; Codex; Gemini CLI; Cursor; Kiro; Roo Code and Cline through their MCP configuration; and the GitHub workflows that run an agent.
• 🧰 Clone-time protection: what runs when a repository is opened or committed to. Dev container features, extensions and lifecycle commands, and VS Code extension recommendations; pre-commit hook repositories, their dependencies, and local hooks; editor startup files (.nvim.lua, .exrc, .dir-locals.el) and JetBrains required plugins. Recorded as written: nothing is installed, pulled, or run. Examples.

What it tells you

• 🎯 The blast radius, first. Every report opens with the single worst thing the agent can do right now: ! WORST REACHABLE financial-action: … can invoke Issue a refund. Material capability taxonomy.
• 🗣️ A plain-language authority statement for every change to an agent's configuration: This change gives Claude Code the power to run node .github/setup.js on every session start. Authority statement.
• 🔀 A capability diff, not a file diff: what became newly reachable against the baseline you approved, by class. Capability diff.
• 📏 A capability ceiling that blocks authority nobody anticipated, through routes no rule matches, and cannot be suppressed. Capability ceiling.
• 📚 24 policy rules with a plain message, a remediation, and a stable documentation link on every finding. Policy rules.
• 🧾 An evidence artifact on every gate run, including the failing ones, plus JSON and SARIF 2.1.0 output. Evidence artifact format.

How it behaves

• 🔒 Local and offline. Core scanning works with the network disabled. Nothing is executed: no MCP server is started, no endpoint is contacted. Privacy, security, and limitations.
• 🧮 Deterministic. Same inputs, same pinned versions, same digest, same verdict. Unknown is ranked worse than known, never safer.
• 🙈 Nothing protected leaves. Source, prompts, credentials, environment values, and customer data never appear in output, logs, errors, identity material, or artifacts.
• ⚙️ CI-native. A GitHub Action and a pre-commit hook run the same gate.
• 🤖 Callable from your agent. controlloop mcp serves gate, diff, bom and rules as read-only tools to any MCP host over stdio, with no network and no writes. The local MCP server.

Note: the agent hosts whose project configuration is read are Claude Code, Codex, Gemini CLI, Cursor, and Kiro, each pinned to its documentation as read on a stated date (controlloop --version prints it). MCP declarations are also read from VS Code, Roo Code, Cline, Continue, Windsurf, and opencode.

Quick start

Installation

Install the CLI from PyPI with uv:

uv tool install controlloop
controlloop --version

pipx install controlloop works too. To run it once without installing, use uvx controlloop. With Homebrew, on macOS (Apple Silicon) or Linux:

brew install controlloop-security/controlloop/controlloop

Without Python, the shell installer downloads and verifies the standalone binary for your machine:

curl -fsSL https://raw.githubusercontent.com/controlloop-security/controlloop/main/install.sh | bash

In a container, with no network:

docker run --rm --network none -v "$PWD:/work:ro" \
  ghcr.io/controlloop-security/controlloop:0.7.1 scan /work

Every install path, with its verification step, is in Installation. To run from source instead:

git clone https://github.com/controlloop-security/controlloop
cd controlloop
uv sync --locked --all-groups
uv run controlloop --version

ControlLoop 0.7.1
Supported OASF versions: none yet
Agent host key sets (documentation read on): claude-code 2026-10-17, codex 2026-10-17, cursor 2026-10-17, gemini-cli 2026-10-17, kiro 2026-10-17, roo-code 2026-10-29
Rule pack: controlloop-community 0.9.0 (24 rules)

Requirements

• Python 3.12 for the PyPI package; uv installs it for you. Homebrew, the shell installer, and the container need no Python.
• Git, for the automatic merge-base baseline that diff and gate use
• macOS or Linux. Windows is unsupported.

First run

Point it at a repository containing an agent:

controlloop scan /path/to/your/agent-repo

Nothing to try it on? The public reference agent is a realistic, deliberately imperfect agent built for exactly this:

git clone https://github.com/controlloop-security/controlloop-reference-agent
controlloop scan controlloop-reference-agent/scenarios/order-support-agent

! WORST REACHABLE  financial-action: widgetworks-order-support-agent can invoke
  Issue a refund

✓ PASSED

• material change: not evaluated

! MEDIUM   policy.undeclared-tools: Tool 'Look up an order' is reachable but not
  declared in controlloop.yaml.
    at agent-card.json

! MEDIUM   policy.undeclared-tools: Tool 'Reply to customer' is reachable but
  not declared in controlloop.yaml.
    at agent-card.json

! MEDIUM   policy.undeclared-tools: Tool 'Issue a refund' is reachable but not
  declared in controlloop.yaml.
    at agent-card.json

Suppressions: none declared

Exit code 0. New here? controlloop example prints a six-step walkthrough that matches the example walkthrough guide.

The commands

Command	Use it to
scan	Full report for a human: blast radius, verdict, changes, findings
gate	The same analysis for CI: one verdict, one exit code, an evidence artifact every time
diff	See what changed against a baseline, as capabilities rather than files
bom	Generate or validate the capability graph (ACBOM), natively or as CycloneDX
init	Draft a controlloop.yaml from what is actually in the repository
rules	List the rule pack in use and what each rule looks for
example	Print a guided walkthrough

scan is what you run at your desk. gate is what you run in CI. Every command and flag is in the CLI reference.

Use it inside your agent

The ControlLoop plugins let a coding agent run this CLI and explain its answer when you ask "what does this change let my agents do?" They run the gate locally, quote its verdict and authority statements, link each finding's documentation, and edit nothing. They ship no hooks and start nothing when a session opens.

Host	Install
Claude Code	/plugin install controlloop --marketplace controlloop-security/controlloop-plugins, then /controlloop:review
Codex	codex plugin marketplace add controlloop-security/controlloop-plugins, then codex plugin add controlloop@controlloop
Gemini CLI	gemini extensions install https://github.com/controlloop-security/controlloop-plugins
Cursor	From the Cursor Marketplace, or import the repository as a team marketplace
GitHub Copilot	copilot plugin install controlloop@controlloop after copilot plugin marketplace add controlloop-security/controlloop-plugins; in VS Code, Chat: Install Plugin from Source
Any MCP host	controlloop mcp: gate, diff, bom and rules as read-only local tools

Screenshots

Every block in this README is real output, recorded with the version above against the public reference agent or, for the Clone-time protection examples, a two-commit repository holding only the file shown. Nothing is staged.

A pull request adds a tool the agent's ceiling prohibits. The blast radius got worse, the ceiling breach blocks, and the evidence artifact is written:

! WORST REACHABLE  financial-action: widgetworks-order-support-agent can invoke
  Issue a refund

✕ DEPLOYMENT BLOCKED

• GAINED  financial-action: widgetworks-order-support-agent invokes
  customer-payment-methods
• GAINED  sensitive-data-access: widgetworks-order-support-agent invokes
  customer-payment-methods
• GAINED  write-access: widgetworks-order-support-agent invokes
  customer-payment-methods

✕ CRITICAL policy.capability-ceiling: agent 'widgetworks-order-support-agent'
  reaches 'customer-payment-methods', which is a prohibited resource or external
  destination under its capability ceiling
    at agent-card.json

controlloop gate on scenarios/order-support-agent with a branch that adds customer-payment-methods. Exit code 1.

A pull request adds a Claude Code hook. The gate says what that lets the agent do before anything else:

✕ DEPLOYMENT BLOCKED

Authority:
  • This change gives Claude Code the power to run `node .github/setup.js` on
    every session start (`.claude/settings.json`, hook `SessionStart`). No
    approval is recorded.

• GAINED  code-execution: Claude Code invokes SessionStart command hook

✕ HIGH     policy.agent-hook-command-change: Added: Hook on event 'SessionStart'
  for host 'Claude Code' runs `node .github/setup.js`.
    at .claude/settings.json

controlloop gate on scenarios/storefront-agent-config, branch scenario/session-start-harvester-hook. Exit code 1. The GitHub Action posts the same statement as one pull-request comment.

Examples

The common uses, each with the real command and its real output.

Scan a repository

controlloop scan .

The report above: blast radius first, then the verdict, the material change against the baseline, every finding with its rule and evidence path, and the suppressions in force. How to read each line is in Terminal report format.

See what a pull request changed

controlloop diff . --baseline main

CONTROLLOOP / CAPABILITY DIFF

• BASELINE   explicit git revision: revision main (4c258dc876245856f97786c05f51157ee68e8e25)
• SCOPE      full -- nodes, edges, and effective authority

• ADDED    node        clp:tool:sha256:ccc68b72…  customer-payment-methods
• ADDED    edge        clp:edge:sha256:0234aa41…
• ADDED    capability  clp:agent:sha256:2321fe51…  invokes  clp:tool:sha256:ccc68b72…

3 changes: 3 added

Without --baseline, diff uses the committed .controlloop/baseline.json if there is one, else the merge-base with your default branch. diff <baseline.json> <current.json> compares two ACBOM files directly.

Gate in CI, with evidence

controlloop gate . --default-branch main \
  --evidence-path evidence.json --sarif-path controlloop.sarif

gate returns one of four verdicts and always writes the evidence artifact, including on a failing run, which is exactly when you need it:

Verdict	Exit	Meaning
✓ PASSED	0	Nothing blocking, nothing warned
! PASSED WITH WARNINGS	0	Findings below the blocking threshold
! REVIEW REQUIRED	3	A human must look: analysis was incomplete under strict enforcement, or (Team) a grant is not on the approved list
✕ DEPLOYMENT BLOCKED	1	A blocking finding

gate needs real git history for an automatic baseline, so check out with fetch-depth: 0. The full exit-code table is at the end of this file.

Catch a change to a coding agent's configuration

The second screenshot above. Any change to .claude/settings.json, .mcp.json, .codex/config.toml, .gemini/settings.json, .cursor/hooks.json, .kiro/, a plugin, a skill, a subagent, or a workflow that runs an agent produces an authority statement. Same name, different package? That is a changed grant too:

This change gives Claude Code the power to start MCP server `catalog-docs` by
running `npx -y @widgetworks-example/catalog-docs-mcp@1.5.0`, whose declaration
or tool list changed (`.mcp.json`, server `catalog-docs`). No approval is
recorded.

From scenario/mcp-package-drift, where catalog-docs moves from 1.4.2 to 1.5.0 under the same name. The limits of what the scanner can and cannot see are in Agent authority limits.

Clone-time protection

A repository's development environment runs code on the machine of whoever works in it: a dev container installs its features and runs its lifecycle commands when the container is built, pre-commit runs its hooks on every commit, and an editor can run a project startup file when the folder is opened. ControlLoop reads those files, records each entry as written, and reports a new or changed one, and one with no exact version or digest pin, through the same rules as a coding agent's configuration. Each example below is a branch that changes one file against main, gated with controlloop gate . --default-branch main.

A dev container gains a feature on a floating tag and a postCreateCommand:

"features": {
  "ghcr.io/acme-tools/features/setup:latest": {}
},
"postCreateCommand": "bash .devcontainer/setup.sh"

! WORST REACHABLE  unclassified: Dev Containers can invoke devcontainer feature
  ghcr.io/acme-tools/features/setup

✕ DEPLOYMENT BLOCKED

Authority:
  • This change gives Dev Containers the power to install plugin `devcontainer
    feature ghcr.io/acme-tools/features/setup`, unpinned
    (`.devcontainer/devcontainer.json`, plugin `devcontainer feature
    ghcr.io/acme-tools/features/setup`). No approval is recorded.
  • This change gives Dev Containers the power to run `bash
    .devcontainer/setup.sh` through the `postCreateCommand` setting
    (`.devcontainer/devcontainer.json`, setting `postCreateCommand`). No
    approval is recorded.

• GAINED  code-execution: Dev Containers invokes postCreateCommand command
• GAINED  unclassified: Dev Containers invokes devcontainer feature
  ghcr.io/acme-tools/features/setup

! MEDIUM   policy.unpinned-agent-component: Added: Devcontainer feature
  ghcr.io/acme-tools/features/setup (devcontainer-feature) has no commit or
  digest pin.
    at .devcontainer/devcontainer.json

✕ HIGH     policy.agent-hook-command-change: Added: Setting 'postCreateCommand'
  for host 'Dev Containers' runs `bash .devcontainer/setup.sh`.
    at .devcontainer/devcontainer.json

Suppressions: none declared

Completeness enforcement: warn (default)
Evidence: evidence.json

A pre-commit hook repository moves from a commit SHA to a tag (rev: 25.1.0). An unpinned component is a medium finding, reported but not blocking:

! WORST REACHABLE  unclassified: pre-commit can invoke pre-commit hook
  repository github.com/psf/black

✓ PASSED

Authority:
  • This change gives pre-commit the power to install plugin `pre-commit hook
    repository github.com/psf/black`, unpinned, whose source changed
    (`.pre-commit-config.yaml`, plugin `pre-commit hook repository
    github.com/psf/black`). No approval is recorded.

• no material capability change

! MEDIUM   policy.unpinned-agent-component: Pre-commit hook repository
  github.com/psf/black changed its ref, pinned. Pre-commit hook repository
  github.com/psf/black (pre-commit-hook) has no commit or digest pin.
    at .pre-commit-config.yaml

Suppressions: none declared

Completeness enforcement: warn (default)
Evidence: evidence.json

A Neovim project startup file is added. The file is recorded by path and SHA-256 and never parsed, so a later change to its content is reported by policy.hook-script-changed:

! WORST REACHABLE  code-execution: Neovim can invoke .nvim.lua command

✕ DEPLOYMENT BLOCKED

Authority:
  • This change gives Neovim the power to run `.nvim.lua` through the
    `.nvim.lua` setting (`.nvim.lua`, setting `.nvim.lua`). No approval is
    recorded.

• GAINED  code-execution: Neovim invokes .nvim.lua command

✕ HIGH     policy.agent-hook-command-change: Added: Setting '.nvim.lua' for host
  'Neovim' runs `.nvim.lua`.
    at .nvim.lua

Suppressions: none declared

Completeness enforcement: warn (default)
Evidence: evidence.json

A JetBrains project requires a plugin with a minimum version and no maximum (.idea/externalDependencies.xml):

• no material capability is reachable

✓ PASSED

Authority:
  • This change gives JetBrains IDEs the power to install plugin `editor plugin
    com.acme.ide-helper`, unpinned (`.idea/externalDependencies.xml`, plugin
    `editor plugin com.acme.ide-helper`). No approval is recorded.

• no material capability change

! MEDIUM   policy.unpinned-agent-component: Added: Editor plugin
  com.acme.ide-helper (editor-extension) has no commit or digest pin.
    at .idea/externalDependencies.xml

Suppressions: none declared

Completeness enforcement: warn (default)
Evidence: evidence.json

What each file contributes, and where each adapter stops, is in Dev containers and VS Code extensions, pre-commit, and Editor startup files and JetBrains required plugins.