Skip to content

Agent integration

Jump to bottom
Kevin Straub edited this page Aug 1, 2026 · 7 revisions

An agent can reach a hundred tools while carrying one line per server in its context. That line still has to get in there somehow.

The prompt block

mduct index
MCP tools via `mduct` CLI (list+args: mduct tools <server>; call: mduct call <server> <tool> key=value key:=<json>):
  gitlab       — GitLab: MRs, pipelines, issues, repos
  notes        — shared notes
CLI tools via `mduct` CLI (run: mduct run <tool> [args…]):
  kubectl      — read-only cluster access

Paste it into a system prompt, a CLAUDE.md, an AGENTS.md, whatever your harness reads. Each line is that server's note field. Write those notes for someone who has to pick a tool from this list and nothing else.

Claude Code

mduct hook install claude          # --remove to undo

Two hooks land in ~/.claude/settings.json:

SessionStart prints mduct index, so the block is there without you maintaining it. It also warns when a server is attached directly to Claude while mduct serves it too, since you would be paying for those schemas anyway.

PreToolUse matches mcp__* and answers with the replacement command, mduct call <server> <tool> key=value. Only for servers mduct actually serves. Everything else passes through untouched.

Other people's hooks in that file are left alone. Re-running the install replaces mduct's own entries and nothing else.

The installer writes the path of whichever binary you ran it with. Install first, then run mduct hook install claude from the installed one. Running it from a source checkout pins your hooks to your working tree, which is rarely what you meant.

Everything else

There is no plugin API and nothing needs one. Any agent that can run a shell command can use mduct:

  1. Put mduct index output in the system prompt.
  2. Let the agent run mduct tools <server> when it needs the tool list, and mduct schema <server> <tool> when it needs the fields.
  3. Calls are mduct call <server> <tool> key=value.

Three commands. If your harness has a bash tool, it already supports mduct.

Teaching the pipe habit

An agent that runs mduct call srv list_things gets the whole list in its context. Run the same thing with --json | jq -c 'map({id,title})' and it gets what it asked for. That difference is real money, so the index block mentions it and mduct help carries worked examples.

warnAbove is the backstop. An oversized result prints a warning with a ready-made jq projection instead of quietly costing 40k characters.

mduct config warnAbove 25000

Isolating an agent

Give it a profile and it gets its own config, secrets, OAuth tokens and daemon:

MDUCT_PROFILE=research mduct add notes --url https://mcp.example.com/mcp
MDUCT_PROFILE=research mduct call notes search q=neutrinos

One agent cannot see or use another's servers or credentials. Add a guard per server and the blast radius of a confused agent stops depending on its own good judgement.

Nudging it toward the better tool

If a server keeps losing to a habit (an index server to grep, an API to curl), it can say so at the moment of the call. See Shadowing.

Clone this wiki locally