Connecting a coding agent (MCP)

Madebook installs above whatever your engineers already use. The agents keep their tools; the connection is an MCP server that runs where the client runs.

The server is stateless. It holds no database and no configuration beyond a token: every tool is an HTTP call to the Madebook API with that token as a bearer, so the web's authorization guard and audit log are the MCP's too. There is one authorization path, not two that can drift apart.

Before you start

1. An API token. Organization → MCP tokens → Create MCP token. Scope it to a workspace if the client only ever works on one. Copy it — it is shown once.
2. Your coding client must be on the organization's approved clients list. MADEBOOK_CLIENT is checked against it and an unapproved client cannot open a session at all. See Providers, models and clients.

Configuration

For Claude Code, in .mcp.json at the repository root:

{
  "mcpServers": {
    "madebook": {
      "command": "node",
      "args": ["/absolute/path/to/madebook/mcp/server.mjs"],
      "env": {
        "MADEBOOK_URL": "https://app.madebook.ai/api",
        "MADEBOOK_TOKEN": "vos_…",
        "MADEBOOK_CLIENT": "claude_code"
      }
    }
  }
}

The transport is stdio. Any MCP client that can launch a command works the same way.

You do not have to type this: the Editor tab of Connections shows the block with the address already filled in, fills the token in the moment one is created, and has a Copy button. Under it, Optional: auto-report hooks for Claude Code gives the hook snippet that opens and reports sessions without the agent being asked to.

The environment variables

Variable	What it is
MADEBOOK_URL	Where the Madebook API is. For the hosted product, https://app.madebook.ai/api. Defaults to http://localhost:8080.
MADEBOOK_TOKEN	The token from Organization → MCP tokens.
MADEBOOK_CLIENT	One of claude_code, cursor, codex, copilot, windsurf, vscode, other. Defaults to claude_code. Checked against the organization's approved clients.
MADEBOOK_WORKSPACE	A workspace id. Needed only when the token reaches the whole organization rather than one workspace.

The seven tools

The first version had eighteen tools, one per API call. An engineer opening that list saw a ceremony, and an agent given it spent tokens deciding which of five read tools to call. The seven below are the workflow. Everything else — the mission, the rules, the decisions, the policies, the skills, moving a step, evidence, run telemetry, a blocker, a proposed decision — is a parameter on the tool whose moment it belongs to.

They are listed in the order an agent uses them.

1. madebook_session_start — open

Opens a supervised work session and returns the compiled brief: policies, architecture rules, decisions already made, skills, workspace context, the mission contract, and what other sessions are touching. Called before anything is written.

Parameter	Type	Notes
mission_id	integer	The mission this session works on. Its contract must be approved.
workspace_id	integer	Needed only when the token is not scoped to a workspace.
label	string ≤ 80
branch	string ≤ 200
base_commit	string ≤ 80
worktree_path	string ≤ 500
files	up to 50 strings	Files the agent expects to touch, if known.
intent	string ≤ 2000	What it is about to do, in a sentence.

When the token reaches more than one workspace and none is named, the reply is not an error — it is the list of workspaces, with guidance telling the agent to ask the engineer which one, in plain language, and call again with its id. It is explicitly told not to guess and not to pick the first one.

If the token reaches no workspace at all: "This token reaches no workspaces. Create one in Madebook, or ask for a token with access."

If the client's hooks already opened a session, this tool continues that one rather than opening a second, and says so — unless the agent asks for a different mission, in which case it means what it says and gets its own session.

2. madebook_context — re-brief

Re-compiles the brief for the open session. Called when Madebook asks for a re-brief, when the agent moves to a different part of the code, after a report said stop, or while waiting on a person.

This is also the resume: anything a person decided since the agent last looked arrives here, once, with the instruction attached. It also says whether a person has asked the session to pause.

Parameter	Type	Notes
files	up to 50 strings	Files being worked in now. Decisions and skills are matched to them.
symbols	up to 50 strings
intent	string ≤ 2000
detail	up to 5 of mission, constitution, decisions, policies, skills	Attach a section in full.

The brief always summarises all five sections. detail is for when the agent needs a whole one:

• mission — the mission with each clause's verification state, the source item, the plan, the evidence, and the plan's instruction. If the session has no mission: "This session is not attached to a mission."
• constitution — the architecture rules with their do-not-use lists.
• decisions — only active decisions, matched to the paths and symbols given.
• policies — the policies in force for this organization and workspace.
• skills — the routed skills, with the threshold and cap that selected them.

3. madebook_plan — how

The execution plan for the session's mission. Exactly one of the two parameters is passed; passing both or neither fails with "Pass exactly one of steps (propose the plan) or step (move one step)."

steps proposes (or re-proposes) the whole plan — 1 to 40 steps — after reading the mission, the rules and the repository, and before changing code. Each step carries:

Field	Notes
title	≤ 200. One concrete technical change, e.g. "Add ownership check before document access".
detail	≤ 4000
kind	analysis, authorization, backend, frontend, data, integration, audit, tests, docs, other
files	up to 50 paths this step expects to touch
depends_on	up to 20 one-based step numbers that must land first
evidence_kind	unit_test, integration_test, browser, security_review, human_review

On a high-risk mission the plan waits for a lead, and the reply says so.

step moves one step: sequence (the step number), status (active, complete, skipped or blocked), an optional note, and optionally the files it actually touched if they differ from the plan. One step is active at a time, and Madebook shows it as the session's current step.

4. madebook_change_report — what

The workhorse. It reports what the agent did, and in the same call carries four other things that belong to that moment.

