Installation
npx skills add oakoss/agent-skills --skill mcp-expert 35
Installs
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
uvxornpxfor 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
Exploreagent to check active servers, verify connectivity, and identify missing capabilities - Build and deploy a new MCP server with validation and auth: Use
Taskagent to scaffold the server, implement Zod validation, and configure OAuth - Design MCP ecosystem architecture for multi-agent workflows: Use
Planagent 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
Installs
Security Audit
View Source
oakoss/agent-skills
More from this source
EU-Hosted Inference API Power your AI Agents with
the best open-source models.
Drop-in OpenAI-compatible API. No data leaves Europe.
Explore Inference APIGLM
GLM 5
$1.00 / $3.20
per M tokens
Kimi
Kimi K2.5
$0.60 / $2.80
per M tokens
MiniMax
MiniMax M2.5
$0.30 / $1.20
per M tokens
Qwen
Qwen3.5 122B
$0.40 / $3.00
per M tokens
How to use this skill
Install mcp-expert by running npx skills add oakoss/agent-skills --skill mcp-expert in your project directory. Run the install command above in your project directory. The skill file will be downloaded from GitHub and placed in your project.
No configuration needed. Your AI agent (Claude Code, Cursor, Windsurf, etc.) automatically detects installed skills and uses them as context when generating code.
The skill enhances your agent's understanding of mcp-expert, helping it follow established patterns, avoid common mistakes, and produce production-ready output.
What you get
Skills are plain-text instruction files — not executable code. They encode expert knowledge about frameworks, languages, or tools that your AI agent reads to improve its output. This means zero runtime overhead, no dependency conflicts, and full transparency: you can read and review every instruction before installing.
Compatibility
This skill works with any AI coding agent that supports the skills.sh format, including Claude Code (Anthropic), Cursor, Windsurf, Cline, Aider, and other tools that read project-level context files. Skills are framework-agnostic at the transport level — the content inside determines which language or framework it applies to.
Made in Europe Chat with 100+ AI Models in one App.
Use Claude, ChatGPT, Gemini alongside with EU-Hosted Models like Deepseek, GLM-5, Kimi K2.5 and many more.
