Skip to content

Wire the MCP server into a coding agent

You will register GuardLink’s MCP server with a coding agent, verify over the wire that it exposes 28 tools and 3 resources, and confirm the answers it returns are about your repository rather than whatever directory it started in.

An agent editing an annotated file otherwise infers security context from the source. The model already records what a human decided: which risks were accepted, which controls are load-bearing, and which asset a function belongs to. None of that is derivable from the code.

  • GuardLink installed. See Install GuardLink.
  • A project with guardlink init run in it, and some annotations. The annotate guide builds one.
  • An MCP client. Claude Code discovers the config guardlink writes; others need a line of JSON.

guardlink init already wrote .mcp.json at the project root:

.mcp.json
{
"mcpServers": {
"guardlink": {
"command": "guardlink",
"args": ["mcp"]
}
}
}

Claude Code picks that up and asks before using it:

Terminal window
claude mcp list
guardlink: guardlink mcp - ⏸ Pending approval (run `claude` to approve)

guardlink-mcp and guardlink mcp are the same server, with the same startStdioServer(), the same tools. Use whichever your client’s config style prefers. For a client that does not auto-discover .mcp.json, the whole configuration is:

{"mcpServers": {"guardlink": {"command": "guardlink-mcp"}}}

Before involving an agent, check the server answers on its own. It speaks JSON-RPC on stdin and stdout, so you can drive it from a shell:

Terminal window
{
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'
echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
sleep 2
} | npx guardlink-mcp

The initialize response identifies the server:

{"serverInfo":{"name":"guardlink","version":"2.4.0"}}

and tools/list returns 28. Their names, in the order the server lists them:

guardlink_parse, guardlink_status, guardlink_validate, guardlink_suggest,
guardlink_worklist, guardlink_reach, guardlink_lookup, guardlink_context,
guardlink_graph, guardlink_annotate_apply, guardlink_reanchor,
guardlink_threat_report, guardlink_annotate, guardlink_report,
guardlink_dashboard, guardlink_sarif, guardlink_diff, guardlink_paths,
guardlink_threat_reports, guardlink_sync, guardlink_clear,
guardlink_unannotated, guardlink_review_list, guardlink_review_accept,
guardlink_entitlement_propose, guardlink_entitlement_list, guardlink_blame,
guardlink_workspace_info

guardlink_worklist and guardlink_reach are new in 2.2.0 and read a code graph, not the model. With codegraph-mcp or bravos graph installed and the repository indexed, the worklist ranks route handlers by the sink classes they reach and says whether the model already covers each one, and guardlink_reach answers which sinks one function reaches. Without a usable graph they return an empty list and a code_graph.status saying why. GuardLink never installs or builds a graph.

plus three resources: guardlink://model, guardlink://definitions, and guardlink://unmitigated. Every one of them, with its input schema, is in the MCP tool reference.

guardlink-mcp --help and --version print and exit before any transport is connected, which is why they are safe on a server whose stdout is the protocol channel. With no flag it serves and blocks on stdin, so an apparently hung process is the server working.

This is the failure that wastes the most time, and it is invisible unless you look for it.

The server resolves root per tool call. Omit it, and the root is the process’s working directory, whatever your MCP client happened to launch the server in. Every tool result carries a second content block naming what it used:

{
"guardlink": {
"annotation_hash": "sha256-v3:17a41e0fbbb02cb53129f74437e92fb4b13914c2f8c117942e2781964e2c7afc",
"git_sha": "21f7e97729bf21b2a20e2334a8fd39c628b5be9b",
"generated_at": "2026-10-08T06:26:41.418Z",
"mode": "external",
"root": "/path/to/legacy-api",
"guardlink_version": "2.2.0"
}
}

Started one directory too high, the same call still succeeds. It parses everything below that directory and reports a model assembled from unrelated projects:

{
"guardlink": {
"annotation_hash": "sha256-v3:6ec16dea4e7389005a2cb576eb95f67574fa3811ae2459c8d001c5d23c05bccd",
"git_sha": null,
"generated_at": "2026-10-08T06:26:54.802Z",
"mode": "mixed",
"root": "/path/to/the/parent/directory",
"guardlink_version": "2.2.0"
}
}

Both blocks were captured on 2.2.0. A 2.4.0 server returns the same six fields.

Measured with legacy-api beside an inline-mode project in the same parent directory: assets: 3 became assets: 5, and the unmitigated list gained two exposures from the other project. Nothing errored. The three tells are root, git_sha: null where you expected a commit, and mode: "mixed" where the project has one annotation mode.

Ask for guardlink_status first in a new session and read the root line before trusting anything else.

Twenty-eight is more than anyone memorises. These six carry most sessions.

Tool Ask it when
guardlink_context(file) You opened or are about to edit a file. Everything known about that one file.
guardlink_status() Cold start on an unfamiliar repository. Counts, plus the unmitigated list.
guardlink_graph(from, depth, direction) You are about to change a shared component and need blast radius.
guardlink_lookup(query) You have one specific question.
guardlink_validate() Before finishing a change.
guardlink_diff(ref) After a change: did this make the model worse?
Section titled “guardlink_context distinguishes kinds of empty”
{
"file": "test/users.test.js",
"status": "not_scanned",
"annotation_source": null,
"origin_files": [],
"counts": {},
"annotations": [],
"assets": [],
"open_exposures": [],
"hint": "`test/users.test.js` exists but is not in the parser's scan set — it is under an excluded directory (node_modules, dist, build, test, tests, __tests__, vendor, target, .bravos, .bugb). Its annotations, if any, were never read."
}

annotated, scanned_without_annotations, not_scanned, not_found. The second means genuinely clean; the third means nobody looked. An agent that treats them alike will report a test directory as having no security concerns.

guardlink_graph with from: "#api", depth: 2, direction: "out":

