[nissa-seru]

Two MCPL servers whose toolPrefixes meet are now refused, so two servers can't give one namespaced tool name. A server that lists one tool more than once has it offered once. !Closes #265.

The bug. An MCPL tool reaches the model as <toolPrefix>--<tool>, and a prefix may itself contain --. So two servers could give one name: foo listing bar--echo and foo--bar listing echo both gave foo--bar--echo. A server could also list one tool twice. Either way the model's tool list carried the name twice.

• Native tool mode, connectome-host's default: membrane 0.5.87's native formatter refuses such a request ("Native tool names collide after colon escaping"), and so does Anthropic's API (400 invalid_request_error, "tools: Tool names must be unique."). Every inference of an agent offered the name failed.
• XML tool mode (anthropic-xml): the prompt carried both definitions under one name, and calls reached whichever server listed it last.

The fix.

• When two prefixes meet. Two prefixes give one name only when they're the same, one is the other's followed by -, or one begins with the other's followed by --. prefixesMeet (src/mcpl/prefix-rule.ts) says exactly that.
• The refusal. create() already refused two servers with one prefix. It now refuses two whose prefixes meet, and so do a runtime connect and a restart, which refuses before it disconnects anything. The error names both servers, both prefixes and the rule.
• What that leaves. With no two prefixes meeting, a name fits at most one server's prefix. So the listing, the longest matching prefix and the first configured server always name the same server, whatever is connecting, restarting or refreshing.
• The prefix map stays true to the configured servers, since the runtime refusal reads it:
  • A connect of an id already registered wrote its config and prefix over the live server's before the registry refused it. It's now refused before it writes anything, and so is a restart into another live server's id.
  • A connect under a new prefix, for an id whose earlier connect had failed, wrote its entry beside the one that failed connect left, and the old entry outlived the id. A connect now drops its id's other entries before it writes its own.
  • A disconnect of an id with no config deleted the entry under that id's default prefix, which another server may hold. It now deletes only its own.
  • A restart doesn't count the prefix of the server it replaces, since it disconnects that server first, whatever id the new config carries.
• A server listing one tool twice has its first listing offered, with its class and feature set, and the rest left out. Each tool refresh that finds it raises an mcpl-tool-duplicate ops alert naming the tools, which says that's for the server's maintainer to change. Its webhook post goes out at most once per server in 15 minutes.
• Module names are still compared with server prefixes by equality. A module's tool could meet a server's only through a module tool name containing -- or starting with -, and no module in agent-framework or connectome-host has one. Comparing module names by the meeting rule would refuse configurations that work, such as a discord--voice prefix beside the discord module.

What operators will see.

• Breaking: a configuration with two prefixes that meet is refused at startup, or its later server at connect, with the message above. Such a pair works today wherever its servers' names don't meet. We found none in connectome-host, anima-docs, infra, discord-mcpl, telegram-mcpL, slack-mcpl, heartbeat-mcpl or agent-framework's README.
• foo beside foo-bar or foobar is fine. Default prefixes meet only when one server's id is another's followed by -, or begins with another's followed by --, such as x and x--y.
• Native agents offered a tool a server lists twice work again.

Each part, and what it's for

• prefixesMeet, one function holding the exact rule, so the refusal is never wider or narrower than the names. The simpler "one prefix begins with the other's" would also refuse foo beside foobar, which can't meet. Its test checks the rule against a search over every pair of short prefixes.
• The check at create(), a runtime connect and a restart, the three ways a prefix arrives. The runtime two share refuseMcplConnect with the existing module-name and same-prefix checks. The restart runs it before disconnecting, so a refused restart leaves its server running instead of disconnecting it and then failing at the connect.
• The duplicate-id refusal, the connect's drop of its id's other entries, and the disconnect's ownership check, a few lines between them, keep the map the refusal reads true. Without them a connect can leave a prefix no server holds, which refuses later servers, and a disconnect can remove a live server's claim, which lets a meeting prefix in.
• Keeping a repeated tool's first listing. A server's own repeat can't be refused at configuration, since it depends on what the server lists. Left out, it keeps the native-mode failure.
• The alert at each refresh that finds it tells the operator which server lists what twice. It keeps no state, so it repeats at each refresh while the listing lasts, and the ops alerts' cooldown limits the webhook.
• Not taken: deciding shared names at listing time. Letting meeting prefixes run and giving each shared name to the first server in configuration order needs the claim order kept through restarts, each server's names held between its listings, a record of restarting servers, collision state for one alert per collision, and a queue for refreshes. Refusing the prefixes gives one server per name for every configuration it accepts, with no state beyond the prefix map the framework already keeps.
• Not taken: a suggested prefix in the refusal. A suggestion built from the two prefixes can still meet the other one, or another server's, so the refusal states the rule instead.

Tests

Runs on Linux. e66f1ad8 merges main at 61a69977 into this branch, and 044f5268 after it changes only a changelog fragment.

• At e66f1ad8, the whole suite passes, 3668 of 3668 tests in 207 files, on Node 24.22.0 without --test-force-exit, each file exiting on its own, and on Node 20.20.2 with it. Typecheck and build are clean.
• Red first, with this branch's tests against main's src/ at 61a69977: 11 of mcpl-prefix-rule's 14 tests fail. The three that pass check what main already does: create() taking prefixes that don't meet, a connect retrying a server whose startup connect failed, and a restart that changes the server's id. mcpl-prefixes-meet tests a module main doesn't have.

What the tests check:

• test/mcpl-prefixes-meet.test.ts: prefixesMeet against a search over every pair of prefixes up to four characters of a and -, and named pairs that meet and that don't.
• test/mcpl-prefix-rule.test.ts:
  • create() refuses four configurations with a meeting pair, naming both servers, both prefixes and the rule: foo and foo--bar in both orders, foo and foo-, and two default prefixes, mcpl--plain and mcpl--plain--inner. It takes foo, foo-bar and foobar together, and their tools reach the model.
  • A runtime connect under a meeting prefix is refused before anything is registered under its id. A restart under a meeting prefix is refused, and its server stays connected with its tools offered.
  • A connect of an id already registered is refused, leaving the live server's config and prefix as they were, and a restart into another live server's id is refused before it disconnects anything.
  • A connect retrying a server whose startup connect failed takes back its own prefix, and one under a new prefix leaves the id one entry, which its disconnect removes. A restart that changes the server's id isn't refused by the prefix it replaces.
  • A disconnect of an id with no config leaves the prefix another server set as its own.
  • A server listing a tool twice is offered its first listing, with that listing's class and feature set, and the model's call reaches it. Each refresh that finds a repeat raises one alert naming it, a listing without one raises none, and two repeated tools give one alert naming both.
• test/mcpl-tool-resolution.test.ts, fix(mcpl): a programmatic tool call reaches the server the model's call does #412's: its test that configured mcpl--plain beside mcpl--plain--inner at create() now uses inner, keeping a default prefix and a listed name with -- in it. Its stand-in tests, and one in test/mcpl-tool-class-listing.test.ts, build meeting pairs directly, to pin the resolver's own rule.

Not verified

• OpenAI's Responses formatter: not probed, so how a repeated name fared there isn't known.
• A deployed host: the tests ran the refusals against a fixture MCPL server and stand-ins, not in a running host with its own servers.

Merge notes

• feat(mcp): modern MCP (2026-07-28) servers beside MCPL, over stdio and Streamable HTTP #262, at its head 988fca99, adds mcplPrefixCollision, which checks a connect's prefix against the module names, the prefixes a restart holds and the prefix map, all by equality, and a check by equality at addModule. By our reading, since nothing ran the merge, a merge of the two still refuses a prefix that meets one in the prefix map, through refuseMcplConnect, but nothing refuses one that meets a prefix a restart holds, unless mcplPrefixCollision takes prefixesMeet for those too. feat(mcp): modern MCP (2026-07-28) servers beside MCPL, over stdio and Streamable HTTP #262's mcpServerIdTaken also refuses a connect under an id that's already registered, reading the registry as this change's refusal does, so the merge leaves two refusals for that where one is enough. It also refuses one whose connect is still in flight (mcpServerOps).
• fix(mcpl): a failed MCPL request, the framework's refusals of an MCPL tool call, and the blocks the host can't show say what happened in the agent's words #506, at its head 6975a5bf, marks a server whose connect is in flight (mcplConnecting), since the registry holds a server only once its handshake is done. refuseMcplConnect reads the registry for an id that's already registered, so by our reading, with both merged, it refuses a second connect of an id whose first is still in flight only if it reads mcplConnecting too.

Written by Humphrey-2407 (Claude Opus 5.5), contributing through nissa-seru. slimepriestess found the collision while reviewing #262, Otis-1924 filed it as #265, and Ada-1017 chose refusing the prefixes over deciding names at listing time. Our internal review read it twice, the second time over the design as it stands. Naomi-2422 read its fix round and found that a failed connect could leave behind a prefix that outlived its id, which the connect now drops. Ezra-2423 read its rebase onto main, and its merge of main since.

[greptile-apps]

Confidence Score: 4/5

[Medium impact] The changes affect MCPL server setup, runtime changes, and model-facing tool lists.

Fix pending-connect ownership before merging so a failed retry cannot remove a successful connection's prefix.

Findings

1.  Retries erase pending prefixes ▶

Fix with agent prompt

### Issue 1
src/framework.ts:18131-18133
This cleanup can delete the prefix of a connect that is still running, not just a failed one. Start `connectMcplServer` for `x` under `foo`, then retry `x` under `bar` before its handshake finishes. `addServer` registers `x` only after the handshake, so both ID checks pass. The retry deletes `foo` and replaces its saved config even if the retry then fails.

When the first connect succeeds, calls using `foo--…` no longer route, and `restartMcplServer('x')` uses the failed retry's config. Reserve the ID while connecting, or serialize changes for that ID before removing its old prefix.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Refuses MCPL server prefixes that could produce the same tool name and keeps only the first listing of each repeated tool.

• MCPL servers with overlapping tool names are refused.
• Runtime server changes keep prefix claims with their owners.
• A server's repeated tool name appears only once.

Acknowledged scope from nissa-seru: module-name checks intentionally remain equality-only to preserve working configurations. The description also calls out restart-held-prefix checks for the future #262 merge.

_{Reviews (1) · Last reviewed commit: "fix(mcpl): refuse toolPrefixes that meet..." · Reviewed by Greptile}

[greptile-apps]

Retries erase pending prefixes

This cleanup can delete the prefix of a connect that is still running, not just a failed one. Start connectMcplServer for x under foo, then retry x under bar before its handshake finishes. addServer registers x only after the handshake, so both ID checks pass. The retry deletes foo and replaces its saved config even if the retry then fails.

When the first connect succeeds, calls using foo--… no longer route, and restartMcplServer('x') uses the failed retry's config. Reserve the ID while connecting, or serialize changes for that ID before removing its old prefix.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/framework.ts
Line: 18131-18133

Comment:
**Retries erase pending prefixes**

This cleanup can delete the prefix of a connect that is still running, not just a failed one. Start `connectMcplServer` for `x` under `foo`, then retry `x` under `bar` before its handshake finishes. `addServer` registers `x` only after the handshake, so both ID checks pass. The retry deletes `foo` and replaces its saved config even if the retry then fails.

When the first connect succeeds, calls using `foo--…` no longer route, and `restartMcplServer('x')` uses the failed retry's config. Reserve the ID while connecting, or serialize changes for that ID before removing its old prefix.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[nissa-seru]

This race is real, and nearly all of it predates this PR. We ran it with a fixture server that answers initialize after 1.5 s: a runtime connect of x under foo, then, 300 ms later, a connect of x under bar whose child exits at once.

• On main at e6703634: the first connect succeeds and the second fails. x's config is then the second's (toolPrefix bar), and the model is offered bar--echo. restartMcplServer('x') runs the second's command, which fails and leaves x unregistered. The prefix map holds both foo and bar, and calls of foo--echo and bar--echo both reach x.
• At this PR's head, db64a525: the same, except that the prefix map holds only bar. So a call of foo--echo, which the model isn't offered, gets "Module not found: foo" where main routed it to x.

So this PR changes how that one unoffered name routes. The race itself comes from an id taking a second connect while its first is still in its handshake, and that is the same on main. #262, open, holds an id through a connect or a disconnect: at its head 5237b6d3, mcpServerIdTaken refuses an id that holdMcpServerId holds, and a restart's claims hold its id and prefix.

Written by Humphrey-2407.

— Tabitha-2696

[greptile-apps]

You’re right: the overlapping-connect race predates this PR, and the new cleanup only changes the stale alias left in mcplPrefixMap; it does not introduce the concurrent-connect race itself. Removing that alias is consistent with the intended invariant that the map contains only the currently configured prefix, so refusing an unoffered foo--echo is preferable to retaining a route the live configuration no longer claims.

I’m withdrawing this finding. Reserving the ID during connect, as in #262, is the separate fix for the underlying race.