marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add MCP Apps (SEP-1865) documentation

Browse source 
Integrate comprehensive documentation for MCP Apps, the first official
MCP extension enabling interactive UI delivery.

Changes:
- guide/architecture.md (656): New section "MCP Extensions: Apps"
  - Technical architecture (primitives, SDK, security)
  - Platform support (Claude Desktop, VS Code, ChatGPT, Goose)
  - Example implementations (9 production tools at launch)
  - Developer workflow and SDK usage
  - ~150 lines of technical documentation

- guide/ultimate-guide.md (6509): New section "MCP Evolution: Apps"
  - User context and use cases
  - Available interactive tools (Asana, Slack, Figma, etc.)
  - Platform support matrix
  - Hybrid workflow examples
  - ~90 lines of user-facing documentation

- guide/ultimate-guide.md (7522): Table update
  - Added "Interactive UI" row to Plugin vs. MCP Server comparison
  - Clarified MCP Apps = "What Claude can show"

- machine-readable/reference.yaml: 8 new entries
  - mcp_apps_architecture, mcp_apps_evolution
  - Links to spec, SDK, blog posts
  - CLI relevance note (indirect)

- docs/resource-evaluations/mcp-apps-announcement.md: New evaluation
  - Score: 4/5 (High Value - Integrate within 1 week)
  - Fact-checked with Perplexity searches
  - Technical review by agent

Resource evaluated:
- https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/
- https://claude.com/blog/interactive-tools-in-claude

Total documentation: ~240 lines across 3 files
Score: 4/5 (High Value)
CLI relevance: Indirect (ecosystem understanding, MCP server dev, hybrid workflows)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX 2026-01-27 08:14:49 +01:00
parent 3a7671ac5e
commit 18ea240e12
4 changed files with 482 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

205
guide/architecture.md
View file