{
"traversal": {
"start": {
"ref": "#api",
"canonical": "api",
"resolved": true,
"matched_via": "exact",
"matched_against": "api"
},
"nodes": [
{
"key": "api",
"depth": 0,
"declared": true
},
{
"key": "tokens",
"depth": 1,
"declared": true
},
{
"key": "users",
"depth": 1,
"declared": true
}
],
"edges": [
{
"kind": "flow",
"from": "api",
"to": "users",
"directed": true,
"label": "GET./api/users",
"at": "src/routes.js:4"
},
{
"kind": "flow",
"from": "api",
"to": "tokens",
"directed": true,
"label": "POST./api/refresh",
"at": "src/routes.js:8"
}
],
"depth_reached": 1,
"depth_requested": 2,
"completeness": "complete"
},

Truncated after traversal. The response continues with the narrowed model under model. depth_reached below depth_requested with completeness: "complete" means the graph ran out, not that the traversal was cut short.

It understands a fixed set of named forms and returns the whole list rather than inventing an answer for anything else:

{
"query": "what is broken",
"type": "no_match",
"count": 0,
"results": [
{
"hint": "Unrecognised query form: `what is broken`. This is not a supported form, so no result was guessed.",
"supported_forms": [
"unmitigated",
"confirmed",
"features",
"asset <id>",
"threat <id>",
"control <id>",

Truncated after the sixth form. The real list runs to 32, among them the reach forms 2.2.0 added: reaches, agents, unentitled reaches, effects, gates and ungated effects, each with an optional for <actor|asset>. Send a deliberately bad query to see all of them. guardlink lookup <query> answers the same forms from a shell.

Anything that resolves a reference reports matched_via: exact, alias, or substring. A substring match is a suggestion, not an identification, and ambiguous with a candidates list means several records tied.

guardlink_annotate_apply writes a validated @source block into the sidecar rather than having the agent edit .gal text. Pass the source file, the line the block anchors to, and the raw annotation lines:

{
"file": "src/db.js",
"line": 1,
"symbol": "query",
"dry_run": true,
"annotations": ["@audit #users -- \"All SQL passes through here\""]
}
{
"ok": true,
"galPath": ".guardlink/annotations/src/db.js.gal",
"status": "written",
"diff": "--- .guardlink/annotations/src/db.js.gal\n+++ .guardlink/annotations/src/db.js.gal\n+@source file:src/db.js line:1 symbol:query\n+@audit #users -- \"All SQL passes through here\"",
"errors": [],
"linesWritten": 2
}

Four things about that call.

  • Do not pass @source yourself. The header is synthesised from file, line and symbol. Passing one is an error.
  • Pass symbol. It is what lets guardlink reanchor find the block after a refactor moves the code. Omitting it also means “this is about the asset, not one function”.
  • dry_run: true returns the diff without writing. status: "written" in a dry run describes what would happen.
  • Every line is re-parsed before anything reaches disk, so a syntax error is rejected with its reason. So is a #id that .guardlink/definitions.* does not declare: the same call with #dbstore comes back "status": "rejected" with Undeclared reference(s): #dbstore. Re-send with allow_undeclared_refs: true to write it with a warning when the definition is coming.

It accepts the reach verbs, @agents, @reaches, @effects and @gates, since those record what the code does and an agent can observe it. It refuses @accepts and @entitles:

{
"ok": false,
"galPath": ".guardlink/annotations/src/db.js.gal",
"status": "rejected",
"diff": "",
"errors": [
"Line 1: refusing to write `@accepts`. Accepting a risk is a human governance decision. Record the risk with @exposes and flag it with @audit instead."
],
"linesWritten": 0
}

Both are human governance decisions: accepting a risk, and confirming an actor is legitimately entitled to a capability. There is deliberately no guardlink_entitlement_accept. An agent can file a proposal with guardlink_entitlement_propose, and only guardlink entitle at a terminal records the acceptance, under the name of the human who made it.

The MCP server is one of two channels. The other is the instruction files init wrote, such as CLAUDE.md, AGENTS.md, .cursor/rules/guardlink.mdc, .windsurfrules, .clinerules, .github/copilot-instructions.md and .gemini/GEMINI.md, which an agent reads before it calls anything.

Since 2.4.0 the GuardLink block in those files is a short pointer, not a copy of the model: whether a model exists, where annotations go, which decisions belong to a person, where to ask, and what to check before a pull request. The live answers come from the MCP tools. The block carries a stamp of the model it was written from:

<!-- guardlink:stamp annotation_hash=sha256-v3:8bed94a125e3e3ed533cd5acd7936a1e985e7e3c886fbf4a0f06c30994308278 agent_config_hash=sha256-v1:1047e9aa807f3fba476fa38095f693f17aeca1bfa9aaff6fab61c452047a2845 -->

When the annotations or the agent configuration change, guardlink validate . warns that the stamp is stale and names the fix. Run it:

Terminal window
npx guardlink sync .
✓ Updated 2 agent instruction file(s):
.guardlink/README.md
CLAUDE.md
Skipped: .cursor/rules/guardlink.mdc (absent — sync writes only into instruction files that exist), AGENTS.md (absent — sync writes only into instruction files that exist), .github/copilot-instructions.md (absent — sync writes only into instruction files that exist), .windsurfrules (absent — sync writes only into instruction files that exist), .clinerules (absent — sync writes only into instruction files that exist), .gemini/GEMINI.md (absent — sync writes only into instruction files that exist)
✓ Every block is stamped with this model (annotation_hash and agent_config_hash);
guardlink validate warns when one goes stale. Agents read the live model through
guardlink_lookup and guardlink_context, so the block itself carries no copy of it.

That transcript is from the quickstart project, which init set up with --agent claude alone. sync writes only into instruction files that exist, and replaces only the text between GuardLink’s markers, so anything another tool or a person wrote around the block survives.

.guardlink/README.md gets the same treatment, and records the hash so a reader can tell whether it is current:

Current model: 6 annotations · 1 assets · 1 threats · 1 controls · 1 exposures · 0 flows
Content hash: `sha256-v3:8bed94a125e3e3ed533cd5acd7936a1e985e7e3c886fbf4a0f06c30994308278` — identical hash means identical model.

validate --sync and status --sync also refresh the files as a side effect; without the flag, neither writes anything.

Another tool can add its own line to the block’s pull-request step through pre_pr in .guardlink/config.json, rather than keeping a second block in every instruction file. The schema is in docs/GUARDLINK_REFERENCE.md, which init writes.

  • Add guardlink validate . to the agent’s finishing checklist. The instruction files already tell it to; a project-level hook makes it certain.
  • Commit .mcp.json. It is configuration every contributor needs, and it is three lines.
  • Give the agent guardlink_graph before a refactor, not after. It is the one tool whose answer is hard to reconstruct from reading files.