Connect an AI agent

This is the core scenario for Agent NextUp. The division of labour: Agent NextUp is the management layer, the AI agent does the execution. The two meet at the hub: nextup-mcp, an MCP (Model Context Protocol — the open standard agents use to call external tools) server bundled with the app, which exposes the project’s tasks, ledger and workflow to the agent as tools.

Wiring it up (one-time)

1. There is nothing to build or put on your PATH. The app’s own build step compiles nextup-mcp and bundles it alongside the app; a workspace you initialised already contains .mcp.json in its root, pointed at that executable’s absolute path. There is no background service to start or keep running: the agent host spawns nextup-mcp itself through that file, once per session, and it exits with the session.

2. The Claude CLI picks .mcp.json up and connects to the hub automatically when it opens that folder. Other vendors’ CLIs wire up MCP differently and do not — consult their own documentation.

3. To check the connection, go to the Tools page and look at the nextup-mcp health card. Ready means it is wired up. Needs repair (for example after you rebuilt the executable) means press Repair connection to re-point it — it repairs the pointer in .mcp.json, there is no running process to restart. Executable missing means the hub binary could not be found at all — neither bundled beside the app nor on your PATH; rebuild the app, then repair here.

   Working on one project from two machines? That absolute path belongs to the machine that wrote it, and .mcp.json sits in the project root, so git or a synced folder carries it to the other machine — where agents then fail to connect, with nothing on their side saying why. On the second machine the health card shows Needs repair, and the workspace doctor reports it too (hub_discovery); press Repair connection there. The app never rewrites the file just because you opened the project, so the two machines only overwrite each other when someone repairs. Whether to keep .mcp.json in version control at all is answered in the FAQ.

Any other MCP client

The hub is a plain stdio MCP server — nothing about it is Claude-specific. What the Claude CLI reads from .mcp.json is this (with command rewritten at init time to the bundled executable’s absolute path):

{
  "mcpServers": {
    "nextup": { "command": "nextup-mcp", "args": ["--workspace", "."] }
  }
}

To wire up any other MCP client, copy that command and args into its own configuration. Two things to know:

• --workspace . resolves against the directory the server is spawned from. Claude Code spawns it from the project root, so . works; if your host spawns servers from somewhere else, replace . with the workspace’s absolute path. Getting this wrong is loud rather than silent — the server prints not an initialized Agent NextUp workspace to stderr and exits with code 2 — but some harnesses swallow server stderr, so if the server “just won’t start”, check this first.
• Full usage is nextup-mcp --workspace <root> [--agent <name>]. --agent names the caller in the ledger; the NEXTUP_AGENT environment variable does the same, and the flag wins when both are set. Worth setting even for a single agent, so the audit trail says who did what. (Several agents in parallel, each under its own name, is the multi-agent setup.)

To verify the wiring on any client: have the agent call workspace_status — read-only, needs nothing beyond the master switch — then look at .nextup/ledger.jsonl. Every hub call lands there, so one entry proves the connection end to end.

Authorisation (you are in control)

On the Tools page:

• At the top is the master switch, “Allow agents to reach the hub”. Turned off, the AI can’t even use read-only tools — it is fully disconnected.
• With the master switch on, Read-only tools (always allowed) (list tasks, view the workflow, search, doctor, and so on) need no per-item setup.
• Write tools (granted by capability group) (create tasks, change status, record decisions…) are authorised by group. Each group has a name and a plain-language description (task editing, knowledge recording, phases and milestones, …); ticking a group opens every tool in it. Expand Per-tool to control them one by one, or use Select all to open everything currently exposed — tools belonging to a module you have not enabled are not in that set.
• New projects don’t start from zero. At creation, the everyday recording and flow tools are already authorised, so an agent can do useful work the moment it connects. What stays off by default is anything that is itself a check: marking something verified (set_task_verification / set_milestone_verified), advancing a phase (advance_phase), packaging a delivery into this workspace’s outbox (publish_delivery), and rewriting workspace assets (upgrade_workspace_assets) — plus every tool of a project put in charge of a team, which reach outside this workspace altogether. You have to open those yourself. reference/mcp-tools marks each one, and is the list this page does not restate. (Projects created before this default are not retroactively changed — they remain fully closed; one press of “Select all” fixes that.)
• Every call is written to the ledger — including rejected ones — so it can be audited afterwards.
• You find out immediately when a call is denied. If an AI calls an unauthorised tool, a toast appears in the bottom right (“⟨agent⟩ was denied ⟨tool⟩ — not authorized yet”) with an Authorize button. Repeated attempts at the same tool don’t spam you; they collapse into one entry with a count. Without that toast the AI would just sit there waiting and you would never know.
• Grants take effect on the agent’s next call. The server re-reads the allowlist from disk per call, so there is no session to restart — authorise the tool and tell the agent to try again.
• An AI has no permission to force a phase advance or to satisfy a manual confirmation gate. Those two are permanently human-only.