@ -654,6 +654,211 @@ MCP (Model Context Protocol) servers extend Claude Code with additional tools.
→ **Cross-reference**: See [Section 8.6 - MCP Security](./ultimate-guide.md#86-mcp-security) for security considerations.
### MCP Extensions: Apps (SEP-1865)
**Status**: Stable (January 26, 2026)
**Spec**: [SEP-1865 on GitHub](https://github.com/modelcontextprotocol/ext-apps)
**Co-authored by**: OpenAI, Anthropic, MCP-UI creators
#### What Are MCP Apps?
MCP Apps is the **first official extension** to the Model Context Protocol, enabling MCP servers to deliver **interactive user interfaces** alongside traditional tool responses.
**The problem solved**: Traditional text-based responses create friction for workflows requiring exploration. Each interaction (sort, filter, drill-down) demands a new prompt cycle. MCP Apps eliminates this "context gap" by rendering interactive UIs directly in the conversation.
#### Technical Architecture
**Two core primitives**:
1. **Tools with UI metadata**:
```json
{
"name": "query_database",
"description": "Query customer database",
"_meta": {
"ui": {
"resourceUri": "ui://dashboard/customers"
}
}
}
```
2. **UI Resources** (`ui://` scheme):
- Server-side HTML/JavaScript bundles
- Rendered in sandboxed iframes by host
- Bidirectional JSON-RPC communication via `postMessage`
**Communication flow**:
```
┌─────────────────────────────────────────────────────────┐
│ MCP APPS ARCHITECTURE │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ MCP Client │◄───────►│ MCP Server │ │
│ │ (Claude/IDE) │ JSON-RPC│ (Your App) │ │
│ └──────┬───────┘ └──────────────┘ │
│ │ │
│ │ Fetches ui:// resource │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ Sandboxed Iframe (UI Render) │ │
│ │ ┌───────────────────────────────────┐ │ │
│ │ │ HTML/JS Bundle from Server │ │ │
│ │ │ - Interactive dashboard │ │ │
│ │ │ - Forms with validation │ │ │
│ │ │ - Real-time data visualization │ │ │
│ │ └───────────────────────────────────┘ │ │
│ │ │ │
│ │ postMessage ◄─────► JSON-RPC │ │
│ └─────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
#### Security Model
**Multi-layered protection**:
| Layer | Protection |
|-------|------------|
| **Iframe sandbox** | Restricted permissions (no direct system access) |
| **Pre-declared templates** | Hosts review HTML/JS before rendering |
| **Auditable messaging** | All UI-to-host communication via JSON-RPC logs |
| **User consent** | Optional requirement for UI-initiated tool calls |
| **Content blocking** | Hosts can reject suspicious resources pre-render |
→ **Cross-reference**: See [Section 8.6 - MCP Security](./ultimate-guide.md#86-mcp-security) for broader MCP security considerations.
#### SDK: @modelcontextprotocol/ext-apps
**Installation**:
```bash
npm install @modelcontextprotocol/ext-apps
```
**Core API** (framework-agnostic):
```typescript
import { App } from '@modelcontextprotocol/ext-apps';
const app = new App();
// 1. Establish communication with host
await app.connect();
// 2. Receive tool results from host
app.ontoolresult = (result) => {
// Update UI with tool execution results
updateDashboard(result.data);
};
// 3. Call server tools from UI
await app.callServerTool('fetch_analytics', {
timeRange: '7d',
metrics: ['users', 'revenue']
});
// 4. Update model context asynchronously
await app.updateModelContext({
selectedFilters: ['region:EU', 'status:active']
});
// Additional capabilities:
app.logDebug('User action', { filter: 'applied' });
app.openBrowserLink('https://docs.example.com');
app.sendFollowUpMessage('Applied filters: EU, Active');
```
**Standard communication**: All features operate over `postMessage` (no framework lock-in).
#### Platform Support
| Platform | MCP Apps Support | Notes |
|----------|------------------|-------|
| **Claude Desktop** | ✅ Available now | claude.ai/directory (Pro/Max/Team/Enterprise) |
| **Claude Cowork** | 🔄 Coming soon | Agentic workflow integration planned |
| **VS Code** | ✅ Insiders build | [Official blog post](https://code.visualstudio.com/blogs/2026/01/26/mcp-apps-support) |
| **ChatGPT** | 🔄 Rolling out | Week of Jan 26, 2026 |
| **Goose** | ✅ Available now | Open-source CLI with UI support |
| **Claude Code CLI** | ❌ N/A | Terminal text-only (no iframe rendering) |
#### Relevance for Claude Code Users
**Direct usage**: None (CLI is text-only, cannot render iframes)
**Indirect benefits**:
1. **Ecosystem understanding**: MCP Apps represents the future of agentic workflows
2. **MCP server development**: If building custom MCP servers, Apps is now a design option
3. **Hybrid workflows**:
- Use Claude Desktop to explore data with Apps (dashboards, visualizations)
- Switch to Claude Code CLI for implementation (scripting, automation)
4. **Context for configuration**: MCP servers may advertise UI capabilities in metadata
#### Example Implementations
**Official example servers** (in [`ext-apps` repository](https://github.com/modelcontextprotocol/ext-apps)):
- **threejs-server**: 3D visualization and manipulation
- **map-server**: Interactive geographic data exploration
- **pdf-server**: Document viewing with inline highlights
- **system-monitor-server**: Real-time metrics dashboards
- **sheet-music-server**: Music notation rendering
**Production adoption** (January 2026):
| Tool | Provider | Capabilities |
|------|----------|--------------|
| Asana | Atlassian | Project timelines, task boards |
| Slack | Salesforce | Message drafting with formatting preview |
| Figma | Figma | Flowcharts, Gantt charts in FigJam |
| Amplitude | Amplitude | Analytics charts with interactive filtering |
| Box | Box | File search, document previews |
| Canva | Canva | Presentation design with real-time customization |
| Clay | Clay | Company research, contact discovery |
| Hex | Hex | Data analysis with interactive queries |
| monday.com | monday.com | Work management boards |
**Coming soon**: Salesforce (Agentforce 360)
#### Relationship to Prior Work
MCP Apps standardizes patterns pioneered by:
- **MCP-UI**: Early UI extension for MCP (community project)
- **OpenAI Apps SDK**: Parallel effort for interactive tools
Both frameworks continue to be supported. MCP Apps provides a **unified specification** (SEP-1865) co-authored by maintainers from both ecosystems plus Anthropic and OpenAI.
**Migration path**: Straightforward for existing MCP-UI and Apps SDK implementations.
#### When to Use MCP Apps
**Decision tree for MCP server developers**:
```
Building a custom MCP server?
├─ Users need to SELECT from 50+ options? → MCP Apps (dropdown, multi-select UI)
├─ Users need to VISUALIZE data patterns? → MCP Apps (charts, maps, graphs)
├─ Users need MULTI-STEP workflows with conditional logic? → MCP Apps (wizard forms)
├─ Users need REAL-TIME updates? → MCP Apps (live dashboards)
└─ Simple data retrieval or actions only? → Traditional MCP tools (sufficient)
```
**Trade-off**: UI complexity and implementation effort vs. user experience improvement.
#### Resources
- **Specification**: [SEP-1865 on GitHub](https://github.com/modelcontextprotocol/ext-apps)
- **SDK**: [`@modelcontextprotocol/ext-apps` (npm)](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps)
- **Example servers**: [modelcontextprotocol/ext-apps repository](https://github.com/modelcontextprotocol/ext-apps)
- **Blog post (MCP)**: [MCP Apps announcement](https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/)
- **Blog post (Claude)**: [Interactive tools in Claude](https://claude.com/blog/interactive-tools-in-claude)
- **VS Code**: [MCP Apps support announcement](https://code.visualstudio.com/blogs/2026/01/26/mcp-apps-support)
---
### MCP Tool Search (Lazy Loading)
**Confidence**: 100% (Tier 1 - Official)

108
guide/ultimate-guide.md
View file

@ -6507,6 +6507,110 @@ MCP (Model Context Protocol) is a standard for connecting AI models to external
└─────────────────────────────────────────────────────────┘
```
### MCP Evolution: Apps Extension (SEP-1865)
> **🆕 Since January 2026**: MCP can now deliver interactive UIs alongside traditional text responses.
#### The Context Gap Problem
Traditional AI interactions require repeated prompts for data exploration:
**Without MCP Apps**:
```
You: "Show me customer data"
Claude: "Here are 500 customers [text list]"
You: "Sort by revenue"
Claude: "Here's the sorted list [text]"
You: "Filter to last 30 days"
Claude: "Here's the filtered list [text]"
You: "Show me the top 10"
... (multiple prompt cycles)
```
**With MCP Apps**:
```
You: "Show me customer data"
Claude: [Renders interactive dashboard with sorting, filtering, date pickers]
You: [Sort, filter, drill-down directly in UI - no additional prompts]
```
#### What Are MCP Apps?
MCP Apps enable MCP servers to deliver **interactive interfaces** that render directly in your conversation:
- **Dashboards**: Charts with filtering, drill-down, export
- **Configuration wizards**: Forms with dependent fields and validation
- **Document viewers**: PDFs with inline highlights and annotations
- **Real-time monitors**: Live metrics updating without re-running tools
#### Available Interactive Tools
**At launch** (January 26, 2026), **9 interactive tools** are available:
| Tool | What It Does |
|------|--------------|
| **Asana** | Create project timelines, manage tasks visible to teams |
| **Slack** | Draft formatted messages with preview before posting |
| **Figma** | Convert text into flowcharts, Gantt charts in FigJam |
| **Amplitude** | Build analytics charts, explore trends interactively |
| **Box** | Search files, preview documents inline |
| **Canva** | Create presentations with real-time design customization |
| **Clay** | Research companies, find contacts, draft outreach |
| **Hex** | Query data with interactive charts and tables |
| **monday.com** | Manage work, update boards, visualize progress |
**Coming soon**: Salesforce (Agentforce 360), Claude Cowork integration
→ **Access**: [claude.ai/directory](https://claude.ai/directory) (Pro/Max/Team/Enterprise plans)
#### Platform Support
| Platform | Support | How to Use |
|----------|---------|------------|
| **Claude Desktop** | ✅ Now | claude.ai/directory - connect interactive tools |
| **Claude Cowork** | 🔄 Coming | Agentic workflows with file/project access |
| **VS Code** | ✅ Insiders | Install Insiders build, configure MCP Apps |
| **ChatGPT** | 🔄 Rollout | Week of Jan 26, 2026 |
| **Goose** | ✅ Now | Open-source alternative with UI support |
| **Claude Code CLI** | ❌ No | Terminal is text-only (no UI rendering) |
#### Why This Matters for CLI Users
**Direct impact**: **None** - Claude Code CLI cannot render interactive UIs in the terminal.
**Indirect benefits**:
1. **Ecosystem awareness**: Understand where MCP is heading (interactive agentic workflows)
2. **Hybrid workflows**: Use Claude Desktop for visual exploration → Claude Code CLI for automation
3. **MCP server development**: If building custom servers, Apps is now an option
4. **Context for tools**: Some MCP servers may advertise UI capabilities (visible in metadata)
**Example hybrid workflow**:
```
1. Claude Desktop: Use Amplitude MCP App to explore analytics interactively
2. Identify patterns visually (e.g., "EU region shows 30% growth")
3. Claude Code CLI: Automate data export and reporting based on findings
```
#### Technical Foundation
MCP Apps is built on the **Model Context Protocol** (open standard by Anthropic):
- **Open specification**: [SEP-1865 on GitHub](https://github.com/modelcontextprotocol/ext-apps)
- **Co-authored by**: OpenAI, Anthropic, MCP-UI creators
- **SDK**: `@modelcontextprotocol/ext-apps` (npm)
- **"Build once, deploy everywhere"**: Works in Claude, VS Code, ChatGPT, Goose
→ **Deep dive**: See [guide/architecture.md:656](./architecture.md#mcp-extensions-apps-sep-1865) for technical architecture, security model, and SDK details.
#### Resources
- **MCP Apps blog post**: [Anthropic announcement](https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/)
- **Interactive tools blog**: [Claude announcement](https://claude.com/blog/interactive-tools-in-claude)
- **Official spec**: [SEP-1865 on GitHub](https://github.com/modelcontextprotocol/ext-apps)
---
## 8.2 Available Servers
<details>
@ -7519,10 +7623,14 @@ Understanding when to use which:
| **Scope** | Claude Code instructions and patterns | External system integrations |
| **Installation** | `claude plugin install` | Add to `settings.json` MCP config |
| **Use case** | Security auditor agent, code review workflows | PostgreSQL access, Playwright browser automation |
| **Interactive UI** | No | Yes (via MCP Apps extension - SEP-1865)* |
**Rule of thumb:**
- **Plugin** = "How Claude thinks" (new workflows, specialized agents)
- **MCP Server** = "What Claude can do" (new tools, external systems)
- **MCP Apps** = "What Claude can show" (interactive UIs in supported clients)*
*Note: MCP Apps render in Claude Desktop, VS Code, ChatGPT, Goose. Not supported in Claude Code CLI (terminal is text-only). See [Section 8.1](#81-what-is-mcp) for details.
### Security Considerations