repoprompt-agent-run-mcp-not-inherited
Fix for `mcp__RepoPrompt__agent_run` subagents failing at dependency-check because non-RepoPrompt MCP servers (`mcp__seo-utils__*`, `mcp__open-brain__*`, and other custom MCPs) are NOT inherited by sp
SKILL.mdmisc/repoprompt-agent-run-mcp-not-inherited/SKILL.md
GitHubRepoPrompt agent_run MCP not inherited
Problem
When you spawn a sub-agent with mcp__RepoPrompt__agent_run op=start, the
sub-agent's Codex CLI session does NOT inherit all the MCP servers that are
mounted in the parent (the session you are running in). Specifically: only
mcp__RepoPrompt__* is reliably available in the spawned session. Any other
MCP server you have configured — mcp__seo-utils__*, mcp__open-brain__*,
mcp__chrome-devtools__*, and so on — is NOT mounted in the sub-agent.
This is silent. The sub-agent does not warn you up front; it only discovers
the missing MCP when it tries to call a tool, at which point it stops and
reports something like "seo-utils MCP is not connected in this session".
If the skill is well-written it will halt at a dependency check; if not, it
may silently degrade or hallucinate around the missing capability.
The skill's own allowed-tools frontmatter does not save you. Listing
mcp__seo-utils__query_database in allowed-tools is a permissions
declaration — it does not cause the MCP to be mounted in the spawned session.
Trigger conditions
Any of:
- You spawned a sub-agent via
agent_run op=startandop=wait/op=pollreturns aCompletedstatus whose output reads "X MCP is not connected in this session" or "only RepoPrompt is present". - A skill you delegated declares non-RepoPrompt MCP tools in its
allowed-toolsfrontmatter (mcp__seo-utils__*,mcp__open-brain__*, etc.) and the sub-agent claims those tools are missing despite the declaration. - You're designing a skill that mixes RepoPrompt MCP work (file IO, code navigation) with non-RepoPrompt MCP work (database queries, semantic search, browser automation) and need to decide which steps can run in a delegated sub-agent and which must run in the parent session.
Solution
The fix depends on which side you're on.
If you're TRIGGERING this skill (delegated a skill that failed)
Don't wholesale-delegate the whole skill. Run the orchestrator role yourself in the parent session — the one that has the missing MCP mounted — and delegate only the sub-steps that need RepoPrompt MCP.
Concretely, for skills like service-tier-brief-generator and
failure-brief-generator that have a documented "runs inline in the
orchestrator" step:
- Stay in the parent session (where seo-utils + OB1 are mounted).
- Run the orchestrator-side steps yourself: GSC database queries, OB1 thought searches, anything else that uses the non-RepoPrompt MCP.
- Delegate only the wiki/repo research agents (Step 2 + Step 3 in those skills). Those use RepoPrompt MCP exclusively, so they are safely delegatable.
- Synthesise the final artifact yourself, reading the dossier files the delegated agents wrote.
If you're DESIGNING a skill that wants to be delegatable
Treat sub-agent capability as a strict subset:
| MCP class | Available in parent? | Available in sub-agent? |
|---|---|---|
mcp__RepoPrompt__* |
Yes | Yes |
| All other MCPs (seo-utils, open-brain, chrome-devtools, etc.) | Yes | No |
| Built-in tools (Read, Write, Bash, Edit, Glob, Grep) | Yes | Yes |
Design your skill's pipeline accordingly:
- Steps that use only RepoPrompt MCP or built-ins: safely delegatable.
Dispatch with
agent_run op=start model_id="explore"|"engineer"|.... - Steps that use other MCPs: mark them inline-only. Add an explicit callout in the step heading so the next person doesn't try to wholesale- delegate the skill.
- Mixed skills: the parent session plays the orchestrator role. Dispatch
the safely-delegatable parts; run the rest inline. This is the pattern
used by
service-tier-brief-generatorStep 1b andfailure-brief-generatorStep 1b.
Recommended callout wording (mirror this in your own skills):
**Architectural constraint — read before delegating.** Step Xb runs in the
orchestrator's session, not in a delegated sub-agent. The `mcp__<server>__*`
tools are NOT inherited by spawned `agent_run` sub-agent sessions — only the
session that loaded the skill has them. This means the whole skill cannot be
wholesale-delegated to an engineer/pair sub-agent: the orchestrator role
must be played by the parent session that has <server> mounted (or the run
fails at dependency check). Steps Y and Z are still safely delegatable
because they only need RepoPrompt MCP, which sub-agents do inherit.
Verification
To verify a sub-agent's MCP availability before relying on it:
- Spawn a tiny test agent (
agent_run op=start model_id="explore") with a one-shot prompt: "List the MCP servers visible in your session and echo the names back. Don't do anything else." op=waitfor completion; read the output.- Compare against the parent's available MCPs. If any non-RepoPrompt MCP is missing, plan the orchestrator role accordingly.
You can do this once per machine/setup; the result is stable until you change RepoPrompt config.
Example
You wrote a skill that does GSC keyword analysis (uses mcp__seo-utils__*)
followed by repo research (uses mcp__RepoPrompt__*). You try to delegate
the whole thing to an engineer sub-agent:
mcp__RepoPrompt__agent_run op=start model_id="engineer"
message="Run my-gsc-skill on entity X"
The sub-agent comes back with:
seo-utils MCP is not connected in this session, so Step 1 (GSC probe) cannot run. I verified available MCP servers, and only RepoPrompt is present. Smoke test fails at dependency check.
Fix: keep the GSC probe in the parent session, dispatch only the repo research:
# In parent (where seo-utils is mounted)
result_a = run_gsc_probe_inline() # uses mcp__seo-utils__*
# Delegate the RepoPrompt-only part
agent_run op=start model_id="explore"
message="Walk app/routes/services/X/ and write findings to <dossier>"
detach=true
agent_run op=wait session_id=<id>
# Synthesise inline
write_brief(result_a, dossier_findings)
Notes
- This is specific to RepoPrompt's
agent_runcalling Codex CLI. Other agent backends or harnesses may have different inheritance rules. If RepoPrompt later changes the inheritance model, this skill should be marked deprecated. - Built-in Claude Code tools (
Read,Write,Bash,Edit,Glob,Grep) are reliably available in sub-agents — when a skill is RepoPrompt+built-ins only, full delegation works fine. The hazard is exclusively about non-RepoPrompt MCPs. - The
allowed-toolsfrontmatter of a skill is a permissions allowlist for the SESSION that loaded the skill; it doesn't trigger MCP mounting in spawned sub-agents. Don't read it as a guarantee of availability. - When in doubt about whether a step is delegatable, default to inline-with-callout. Over-delegating costs you a wasted agent run plus the time to diagnose; over-running-inline only costs context.
- Skills that already follow this pattern correctly (good references):
service-tier-brief-generatorv2.3+ Step 1b,failure-brief-generatorv1.8+ Step 1b,entity-demand-check(entirely orchestrator-side, never delegates).
See also
repoprompt-agent-run-sandbox-approval— sibling gotcha about a differentagent_runfailure mode: subagents pausing on file-write approvals when asked to write outside loaded RepoPrompt roots.skill-creator-aggregate-benchmark-layout— sibling gotcha about the workspace layoutaggregate_benchmark.pyexpects.