MCP Expert
Overview
Definitive resource for building and managing Model Context Protocol ecosystems. Covers the full lifecycle from server development and transport configuration to security, elicitation, and async task execution. Designs agent-first tool interfaces that minimize token usage and maximize LLM accuracy.
When to use: Building MCP servers, designing tool interfaces, configuring transports (Stdio/Streamable HTTP), implementing OAuth 2.1, troubleshooting connectivity, using elicitation for server-initiated user interaction.
When NOT to use: Application-level business logic, non-MCP API design, frontend UI components, general HTTP API development unrelated to MCP.
Quick Reference
| Pattern |
API/Approach |
Key Points |
| Outcome-oriented tools |
Single-call operations |
Avoid chatty multi-step APIs |
| Argument flattening |
Flat Zod schemas with descriptions |
Reduce model hallucination |
| Progressive disclosure |
Return mcp:// URIs for large data |
Agent reads partially via resources/read |
| Retryable tools |
Return retry_with suggestions |
Help LLM self-correct on bad inputs |
| Helpful errors |
Descriptive strings with fix guidance |
Never return raw exceptions or stack traces |
| Pagination |
has_more + next_cursor metadata |
20-50 records per call maximum |
| Structured outputs |
JSON Schema in outputSchema |
Typed tool results for programmatic consumption |
| Stdio transport |
Local tools, stderr-only logging |
Never write to stdout except JSON-RPC |
| Streamable HTTP |
Remote/cloud tools, single endpoint |
Replaces deprecated SSE transport |
| OAuth 2.1 with PKCE |
Enterprise data access |
MCP server is resource server, not auth server |
| Elicitation |
Server-initiated user input |
Flat schema maps to forms, three response states |
| Async tasks |
tasks/get, tasks/cancel |
Long-running operations return task handles |
| Capability scopes |
read:docs, write:code, admin:users |
Granular permission boundaries |
| HITL gate |
confirmation_required flag |
Manual approval for destructive actions |
| URL elicitation |
Secure credential collection |
Redirects user to browser for sensitive input |
| Extensions |
Namespaced capability negotiation |
Optional features without forking the spec |
| Sampling with tools |
Server-initiated LLM requests |
Enables server-side agent loops |
| MCP Inspector |
npx @modelcontextprotocol/inspector |
Test tools interactively without an LLM |
| Unit testing |
InMemoryTransport + Vitest |
Test tool handlers with mock client |
| Evaluation framework |
Schema, error, pagination assertions |
Validate tool quality for LLM consumption |
| Tool contract testing |
Schema field descriptions, edge cases |
Every field described, optional params handled |
| CI smoke tests |
GitHub Actions + Inspector CLI |
Automated build, test, and transport health check |
Spec Versions
The current MCP specification is 2025-11-25. Key milestones:
- 2025-03-26: Streamable HTTP transport (deprecated standalone SSE), tool annotations
- 2025-06-18: Structured tool outputs, elicitation, OAuth auth server separation
- 2025-11-25: Async tasks, extensions framework, sampling with tools, CIMD auth, server discovery
Onboarding Protocol
When an agent needs a new capability:
- Validation: Check if the required MCP server is already active
- Guide: If missing, provide the user with a direct installation path
- Config: Use
uvx or npx for zero-install execution where possible
Common Mistakes
| Mistake |
Correct Pattern |
| Designing chatty APIs requiring many round-trips |
Build outcome-oriented tools that accomplish tasks in a single call |
| Logging to stdout breaking the Stdio transport |
Log only to stderr to keep the transport channel clean |
| Returning raw exceptions and stack traces to the LLM |
Return helpful error strings with suggested corrections |
| Building monolithic servers with dozens of tools |
Keep servers focused with 5-15 tools for discoverability and maintenance |
| Using deprecated HTTP+SSE transport for new servers |
Use Streamable HTTP for remote servers (single endpoint, optional SSE) |
| Hardcoding secrets in MCP server configuration |
Use environment variable mapping for all sensitive values |
| Returning large datasets in a single tool call |
Use pagination (20-50 records) or resource URIs for large data |
| Implementing auth server inside MCP server |
MCP server acts as OAuth 2.1 resource server only, delegate auth externally |
| Vague tool descriptions causing LLM hallucination |
Add example usage and strict constraints to the tool description field |
| Synchronous blocking on long operations |
Return async task handles for operations exceeding timeout thresholds |
| Passing received tokens to upstream APIs |
Validate tokens locally; never forward to avoid confused deputy attacks |
| Requesting secrets through elicitation |
Use URL mode elicitation or dedicated OAuth flows for credential collection |
MCP Primitives
MCP servers expose three core primitive types to clients:
- Tools: Model-controlled actions the LLM invokes to accomplish tasks (function calling)
- Resources: Application-controlled data exposed via
mcp:// URIs that clients read on demand
- Prompts: User-controlled templates that provide structured context for specific workflows
Servers declare which primitives they support during capability negotiation in the initialize handshake. The November 2025 spec adds Tasks as an experimental primitive for async execution.
Transport Selection
| Scenario |
Transport |
Notes |
| Local CLI tools |
Stdio |
Fastest startup, no network overhead |
| Remote/cloud servers |
Streamable HTTP |
Single endpoint, optional SSE streaming |
| Legacy remote |
HTTP+SSE |
Deprecated since 2025-03-26, migrate to Streamable HTTP |
Clients should support Stdio whenever possible. Streamable HTTP supports both stateless and stateful server implementations via optional Mcp-Session-Id headers.
Delegation
- Discover and audit existing MCP server configurations: Use
Explore agent to check active servers, verify connectivity, and identify missing capabilities
- Build and deploy a new MCP server with validation and auth: Use
Task agent to scaffold the server, implement Zod validation, and configure OAuth
- Design MCP ecosystem architecture for multi-agent workflows: Use
Plan agent to map tool boundaries, transport selection, and security scoping
References
- Server development, tool design, argument flattening, pagination, and error handling
- Transport configuration: Stdio, Streamable HTTP, and migration from SSE
- Security, OAuth 2.1 integration, elicitation, capability scopes, and HITL gates
- Testing and evaluation: MCP Inspector, unit tests, contract tests, CI integration
- Troubleshooting guide, MCP Inspector, common errors, and transport debugging
1---2name: mcp-expert3description: Architects and orchestrates Model Context Protocol (MCP) ecosystems including server development, tool design, and transport configuration. Use when building MCP servers, designing agentic tool interfaces, configuring MCP transports, implementing OAuth security, or troubleshooting MCP connectivity. Use for outcome-oriented tools, Zod validation, progressive disclosure resources, elicitation, and async tasks.4license: MIT5---6
7# MCP Expert
8
9## Overview
10
11Definitive resource for building and managing Model Context Protocol ecosystems. Covers the full lifecycle from server development and transport configuration to security, elicitation, and async task execution. Designs agent-first tool interfaces that minimize token usage and maximize LLM accuracy.
12
13**When to use:** Building MCP servers, designing tool interfaces, configuring transports (Stdio/Streamable HTTP), implementing OAuth 2.1, troubleshooting connectivity, using elicitation for server-initiated user interaction.
14
15**When NOT to use:** Application-level business logic, non-MCP API design, frontend UI components, general HTTP API development unrelated to MCP.
16
17## Quick Reference
18
19| Pattern | API/Approach | Key Points |
20| ---------------------- | ---------------------------------------- | ------------------------------------------------- |
21| Outcome-oriented tools | Single-call operations | Avoid chatty multi-step APIs |
22| Argument flattening | Flat Zod schemas with descriptions | Reduce model hallucination |
23| Progressive disclosure | Return `mcp://` URIs for large data | Agent reads partially via `resources/read` |
24| Retryable tools | Return `retry_with` suggestions | Help LLM self-correct on bad inputs |
25| Helpful errors | Descriptive strings with fix guidance | Never return raw exceptions or stack traces |
26| Pagination | `has_more` + `next_cursor` metadata | 20-50 records per call maximum |
27| Structured outputs | JSON Schema in `outputSchema` | Typed tool results for programmatic consumption |
28| Stdio transport | Local tools, stderr-only logging | Never write to stdout except JSON-RPC |
29| Streamable HTTP | Remote/cloud tools, single endpoint | Replaces deprecated SSE transport |
30| OAuth 2.1 with PKCE | Enterprise data access | MCP server is resource server, not auth server |
31| Elicitation | Server-initiated user input | Flat schema maps to forms, three response states |
32| Async tasks | `tasks/get`, `tasks/cancel` | Long-running operations return task handles |
33| Capability scopes | `read:docs`, `write:code`, `admin:users` | Granular permission boundaries |
34| HITL gate | `confirmation_required` flag | Manual approval for destructive actions |
35| URL elicitation | Secure credential collection | Redirects user to browser for sensitive input |
36| Extensions | Namespaced capability negotiation | Optional features without forking the spec |
37| Sampling with tools | Server-initiated LLM requests | Enables server-side agent loops |
38| MCP Inspector | `npx @modelcontextprotocol/inspector` | Test tools interactively without an LLM |
39| Unit testing | InMemoryTransport + Vitest | Test tool handlers with mock client |
40| Evaluation framework | Schema, error, pagination assertions | Validate tool quality for LLM consumption |
41| Tool contract testing | Schema field descriptions, edge cases | Every field described, optional params handled |
42| CI smoke tests | GitHub Actions + Inspector CLI | Automated build, test, and transport health check |
43
44## Spec Versions
45
46The current MCP specification is **2025-11-25**. Key milestones:
47
48- **2025-03-26**: Streamable HTTP transport (deprecated standalone SSE), tool annotations
49- **2025-06-18**: Structured tool outputs, elicitation, OAuth auth server separation
50- **2025-11-25**: Async tasks, extensions framework, sampling with tools, CIMD auth, server discovery
51
52## Onboarding Protocol
53
54When an agent needs a new capability:
55
561. **Validation**: Check if the required MCP server is already active
572. **Guide**: If missing, provide the user with a direct installation path
583. **Config**: Use `uvx` or `npx` for zero-install execution where possible
59
60## Common Mistakes
61
62| Mistake | Correct Pattern |
63| ---------------------------------------------------- | --------------------------------------------------------------------------- |
64| Designing chatty APIs requiring many round-trips | Build outcome-oriented tools that accomplish tasks in a single call |
65| Logging to stdout breaking the Stdio transport | Log only to stderr to keep the transport channel clean |
66| Returning raw exceptions and stack traces to the LLM | Return helpful error strings with suggested corrections |
67| Building monolithic servers with dozens of tools | Keep servers focused with 5-15 tools for discoverability and maintenance |
68| Using deprecated HTTP+SSE transport for new servers | Use Streamable HTTP for remote servers (single endpoint, optional SSE) |
69| Hardcoding secrets in MCP server configuration | Use environment variable mapping for all sensitive values |
70| Returning large datasets in a single tool call | Use pagination (20-50 records) or resource URIs for large data |
71| Implementing auth server inside MCP server | MCP server acts as OAuth 2.1 resource server only, delegate auth externally |
72| Vague tool descriptions causing LLM hallucination | Add example usage and strict constraints to the tool description field |
73| Synchronous blocking on long operations | Return async task handles for operations exceeding timeout thresholds |
74| Passing received tokens to upstream APIs | Validate tokens locally; never forward to avoid confused deputy attacks |
75| Requesting secrets through elicitation | Use URL mode elicitation or dedicated OAuth flows for credential collection |
76
77## MCP Primitives
78
79MCP servers expose three core primitive types to clients:
80
81- **Tools**: Model-controlled actions the LLM invokes to accomplish tasks (function calling)
82- **Resources**: Application-controlled data exposed via `mcp://` URIs that clients read on demand
83- **Prompts**: User-controlled templates that provide structured context for specific workflows
84
85Servers declare which primitives they support during capability negotiation in the `initialize` handshake. The November 2025 spec adds **Tasks** as an experimental primitive for async execution.
86
87## Transport Selection
88
89| Scenario | Transport | Notes |
90| -------------------- | --------------- | ------------------------------------------------------- |
91| Local CLI tools | Stdio | Fastest startup, no network overhead |
92| Remote/cloud servers | Streamable HTTP | Single endpoint, optional SSE streaming |
93| Legacy remote | HTTP+SSE | Deprecated since 2025-03-26, migrate to Streamable HTTP |
94
95Clients should support Stdio whenever possible. Streamable HTTP supports both stateless and stateful server implementations via optional `Mcp-Session-Id` headers.
96
97## Delegation
98
99- **Discover and audit existing MCP server configurations**: Use `Explore` agent to check active servers, verify connectivity, and identify missing capabilities
100- **Build and deploy a new MCP server with validation and auth**: Use `Task` agent to scaffold the server, implement Zod validation, and configure OAuth
101- **Design MCP ecosystem architecture for multi-agent workflows**: Use `Plan` agent to map tool boundaries, transport selection, and security scoping
102
103## References
104
105- [Server development, tool design, argument flattening, pagination, and error handling](references/server-development.md)
106- [Transport configuration: Stdio, Streamable HTTP, and migration from SSE](references/transports.md)
107- [Security, OAuth 2.1 integration, elicitation, capability scopes, and HITL gates](references/security-auth.md)
108- [Testing and evaluation: MCP Inspector, unit tests, contract tests, CI integration](references/testing-and-evaluation.md)
109- [Troubleshooting guide, MCP Inspector, common errors, and transport debugging](references/troubleshooting.md)
oakoss