MCP setup & tools¶
ml-party’s agent surface is an MCP server. It is self-teaching: the full
tracking workflow (orient → prior-art query → pre-register → env-handshake
launch → finalize → distill) is the canonical agent operating manual, served
by the workflow_guide tool. This page covers setup and the tool surface, and
tracking.md explains the contract itself.
Everything else about the package is served by the help tool: these guides
ship inside the wheel, so an agent that only ever ran pip install mlparty can
read them without a checkout or a browser. help() bare returns the topic
index plus every mlp command, the installed version, and the store root;
help(topic) returns a guide in full. The MCP surface is an agent’s whole view
of ml-party, so anything it cannot pull from there, it does not know.
How the workflow reaches the agent¶
Three channels exist and only one of them is reliable, which is why the manual lives where it does:
Channel |
Reaches the agent? |
|---|---|
|
Yes — the manual and every guide, pulled on the agent’s own initiative. Clients may defer tool schemas, but names stay visible. |
Tool responses |
Yes, unconditionally — every response carries a nudge to call |
MCP |
Not guaranteed. Clients cap it (Claude Code at exactly 2048 chars, mid-word, silently) and may drop it outright — the spec calls it a hint clients MAY use. Kept short: a summary whose first line is call |
|
Only if you invoke it — prompts are user-triggered slash commands, so an agent cannot reach for one. |
So the connection text is a router, not the manual, and a test pins it under
budget. If you are writing an MCP server with a workflow to teach, this is the
trap: a long instructions string looks delivered and is not. The spec calls
the field “a hint… MAY be added to the system prompt” — a client may cap it
or ignore it outright and still be conformant, and capping is sound, since
server instructions are untrusted text entering the system prompt. Note the cap
applies per tool description too.
One store, or one per project?¶
Decide this first: it shapes everything else. A store is a notebook, not a
per-repo file. It holds project → experiment → run, and retrieval spans
the whole store — so one store covering all your work lets an agent answer
“what did I try for the vocoder last spring?” from inside any project. A
store per repository splits that into islands which cannot see each other,
and makes the project node type pointless.
The default: one personal store, registered globally.
pip install mlparty
mlp init --root ~/.mlparty --no-mcp
export ML_PARTY_STORE=~/.mlparty # so the `mlp` CLI finds it anywhere
--no-mcp is deliberate: it skips writing a .mcp.json into whatever
directory you happen to be standing in, because this store is registered
globally instead (next section). Each codebase you work in then becomes a
project inside that one graph, and the working directory stops mattering.
A store per project is right in three cases, and only those: the notebook should travel with the repository; a team shares a served store for one project; or a project’s data must stay physically separate (different disk, different backup policy, different machine).
cd /path/to/your/project
mlp init --root .mlparty # store + ./.mcp.json, both here
The trade-off is that queries only ever see this project, and you repeat the setup per repository. If you later want them joined, a spool store can flush into a served one (Remote tracking (spool-and-flush)) — but two local stores do not merge.
Mixed setups are fine: keep the personal store global, and register a
project-local store for the one repository that needs it with
mlp connect --root <that store> --project <dir>.
Zero-terminal setup¶
mlp init --root .mlparty # new store + MCP registration in ./.mcp.json
mlp connect --root <store> # register an existing store in this project
mlp mcp-config --root <store> # print the JSON snippet for other MCP clients
mlp serve-mcp --root <store> # run the server by hand (stdio)
mlp init / mlp connect write (or merge into) the project’s .mcp.json —
the project-scoped convention Claude Code and compatible clients read — so
an agent started in that directory picks the server up after a one-time
approval. From there, “use ml-party to track this run” is all an agent needs
to hear. Note: .mcp.json carries absolute paths — keep it out of git.
Any other MCP client works the same way through its own configuration:
mlp mcp-config --root <store> prints a standard mcpServers entry to
paste (Cursor’s .cursor/mcp.json, and so on — a few clients use a
different top-level key, so check yours). Registering the store globally
rather than per-project is usually what you want: one store holds many
projects, and a global registration means it is there in every session
regardless of the directory.
If the server does not show up, it is almost always one of two things:
The agent was started somewhere else. A project-scoped
.mcp.jsonis read from the directory the agent starts in — not the directory you ranmlp initin, if those differ.cdto the directory holding.mcp.jsonand start the agent there.The approval prompt was never answered. Project MCP servers need a one-time approval; until then the server stays inactive.
Verify with /mcp inside Claude Code (it lists active servers), or
claude mcp list from the shell. To register the store for an agent that
runs elsewhere, use mlp connect --project <that directory>, or paste the
mlp mcp-config snippet into that client’s own configuration.
Tools (21)¶
Tool |
Purpose |
|---|---|
|
the full operating manual, plus which store you are serving and what is in it — an agent’s first call |
|
the package explaining itself — bare returns the quickstart in full plus the index (every |
|
get-or-create hierarchy; an experiment answers one question |
|
pre-register intent + auto-capture; returns |
|
what a code snapshot of a directory would capture, and the delta vs the last one — before anything is written |
|
where a run executes when that is not this machine — job system, id, and the link back to the job (see tracking.md) |
|
telemetry from the agent side (the training process usually streams instead — see tracking.md) |
|
cross-run artifacts on the experiment — experiment-level boards, summary reports (see boards.md) |
|
run control through registered templates — audited, typed, quoted (see actions.md) |
|
close the contract; refusals return as data |
|
distilled knowledge; append-only corrections |
|
retrieval: full nodes, hybrid ranked search, code/param/metric deltas |
Contract refusals come back as {ok: false, refusal: {missing, invalid}} —
repairable in one round-trip, never a protocol error.
Code capture is asked for, never assumed¶
The workflow guide tells agents to ask you which directory holds the code
before the first run they track, rather than picking one. That
directory is source_root, and it is the only thing that gets snapshotted:
The agent calls
snapshot_previewand shows you the file list before anything is written.Files your
.gitignoreexcludes are never captured — that is the lever for keeping something out, and it is one you already use.No
source_rootat all means the run records no code. Nothing is ever captured silently.Outside a git repo, or for an unusually large capture,
run_startrefuses until the agent has shown you the list and you agree (confirm_snapshot). Agents are instructed never to set that flag on their own.
Once you have settled on a directory, later runs from it need no new permission; the preview’s delta reports what changed.