Where the allowlist ends

The allowlist governs the hub tool surface: the structured operations above, each checked per call, each ledgered. It does not govern your agent’s own hands. A coding agent with file access can edit any file in the workspace directly — including .nextup/ state, and including agent_access.json, the allowlist itself. Those hands are your agent CLI’s permissions to grant or withhold, not Agent NextUp’s; the openness is the price of files-are-truth, the same property that lets you fix anything with a text editor. What holds regardless: gates are evaluated against real state, manual_confirm has no tool surface at all, and the file watcher picks up hand edits — but a hand edit is not a ledgered call. Read the ledger as the record of what agents did through the hub, not of everything that happened to the folder.

Actually using it

Open a Claude Code session in the project folder. The first time, the CLI asks whether you trust this project’s .mcp.json — allow it, and every subsequent session connects automatically.

It then reads the root CLAUDE.md, a short shell whose one working line imports AGENTS.md — whose state block the engine keeps fresh (current situation, this phase’s instructions, gate list, next step) — picks up the work from there, and reports tasks and decisions back through the hub tools. You watch the progress arrive in the app live.

The bundled skills

Initialising a workspace also places the general-purpose workflow skills in .agents/skills/, with identical copies in .claude/skills/ where Claude Code discovers them (you can customise them — edit both, or the doctor will flag the mismatch):

• Hand over a broad or vague direction and /align-scope settles what “done” means before any work starts — rounds of numbered questions, each with a recommended answer you can accept with a yes, decisions left to you.
• Say “wrap up” to Claude Code and it runs /wrap-up — commit in batches, run the doctor, write progress and decisions back into the project.
• “Check that this can be handed off” runs /handoff-check — self-audit for unrecorded facts, then dispatch a brand-new agent to cold-read the handoff documents and verify a takeover actually works.
• After large documentation changes, /adversarial-review dispatches an agent to check each claim in the docs against reality.
• Once the scope is settled, /slice-work turns it into tasks the engine can schedule — vertical slices, each declaring what must land first, checked with you before they are created.
• At the end of a phase, /retrospect starts from the friction the ledger recorded and turns each piece into one change: an automated check where a machine could have caught it, otherwise a lesson, a boundary or a rejected idea.

A project created with the Software Development template also gets a coding pack, which that template’s phases call at the right moments: /test-first (red–green slices at agreed seams), /debug-loop (a red feedback loop before any theory), /two-axis-review (conventions and spec, reviewed separately), /ship-notes (release notes with evidence and an undo verdict) and /work-the-frontier (builds every ready task in parallel; only you can start it). The pack comes with the template — the template is what tells the agent when to use each skill. A project created with that template on an earlier version gets the pack from the Tools page’s upgrade panel, like any other missing file.

Several of these are adapted from mattpocock/skills (MIT) and rewired to the engine — the dependency gate, the ledger, spec deltas. If you also install that collection, both sets coexist under different names; ours are the ones that talk to the hub.

Step 7 of the session operating protocol instructs agents to invoke them proactively at the right moments, without waiting to be asked. Naming them yourself is a backstop, not a requirement. If your agent host has no concept of skills, each one is plain Markdown at .agents/skills/<name>/SKILL.md — readable and followable as a procedure.