Overview
Building a useful MCP app requires more than placing branded interface components inside Claude or ChatGPT. Drawing on Indeed’s work across external assistants and its internal Career Scout agent, Dustin Macholic explains that conventional text-based MCP tools often support sophisticated workflows surprisingly well: a model can run many searches, filter results, compare options, and synthesize a final answer. A naïvely integrated UI can weaken that capability by hiding API-loaded information from the model or discouraging repeated tool calls. The first remedy is data parity: everything visible to the user must also be returned as structured model-readable content, and user interactions such as opening a job must update the model’s context. Tool descriptions must then clarify that results have already been rendered, preventing redundant prose. The most important architectural move is to separate data processing from UI rendering. Search tools should remain reusable, text-oriented exploration mechanisms, while a render tool receives only the selected records or references after the model has completed its analysis. This pattern preserves deep agentic exploration while enabling controlled branding, links, actions, and richer presentation. The resulting design principle is data-first and composable: expose small tools for retrieving and transforming information, then treat rendering as the final consequence of the model’s reasoning.
Sections
Lessons From Production MCP App Work
Practical principles derived from building job-search experiences for multiple chat environments.
- Design the model-readable data contract before designing the embedded interface.
- Maintain parity between visible application state and the structured information available to the model.
- Use tool descriptions to establish whether the UI or the assistant's prose is responsible for presenting detailed results.
- Preserve the model's ability to make repeated exploratory calls before asking it to render a final selection.
- Treat rendering as the result of analysis rather than the automatic consequence of retrieval.
Implementation Details
Specific mechanisms and tool boundaries described for MCP app integration.
- Return structured content for model reasoning together with a resource URI that identifies the HTML interface.
- Use update model context to report interaction-derived state, such as the item a user opened or the contents of a shopping cart.
- For MCP apps, interaction context is passed as a single string; retaining multiple events may require appending their representations to that string.
- Keep search_jobs as a non-rendering retrieval tool and use a separate render_jobs_widget tool that accepts selected job IDs.
- Render-tool descriptions should specify which retrieval tools must run first and the format of the data supplied for rendering.
- A render contract may accept an item ID plus model-generated fields such as a selection rationale or a highlighted source passage.
Risks and Pitfalls
Failure modes that can degrade reasoning quality, conversational continuity, or user experience.
- Loading data only inside embedded HTML prevents the model from answering follow-up questions about visible results.
- Failing to report UI interactions leaves the model unaware of which item or detail view the user selected.
- Attaching UI rendering to every search call can discourage the model from running the multiple searches required for complex tasks.
- Without descriptive guidance, the assistant may duplicate the UI by restating all rendered results in prose.
- Large, multipurpose tools can overload the model with complex descriptions and reduce flexibility.
- Model-generated rationales or highlights may become ungrounded if the render tool accepts commentary without retaining source data.
Broader Architectural Insights
Implications synthesized from the described MCP app design patterns.
- In agent interfaces, observability is bidirectional: the user must see useful state, and the model must receive an equivalent machine-readable view of that state.
- A richer interface can paradoxically make an agent less capable when presentation side effects discourage iterative tool use.
- The render tool functions as a semantic compression boundary: the model explores a large candidate space, then commits only the most relevant subset to the user's visual attention.
- MCP app quality depends less on reproducing an existing website inside chat and more on redesigning the product as composable data and action capabilities.