Parameter	Cap	What it is
files	2000	Path, change_kind (added/modified/deleted/renamed), lines added, lines removed.
symbols	500	Symbol, kind (class, interface, function, method, endpoint, table, type, module), path, change_kind (added, modified, removed, renamed, signature_changed), contract_changed, contract_detail.
dependencies_added	200	Name, ecosystem, manifest path.
rationale	4000 chars	Why the change was made, in the agent's own words. Kept with the change.
head_commit, branch
progress	0–100
pull_request		Number, URL, title.
evidence	100	Tests run, a browser check done.
run		One model invocation, as metadata only.
decisions_made	10	Decisions the agent made that future sessions should be told.

Evidence takes a kind, a label, a status of passed/failed/partial/not_run/unavailable, optional counts, an artifact URL, detail, and an unavailable_reason. It is stored as reported — the agent's own account — until CI or a person confirms it. The source is enforced on the server; an agent cannot claim its evidence was observed.

Run records provider, model, purpose (plan, implement, test, review, explain, fix, other), status, error, duration, files read, files changed, commands, tests run, and token counts including cache reads and writes. Never the prompt and never the output. A model the organization has not approved is refused here.

Decisions made land as proposed, for a lead to approve before they are injected anywhere. Each takes a title stated as a rule, a rationale, alternatives considered, a category (architecture, security, data, process, product, dependency, convention) and up to 20 paths or symbols it applies to.

Every reply carries next_action and the scope it applies to. See the execution protocol. A refused report still carries a state — a plan waiting for a lead answers with BLOCKED, and that is the useful half of it.

Naming the pull request is what turns that pull request's madebook/supervised status green. Madebook links it and never writes to it.

A call carrying nothing at all fails with "Nothing to report: pass files, evidence, a pull request, a run or a decision."

5. madebook_decision_request — ask

A person must weigh in. Two cases, told apart by kind.

A decision — architecture, security, product, governance, data or ambiguity (the default). The mission, the rules, the decisions and the policies together do not determine the answer, and choosing one would mean making a call that is not the agent's. This is explicitly not for something the agent can fix compliantly: if a rule already says what to do, it does that and reports it.

kind: "blocked" — the agent is stuck for a reason that is not a decision: a broken environment, a missing credential, something it cannot see. The session is marked blocked and it lands in the attention queue.

Parameter	Notes
title	≤ 200. The decision, or the blocker, in one line.
question	≤ 4000. What has to be decided and why the existing rules do not settle it.
detail	≤ 4000
proposal	≤ 4000. What the agent would do if it were its choice. Often the fastest thing to approve.
blocked_scope	up to 20 strings. What cannot proceed until this is answered.
allowed_scope	up to 20 strings. What it will work on meanwhile.

The guidance in the reply is explicit: do not implement the blocked scope, do not wait, work the allowed scope, and call madebook_context when the answer is needed. If nothing independent is left, say so to the engineer and stop.

6. madebook_implementation_complete — finished writing

This is not a claim that the mission is done — you cannot know that.

The agent reports what it built and the evidence it produced. Madebook answers with what the evidence gate is still missing, by name.

Parameters: detail (≤ 4000 chars) and up to 100 evidence entries in the same shape as above.

The reply carries next_action, ready_for_pull_request, still_required, resting_on_your_own_word, and the full evidence_gate.

7. madebook_session_end — close

Closes the session, whether or not the implementation is finished. Implementation should be reported first; this only ends the session.

Parameters: detail (≤ 4000) and progress (0–100, default 100).

The reply says it plainly:

The session is closed. Whether the mission is complete is decided by the evidence gate, the pull request and a person — not here.

Auto-report hooks

Every rule the execution protocol enforces is cooperative. An agent that never calls madebook_change_report is never told anything, and the light on the pull request only goes red after the fact.

The hooks remove the dependency on the model remembering. The coding client calls mcp/hook.mjs on the events it exposes, using the same token — one session, shared between the hook and the MCP server through a small local state file.

Event	Claude Code	Cursor	What Madebook records
Session start	SessionStart	— (opens on first stop)	Opens a session if none is live; prints state and instruction into context
A file edited	PostToolUse on Edit / Write / MultiEdit / NotebookEdit	afterFileEdit	Remembers the path locally. No network call.
Turn ends	Stop	stop	One change report for every remembered path, line counts taken from git, marked reported_via: hook; reads next_action
Session ends	SessionEnd	—	Flushes, then closes the session

On Claude Code the Stop hook can block the stop once with a reason. Madebook uses that for exactly four states — REMEDIATE, DECISION_REQUIRED, BLOCKED and HARD_STOP — so the model continues with the instruction rather than ending its turn. The client's own stop_hook_active flag prevents a loop: a stop that a hook already re-triggered is never blocked again.

Set MADEBOOK_HOOK_QUIET=1 for a client that treats any output on stdout as an error.

Installing the hooks

• Claude Code — plugins/claude-code/README.md: a plugin, or four lines in .claude/settings.json.
• Cursor — plugins/cursor/README.md.
• Codex — plugins/codex/README.md. Codex exposes no hook events, so it gets instructions instead.

The API tokens page shows these snippets with your token already filled in.

What the hooks never do

They write nothing to the repository and never block an edit. If Madebook is unreachable or the token is wrong, edits go unreported, the hook says so on stderr, and the madebook/supervised status on the pull request stays red until a session claims it. An unreachable Madebook degrades to "unreported", which is exactly what the status then says.

How a session reports its own wiring

A session's page shows how its reports arrived: via hook, via the model's own calls, or both. That is measured from what actually arrived, never from how the client was configured — a hook that is installed and never fires reads as "the model's own calls", which is the honest answer.

What the MCP can never do

Read tools dominate, and the write tools write only to the session the token opened. Nothing in the MCP can approve anything, ship anything, amend the architecture rules, or read another workspace.

Related

• API tokens
• The execution protocol
• Work sessions
• The pull request check