| name | mcp-protocol |
| description | This skill should be used when the user asks about MCP protocol details,
needs to "design MCP tools", "understand MCP architecture", "configure
MCP transport", "set up MCP authentication", "implement MCP tasks",
"handle MCP security", "debug MCP protocol errors", "understand
structuredContent vs content", or needs specification-level knowledge
for building or debugging MCP servers and applications.
|
MCP Protocol Reference
The Model Context Protocol (MCP) is an open protocol (spec revision 2025-11-25) that standardizes how AI applications provide context to LLMs. It uses JSON-RPC 2.0 over defined transports, with a host → client → server architecture.
- Host: The AI application (Claude, VS Code, etc.) that manages client instances
- Client: Maintains a 1:1 stateful session with a server, handles capability negotiation
- Server: Exposes tools, resources, and prompts to the client
Full introduction: https://modelcontextprotocol.io/docs/getting-started/intro
MCP Apps: Why Not Just a Web App?
MCP Apps are extensions that live inside the AI conversation, not separate browser tabs. They solve problems that regular web apps can't:
- Context preservation: The app and LLM share the same conversation context — no copy-pasting between windows
- Bidirectional data flow: The widget can trigger LLM actions, and LLM tool calls update the widget in real time
- Host integration: The app runs inside the host's security sandbox — authentication, permissions, and display are managed by the host
- Two audiences: Every tool serves both the human (via widget UI) and the LLM (via text content) simultaneously
When to use an MCP App vs a plain MCP tool:
- Plain tool: The LLM only needs text data (search results, API responses, file contents)
- MCP App: The user needs to see, interact with, or manipulate rich data (dashboards, forms, editors, visualizations)
More: https://modelcontextprotocol.io/docs/extensions/apps
How MCP Apps Work
- Tool declares
_meta.ui.resourceUri pointing to a ui:// resource containing the bundled HTML
- Host preloads the UI resource when the server connects
- When the tool is called, the host renders the widget in a sandboxed iframe
- Communication between widget and host uses postMessage (never direct DOM access)
Data flow in tool responses:
| Field | Audience | Purpose |
|---|
structuredContent | Widget + LLM | JSON data the widget renders and the LLM can reason about |
content | LLM only | Text fallback for hosts that don't support MCP Apps |
_meta | Widget only | Large data (images, binary) that the LLM doesn't need to see |
The widget receives structuredContent merged with _meta. The LLM receives structuredContent (as JSON text) plus content (as natural language text).
What's New in Spec 2025-11-25
Key additions over the previous revision:
- Tasks: Durable state machines for long-running async operations (experimental)
- URL elicitation: Servers can redirect users to external URLs for complex auth flows
- Sampling with tools: LLM sampling requests can now include tool definitions and tool calls
- Client ID Metadata Documents: Recommended mechanism for client identity verification
- JSON Schema 2020-12: Updated from Draft 7 for input/output schemas
- Icons: Servers and tools can declare sized icons (PNG, JPEG, SVG, WebP) with theme support
- Incremental scope consent: OAuth scopes can be requested progressively via WWW-Authenticate
- Tool names: Expanded allowed characters (letters, digits, underscores, hyphens, dots, slashes)
- Elicitation schema: Added title/default fields, URL requestType
Full changelog: https://modelcontextprotocol.io/specification/2025-11-25/changelog
Quick Reference: All Capabilities
Server Capabilities
| Capability | Key Methods | Purpose |
|---|
tools | tools/list, tools/call | Executable functions the LLM can invoke |
resources | resources/list, resources/read, resources/subscribe | URI-identified read-only data |
prompts | prompts/list, prompts/get | Reusable prompt templates |
logging | notifications/message | Structured log messages to client |
completions | completion/complete | Argument autocompletion |
extensions | Per-extension | Vendor-prefixed protocol extensions |
Client Capabilities
| Capability | Key Methods | Purpose |
|---|
sampling | sampling/createMessage | Server requests LLM completion (with tool support) |
elicitation | elicitation/create | Server requests user input (form or URL redirect) |
roots | roots/list | Filesystem roots the server may access |
extensions | Per-extension | Vendor-prefixed protocol extensions |
Server concepts: https://modelcontextprotocol.io/docs/learn/server-concepts
Reference Files
Detailed reference material organized by topic. Each file covers a specific area of the MCP specification.
Protocol & Architecture
- Protocol Fundamentals — Host/client/server architecture, lifecycle, capability negotiation, JSON-RPC message types, error codes, extensions framework. Use when debugging connection issues, understanding init handshake, or working with protocol extensions.
Extensions & Apps
- MCP Apps & Extensions — When to use MCP Apps vs plain tools,
structuredContent/content/_meta decision guide, security model, cross-host support, display modes, extension negotiation. Use when deciding how to structure tool responses or understanding iframe sandbox behavior.
Tools & Resources
- Tool Design — Tool schema, annotations (
readOnlyHint, destructiveHint, etc.), naming rules, input/output schemas, error handling, content types, task support. Use when defining new tools or setting appropriate annotations.
- Resource Design — URI-identified data, static vs template resources, URI schemes, annotations, subscriptions,
ui:// pattern for MCP Apps. Use when exposing data or implementing the UI resource pattern.
Transport & Connection
- Transport & Connection — stdio vs Streamable HTTP, Express setup, session management, resumability, CORS, cloudflared tunneling. Use when configuring server transport or debugging connection issues.
Async & Tasks
- Tasks & Async — Experimental durable state machines for long-running operations, two-phase responses, lifecycle states, polling, TTL. Use when implementing async workflows that outlive a single request-response cycle.
Auth & Security
- Authorization — OAuth 2.1 for HTTP transports, discovery chain, Client ID Metadata Documents, PKCE flow, incremental scope consent. Use when implementing authenticated MCP servers.
- Security — Confused deputy attacks, SSRF protection, session hijacking, DNS rebinding, input validation, MCP Apps sandbox security, pre-deployment checklist. Use for security review before deploying any MCP server.
Relationship to mcp-app-builder
/mcp-app-builder covers the Skybridge framework: widgets, state management, UI hooks, deployment to Alpic, OAuth implementation, CSP configuration. It's the tool for building./mcp-protocol (this skill) covers the MCP specification: protocol fundamentals, transport details, tool/resource design at the spec level, authorization flows, security model. It's the reference for understanding.
Use together: /mcp-app-builder for "how do I build this?" and /mcp-protocol for "how does the protocol work?"
Full Specification Index
All specification pages: https://modelcontextprotocol.io/llms.txt
