Skip to content

feat(mcp): cap a run from the MCP surface -- plan and start take max_calls / max_usd #1184

Closed

Description

@HugoXK

Problem

The run-level call cap shipped for the CLI (#1166, PR #1167) and the operator ceiling shipped for the process (#1082, PR #1181), but neither is reachable from the MCP surface. plan and start accept budget_usd and usd_per_call and nothing else:

  • agentdescent/mcp.py:669-671 — plan(self, spec, usd_per_call=None, budget_usd=None, probe=False)
  • agentdescent/mcp.py:714-715 — start(self, spec, budget_usd=None, usd_per_call=None)
  • agentdescent/mcp.py:757 — runstore.launch(rd, budget_usd=..., usd_per_call=..., env=...) — no max_calls
  • the tool wrappers mirror those signatures: :1393-1396 (plan), :1404-1416 (start)

So an MCP host that wants "at most N model calls for this run" has exactly one lever, the process-wide AGENTDESCENT_MAX_CALLS (agentdescent/runstore.py:107, operator_max_calls :116), which it cannot lower per call — and a host that does not set it gets no per-call bound at all. The CLI already validates this through build_call_limit (agentdescent/cli.py:2731-2733, evolvespec.py:1113-1135), including the refusal that names the field and the value.

This is user-perceivable: a caller of the MCP start tool cannot state a call cap, so the transcript of a runaway run shows no bound the host asked for.

Scope

  • Give plan and start (both the tool methods and the maybe_tool wrappers) max_calls: Optional[int] = None and max_usd: Optional[float] = None.
  • Validate them through build_call_limit(max_calls=..., max_usd=..., usd_per_call=...), so a bad value or a max_usd without usd_per_call refuses with the same wording the CLI uses — one contract, not two wordings.
  • Enforce the operator ceiling with the same min the run store applies: a caller may lower AGENTDESCENT_MAX_CALLS, never raise it.
  • Put the effective limit in the returned payload (plan and start), naming what was asked for and what will be enforced when the ceiling bound it — the same distinction AGENTDESCENT_MAX_CALLS_REQUESTED already carries across the detach boundary (runstore.py:109-134).
  • start must pass the clamped max_calls into runstore.launch so the detached child runs under it.
  • Offline tests for: cap accepted and reported; max_usd without price refused with the CLI wording; a caller's cap above the operator ceiling clamped and labelled; the nested-start stub (mcp.py:726-737) unchanged.
  • Docs row for the two tool arguments plus one changelog fragment.

Acceptance

  • An MCP start with max_calls: 1 launches a run whose status shows the cap and stops at it; with no argument the behaviour is exactly today's.
  • max_usd alone returns the CLI's max_usd needs usd_per_call refusal, not a new sentence.
  • With AGENTDESCENT_MAX_CALLS=2, a caller asking for max_calls: 9 reports 2 enforced / 9 requested and cannot raise it.
  • pytest -q stays offline and green; no new dependency.

Not in scope

max_concurrency, doctor reporting of the ceilings, any USD default for un-priced runs (a process-wide dollar ceiling would turn every un-priced run into a SpecError through require_budget_pair).

Source

Written-by: AgentDescent Lead

Activity

  1. added
    enhancementNew feature or request
    area:pluginsHost plugins and installers: Claude Code, Codex, DSH, OpenCode, MCP server
    area:cliThe agentdescent command line (cli.py, doctor, plan/evolve/status/apply)
    agent-workingAn agent has claimed this issue (the claim comment names the branch)
    on Nov 20, 2026
  2. HugoXK commented on Nov 20, 2026

    @HugoXK
    CollaboratorAuthor

    Branch agent/1184-mcp-call-limit from f5017f93; local tip 4015bb8f (4 files, +239/−13). PR follows in this session.

    Gap reproduced on clean f5017f93 with only tests/test_mcp_call_limit.py added: 8 failed, 2 passed on the final file (the earlier 6 was the same run before its last two rows existed). The eight: 7 are TypeError: Tools.plan() / Tools.start() got an unexpected keyword argument 'max_calls' / 'max_usd', the eighth is KeyError: 'call_limit' on the plan payload that names no cap — the surface does not exist, which is the issue. The two green rows are the no-cap, behaviour-unchanged ones, which must hold before and after; the behaviour rows (stop at the cap, ceiling in stop_detail, --max-calls 2 in the child argv) are asserted green at the tip.

    At the tip: tests/test_mcp_call_limit.py 10 passed, focused set of 7 files 116 passed, tools.changelog_fragments check and both gen_*_docs --check clean.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

agent-workingAn agent has claimed this issue (the claim comment names the branch)area:cliThe agentdescent command line (cli.py, doctor, plan/evolve/status/apply)area:pluginsHost plugins and installers: Claude Code, Codex, DSH, OpenCode, MCP serverenhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions