docs: document Amplifier-side MCP prerequisites in port plan#508
Conversation
The MCP injection was failing silently: besides tool-mcp needing to be mounted in the user's bundle, the mcp Python SDK must be installed in Amplifier's venv. Mount failures are swallowed as warnings, which looks identical to 'no servers configured'. Also correct the discovery-chain description: config sources are merged, not a fallback chain. Verified end-to-end 2026-07-06: freshell-spawned Amplifier session mounts mcp_freshell_freshell. Generated with Amplifier Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cfc6da9e4a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ```yaml | ||
| modules: | ||
| tools: | ||
| - module: tool-mcp | ||
| source: git+https://github.com/microsoft/amplifier-module-tool-mcp@main | ||
| ``` |
There was a problem hiding this comment.
When users follow this ~/.amplifier/settings.yaml snippet to satisfy the documented prerequisite, Amplifier will not mount tool-mcp: the Microsoft module-resolution spec documents settings.yaml module source overrides under sources: <module-id>: <source-uri-or-object>, while tools: entries are bundle/frontmatter config, not a modules.tools settings key. The supported user-level path in the tool-mcp README is the amplifier bundle add ... --app command already mentioned below, so keeping this snippet makes the MCP setup look complete while Freshell still gets no MCP tools.
Useful? React with 👍 / 👎.
2 participants
What changed
Rewrote the "MCP — KNOWN LIMITATION" section of
docs/port-plan.mdas "MCP — Amplifier-side prerequisites". Single-file docs change.Why
The MCP injection was failing silently. There are two Amplifier-side prerequisites, not one:
tool-mcpmust be mounted in the user's bundle (~/.amplifier/settings.yamlmodules.toolsentry, or app bundle).mcpPython SDK must be installed in Amplifier's venv —tool-mcpimports it at mount time, and Amplifier swallows mount failures as silent warnings, which looks identical to "no servers configured". Durable fix:uv tool install "git+https://github.com/microsoft/amplifier@main" --with "mcp>=1.0.0" --force.Also corrects the discovery-chain description: config sources are merged (inline > env > project > user), not a fallback chain — so
~/.amplifier/mcp.jsonmust stay nonexistent to preserve the "no MCPs outside freshell" property.How to verify
Docs-only. Verified end-to-end on the dev machine 2026-07-06: env var injected → tool-mcp reports
servers seen: ['freshell']→ session tool roster includesmcp_freshell_freshell.Breaking changes
None.
Generated with Amplifier
Co-Authored-By: Amplifier 240397093+microsoft-amplifier@users.noreply.github.com