Agent Canary MCP
An agent safety toolkit: an MCP server and SDK with decoy tools, canary tokens and a gateway that blocks unwanted actions.
- 103 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The gateway lets through reads and calls that pass policy and a GitHub token with package read access is needed to install.
Install
- Works in
Manual install
npm config set @dorianchn:registry https://npm.pkg.github.comThen npm login --scope=@dorianchn with a read:packages token and npm install --global @dorianchn/agent-canary@3.0.0. Docker image: ghcr.io/dorianchn/shanchuanzhi-agent-canary:3.0.0.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The gateway lets through reads and calls that pass policy and a GitHub token with package read access is needed to install.
This is third-party code. Review the repository files before installing.
What it does
Agent Canary 3.0 is an open-source safety toolkit for agents delivered as an MCP server and SDK. It includes decoy tools, canary tokens, a trusted execution gateway, local self-tests and an optional policy console. The server starts with `agent-canary serve --stdio` and in code the gateway is created with `createTrustedExecutionGateway`. The host registers the callbacks it wants protected and the gateway decides whether to allow each one: reads pass and writes outside policy are denied. In a check with a local Qwen model across 48 trials, direct forbidden effects happened in 12 of 12 cases without protection and 0 of 12 with it. There is a plugin for the Cline SDK and a fail-closed adapter for the Filesystem MCP server. Protection covers only callbacks routed through this server.
Who it is for. Agent developers who want to limit side effects of tool calls and catch decoy triggers.
Good fit when
- An agent gets file access and a gateway must deny writes outside the allowed area.
- You need decoy tools and tokens to notice an attempted hijack or theft.
- An embedded agent on the Cline SDK needs a check layer before every tool call.
- Before launch you want to run local self-tests on synthetic files.
Not a fit when
- You need OS-level isolation: protection works as application-level routing.
- The client's direct tools stay available: the gateway does not intercept them.
- You need independent confirmation: reproduction by a third party has not been done yet.
Example request
Read a file through the protected tool, then try writing outside the allowed folder and show the gateway decision.MCP
- Transport
- stdio
- Authentication
- not required
Limitations
Only callbacks the host registered and routed through the server are protected: the client's own tools and outside processes are not controlled by the gateway. This is application-level routing, not OS-level confinement. The author does not claim zero false positives or no time-of-check races, and reproduction by an independent operator is marked blocked. Node.js 20 is required. The npm package lives in GitHub Packages, which needs a token with `read:packages`, and the Docker image is available from GitHub Container Registry. The Cline integration was verified only on the pinned SDK plugin.
How to disable. Remove the `agent-canary` entry from client config and the package with `npm uninstall --global @dorianchn/agent-canary`. The GitHub token used for reading packages can be revoked.
FAQ
How do I install Agent Canary?
Configure the `@dorianchn` registry on GitHub Packages, log in with a token with `read:packages` and run `npm install --global @dorianchn/agent-canary@3.0.0`. Then check `agent-canary --help`.
How do I run the MCP server?
With `agent-canary serve --stdio` or through the container with the `-i` flag and the same arguments.
How does the gateway decide what to allow?
The host registers the callbacks to protect and the gateway lets reads through and denies writes outside policy.
Can I build without logging in to GitHub Packages?
Yes, from a pinned source snapshot. The steps are in `GETTING_STARTED.md`.
Which integrations exist?
A Cline SDK plugin and a fail-closed adapter for the Filesystem MCP server. The Cline Agent Runtime route was verified.
Discussion
No questions or reviews yet.
Related
MCP serversA CLI that scans your machine for skills and MCP configs, finds poisoned tool descriptions and runs a system prompt through 225 attacks
A gateway for MCP servers with plugins for masking known secret patterns in text responses, reputation checks and call logging
AgentShield audits the .claude folder for plaintext keys, broad permissions, dangerous hooks and risky MCP servers and grades the setup from A to F
An MCP memory server for agents plus a free gate that stops dangerous commands before they run
A policy gateway for AI agents: it checks tool calls before they run, holds risky ones for approval and writes an audit trail
A CLI for auditing agent MCP servers: inventory, evidence per server and a CI policy where unmeasured never counts as clean
README in short
The page covers installing from GitHub Packages and Docker, SDK use, the Cline integration and validation results. It states the limits explicitly: what is protected and what the checks do not prove.