docs: clarify the two MCP integration paths (server vs. client)

[psschwei]

Problem

Mellea's documentation currently has two separate pages about MCP, and they describe opposite directions of integration. A user landing on either page may not realize the other exists, or may assume one supersedes the other.

Page	Direction	Use case
integrations/mcp — "MCP Integration"	Mellea as an MCP server — expose Mellea functions as tools for Claude Desktop, Cursor, etc.	You have a Mellea program and want external MCP clients to call it.
how-to/tools-and-agents#mcp-tools — "MCP tools" section	Mellea as an MCP client — consume tools from external MCP servers (added in v0.6, #1042).	You want Mellea agents to use tools hosted by GitHub, etc.

This came up in mellea-website#50 (comment) while reviewing the v0.6 MCP-client blog post — the older page is still valid for the server-side feature, but the two pages don't reference each other and don't frame themselves as "directions" of the same integration.

Suggestions

• Add a short orientation block at the top of each page explaining the two directions and linking to the other.
• Consider consolidating under a single integrations/mcp landing page with two sub-sections ("Mellea as an MCP server" / "Mellea as an MCP client") — moving the client-side content out of tools-and-agents may improve discoverability for users searching specifically for "MCP".
• Make sure each page's description frontmatter disambiguates the direction (e.g., "Expose Mellea functions as MCP tools…" vs. "Consume tools from MCP servers in Mellea agents…").

Notes

• Both features are functional and documented; this is a docs-clarity issue, not a code bug.
• The v0.6 blog post (mellea-website#50) covers the new client-side direction.

[ajbozarth]

So before I saw that you opened this I opened #1110 but that only addresses part of what you outlined. I updated my PR to close this because I'm not sure we should or need to do the other changes. I had Claude summarize my reasoning for each item below. If you want I can add those to my PR though, I'm only personally string against the consolidation idea.

---

• Orientation block on tools-and-agents too — leaning against. The MCP tools section is mid-page within a general tools doc, and a top-of-page callout would be noise for the larger audience reading about @tool, react(), etc. The callout on integrations/mcp is the asymmetric case because that whole page is about one direction.
• Consolidate into a single MCP landing page — also leaning against. Pulling MCP-client out of tools-and-agents orphans it from its natural context — users learning to give agents tools naturally want the MCP example inline next to @tool and react(). The discoverability problem is solved by the callout without the structural cost.
• Disambiguate description frontmatter — already done on integrations/mcp ("Expose Mellea functions as MCP tools…"); on tools-and-agents the description is page-level and shouldn't be MCP-specific. Also worth noting: Mintlify's search snippet comes from body content, not frontmatter, so this wouldn't change search results anyway.

[psschwei]

Orientation block on tools-and-agents too — leaning against. The MCP tools section is mid-page within a general tools doc, and a top-of-page callout would be noise for the larger audience reading about @tool, react(), etc. The callout on integrations/mcp is the asymmetric case because that whole page is about one direction.

What about just at the beginning of the MCP section?

• Consolidate into a single MCP landing page — also leaning against. Pulling MCP-client out of tools-and-agents orphans it from its natural context — users learning to give agents tools naturally want the MCP example inline next to @tool and react(). The discoverability problem is solved by the callout without the structural cost.

With the docs as they are now, I agree. But it's also worth considering if the newer content on using MCPs in Mellea may warrant a more broader content reorg.

No real opinions here, will defer to you.

[ajbozarth]

What about just at the beginning of the MCP section?

I did investigate that and it just felt off, the section reads as part of the tools page and if a user ends up on the tools page they're looking for tools. Which is distinct from if a user ends up on MCP Integration page and is looking for MCP server tools usage instead