| name | runtime-bridge-conflict-resolver |
| description | Detect and resolve MCP bridge conflicts (Path 1 Lab MCP + Path 2 ahujasid running together, port 9876 collisions, host mismatch). Use when readiness checker reports inconsistent signals. |
runtime-bridge-conflict-resolver
Purpose
Resolve the single-bridge constraint when more than one MCP runtime path is configured against the same Blender instance (or when ports collide). BlendOps documents that Blender accepts only one MCP bridge session per instance — but both Path 1 (Blender Lab MCP bpype/blender_mcp) and Path 2 (community ahujasid/blender-mcp) commonly bind to a localhost:9876 range. If both are configured concurrently, the second connection silently fails and downstream planners get inconsistent signals.
This skill diagnoses the conflict, names the cheapest resolution, and hands off to the readiness checker for re-verification.
This skill is BlendOps-specific (no direct analog in Anthropic Superpowers or BMad), driven by the Single-bridge constraint described in docs/runtime-stack-strategy.md.
Quick start
- list every active / configured bridge for the target Blender session
- check for port collision (commonly
localhost:9876)
- identify which path is intended; which is residual
- propose the cheapest disable / port-isolation step
- hand off to
official-runtime-readiness-checker to re-verify
When to use
official-runtime-readiness-checker reports inconsistent signals (e.g. "MCP host says connected" but tool calls return wrong tool surface)- you see Lab MCP add-on AND
ahujasid/blender-mcp addon.py both installed in Blender
- two MCP clients are pointing at the same Blender (e.g. Claude Desktop with Connector + Cursor with manual MCP)
- a recipe smoke test fails despite a recent successful read-only smoke
- log shows port collision around
localhost:9876
When not to use
- no readiness signal yet (run readiness checker first)
- only one path is configured and working (no conflict to resolve)
- the user explicitly wants both paths configured for separate Blender instances on different ports (note: still requires explicit port isolation)
Trigger phrases
- "tool surface looks wrong"
- "smoke test passed yesterday but recipe fails today"
- "Lab MCP and ahujasid both installed"
- "Claude Desktop and Cursor both pointing at Blender"
- "port 9876 already in use"
- "single-bridge constraint violation"
Prerequisites / readiness
- list of configured MCP servers per client (
mcpServers in client config files)
- list of installed Blender add-ons inside Blender (Lab MCP add-on +
ahujasid/blender-mcp addon.py)
- log / port output if available (
netstat -ano | grep 9876 or equivalent)
- no Blender execution required from this skill
Input schema
Required inputs
- target Blender instance (path to
blender binary or "the running session")
- list of MCP clients that are currently configured to talk to that Blender
- list of Blender-side add-ons currently enabled (Lab MCP /
ahujasid/blender-mcp addon.py)
Optional inputs
- recent readiness checker report
- recent smoke test record
- port usage output
Assumptions to confirm
- the operator can disable one path or change ports
- only one path is intended at a time (or explicit port isolation)
- runtime status is one of
Not Run / Attempted / Blocked
Output schema
Primary output
- conflict diagnosis: which paths are present, which is intended, what's residual
- cheapest resolution step (disable add-on / unregister MCP client / change port)
- post-resolution verification handoff
Secondary output
- per-bridge state matrix
- explicit "do not run X concurrently with Y" reminders
Evidence / caveat output
- runtime status: unchanged by this skill (only readiness checker can update)
- artifact status: unchanged
- explicit note that resolution requires operator action; this skill plans, doesn't execute
Required laws
- ../../laws/official-runtime-only.md
- ../../laws/evidence-before-done.md
- ../../laws/no-arbitrary-python-interface.md
- ../../laws/non-blender-user-language.md
Official runtime boundary
This skill does not disable add-ons, edit MCP client configs, change ports, kill processes, or run Blender. It diagnoses and proposes a resolution. The operator (or another skill) executes.
Operating procedure
- Build the bridge state matrix:
- For each MCP client (Claude Desktop with Connector, Claude Desktop manual MCP, Claude Code, Cursor, Codex, OpenCode, Cline, Continue, Zed, goose, LM Studio, Open WebUI, Ollama, etc.) record whether it is currently registered for this Blender.
- For Blender-side: record whether Lab MCP add-on is enabled, and whether
ahujasid/blender-mcp addon.py is enabled.
- Record ports if known.
- Identify the intended path from the user / brief / readiness checker.
- Identify residual / unintended bridges:
- Both Path 1 add-on AND Path 2
addon.py enabled → conflict.
- Two MCP clients pointing at the same Blender → conflict.
- Two servers binding the same port → conflict.
- Propose the cheapest fix:
- If only Path 1 intended: disable
ahujasid/blender-mcp addon.py inside Blender; unregister uvx blender-mcp from MCP client config; restart MCP client.
- If only Path 2 intended: disable Lab MCP add-on inside Blender; if Anthropic Connector is on, also disable that toggle; restart Claude Desktop.
- If both wanted on different Blender instances: explicit port isolation, separate Blender processes, separate workspaces.
- State explicit
do-not reminders for the operator.
- Hand off to
official-runtime-readiness-checker to re-verify the single intended path is the only active one.
Decision tree
- both Path 1 and Path 2 add-ons enabled → ask user which is intended; disable the other.
- two MCP clients configured for the same Blender → ask which is the working session; unregister the other.
- two servers on
localhost:9876 → change one to a different port (e.g. 9877) AND update its MCP client config to match.
- Anthropic Connector toggle ON + manual
mcpServers JSON entry for Lab MCP → these are both Path 1 host options targeting the same Lab stack. Pick one host option per session (per runtime-stack-strategy.md).
- everything looks clean but smoke still fails → route to
blender-troubleshooting.
Playbooks
- Playbook A: "Path 1 + Path 2 both installed" — disable the unintended path's Blender-side add-on first, then unregister its MCP server.
- Playbook B: "Two MCP clients" — pick one client per Blender session; unregister the other from this Blender (its config can stay for other Blender instances).
- Playbook C: "Port collision" — change one server's port; update that client's config to match.
- Playbook D: "Path 1 host (a) Anthropic Connector + Path 1 host (b) manual MCP both ON" — pick one host per session per
docs/runtime-stack-strategy.md.
Mode handling
Text-only mode
- diagnosis only, no execution
- runtime status unchanged
- artifact status unchanged
Runtime-ready mode
- diagnose + propose + hand off; this skill never executes the resolution
Blocked runtime mode
- still useful: even when blocked, the conflict can be diagnosed from configs
- mark resolution proposal as text-only
Validation checklist
Pass / Warn / Fail rubric
| Category | Pass | Warn | Fail |
|---|
| State matrix | Complete | Partial with note | Missing |
| Intended path | Explicit | Inferred without confirmation | Not identified |
| Residual identified | Named with reason | Named without reason | Not named |
| Port check | Done or marked unknown | Done partially | Skipped |
| Resolution proposal | Cheapest step + rationale | Step without rationale | None |
| Execution claim | None | None | Claimed disabled / changed config from this skill |
Failure handling
- operator can't access Blender's add-on list: ask them to check Edit → Preferences → Add-ons; meanwhile mark Blender-side state
Unknown.
- operator can't access MCP client configs: ask for paths (Settings → Developer → Edit Config in Claude Desktop, etc.); meanwhile mark client-side state
Unknown.
- operator unsure which path is intended: route to readiness checker to gather one passing read-only smoke first.
Troubleshooting
- if matrix says only Path 1 active but tool surface is Path 2 (
get_scene_info) → readiness signal is wrong; re-run smoke with explicit tool name list before any resolution.
- if matrix is clean but smoke still fails → route to
blender-troubleshooting.
Best practices
- diagnose before proposing
- explicit do-not reminders prevent re-introduction
- hand off to readiness checker; never claim resolution worked from this skill
Good examples
- "Bridge matrix: Lab MCP add-on enabled (Blender),
ahujasid/blender-mcp addon.py also enabled (Blender), Claude Desktop has Anthropic Connector ON, Claude Desktop also has mcpServers.blender = uvx blender-mcp. Conflict: 2 Blender-side bridges + 2 host options (a) and (b) both targeting Path 1 + Path 2 mixed. Intended (per brief): Path 1 host (a) Anthropic Connector. Cheapest fix: disable ahujasid/blender-mcp addon.py inside Blender; remove the manual mcpServers.blender entry; restart Claude Desktop. Do-not: keep both Blender-side add-ons enabled at once. Handoff: official-runtime-readiness-checker."
Bad examples
- "Both look configured, just try restarting" (no matrix, no intended path, no resolution rationale, no do-not reminder, no handoff).
User-facing response template
- Bridge state matrix (markdown table)
- Intended path (explicit)
- Conflicts found
- Cheapest resolution step
- Do-not reminders
- Handoff:
official-runtime-readiness-checker
Anti-patterns
- proposing a fix without building the matrix
- executing the fix from this skill
- ignoring port collisions
- treating Anthropic Connector and manual MCP as if they were independent paths (they are both Path 1 host options; pick one)
Cross-skill handoff
- After resolution proposal:
official-runtime-readiness-checker to re-verify
- If matrix is clean but smoke still fails:
blender-troubleshooting
- If user wants to change paths entirely:
official-runtime-setup-guide
Non-goals
- executing the resolution (operator does that)
- running Blender
- editing MCP client configs from this skill
- replacing readiness checker
References
- BlendOps doc: ../../docs/runtime-stack-strategy.md (Single-bridge constraint)
- BlendOps doc: ../../docs/external-runtime-setup.md
- BlendOps doc: ../../docs/unofficial-runtime-bridges.md
- Skill system: ../../docs/skill-system.md
