The comprehensive framework for building AI-agent-optimized Model Context Protocol (MCP) servers.
Most existing MCPs are built as simple API wrappers without considering the unique constraints of AI agents:
- Limited context window → Tokens are expensive
- No persistent memory → State must be managed differently
- Pattern-matching decisions → Needs clear, consistent interfaces
- Tendency toward verbose exploration → Requires guardrails
The result? MCPs that waste tokens, require multiple round-trips, and lack safety controls.
This standard defines best practices across 12 critical dimensions to create MCPs that are efficient, robust, and agent-friendly.
| File | Description |
|---|---|
| MCP_EXCELLENCE_STANDARD.md | The complete standard with detailed patterns and anti-patterns |
| skills/mcp-excellence/ | Claude skill for building standard-compliant MCPs (Anthropic format) |
| checklists/compliance-checklist.md | Quick evaluation checklist for any MCP |
returnOnlyIdsmode for listscompactmode with minimal fields- Cursor-based pagination
- Count-only operations
- Summary-only batch responses
search_and_actioncompositesget_or_createpatternsdryRunpreview mode- Internal batching
- Partial success reporting
- Structured error responses
- Internal retry logic
- Graceful degradation
- Account ID parameters
- Silent token refresh
- Device flow support
- Secure credential storage
get_capabilities()tool- Enum discovery
- Rich tool descriptions
- Schema introspection
- ETag/conditional requests
- Delta/incremental sync
- Internal caching with TTL
- Lazy loading / expand parameters
- Exclude heavy fields by default
- Truncation with metadata
{resource}_{action}naming- Danger indicators
- Read/write separation
- Action history logging
- Undo capabilities
- Change summaries
- Email MCP requirements
- Calendar MCP requirements
- File Storage MCP requirements
- CRM/Database MCP requirements
- JSON responses always
- Consistent schemas
- Actionable IDs
- Status enums
- Maximum batch sizes
- Two-stage deletion
- Confirmation tokens
- Rate limiting
- Read-only mode
Use the compliance checklist to evaluate any MCP:
| Score | Rating |
|---|---|
| 30-36 | ⭐⭐⭐⭐⭐ Excellent - Production ready |
| 24-29 | ⭐⭐⭐⭐ Good - Minor improvements needed |
| 18-23 | ⭐⭐⭐ Adequate - Significant gaps |
| 12-17 | ⭐⭐ Poor - Major refactoring needed |
| 0-11 | ⭐ Failing - Rebuild recommended |
The included Claude skill follows Anthropic's official skill format with proper YAML frontmatter and progressive disclosure.
skills/mcp-excellence/
├── SKILL.md # Main skill file with YAML frontmatter
└── references/
├── patterns.md # Detailed implementation patterns
└── platforms.md # Platform-specific requirements
Claude Code: Copy skills/mcp-excellence/ to ~/.claude/skills/
Claude.ai: Zip the folder and upload via Settings > Features
- Automatic context window optimization
- Built-in batch operations
- Error handling patterns
- Safety guardrails by default
- Open the Compliance Checklist
- Score each category
- Identify gaps and prioritize improvements
- Install the skill (see Installation above)
- Ask Claude: "Create an MCP for [API name] following the MCP Excellence Standard"
- Provide your API documentation
- Claude will generate a standard-compliant MCP
- Install the skill
- Ask Claude: "Review this MCP and improve it following the MCP Excellence Standard"
- Share your existing MCP code
- Claude will identify gaps and implement improvements
The skill works for both creating NEW MCPs and IMPROVING existing ones!
Create a new MCP:
"Create a Gmail MCP following the MCP Excellence Standard with
context window optimization and batch operations"
Improve an existing MCP:
"Review this MCP code and enhance it following the MCP Excellence
Standard. Add returnOnlyIds, compact mode, and search_and_action."
Audit an MCP:
"Score this MCP against the MCP Excellence Standard compliance
checklist and tell me what's missing."
Add specific features:
"Add context window optimization to this MCP - I need returnOnlyIds,
compact mode, and count operations."
| Resource | Use For |
|---|---|
| Skill | Let Claude auto-apply best practices while coding |
| Standard | Deep reference for understanding the "why" |
| Checklist | Quick audit of any MCP (yours or third-party) |
// Returns 500 full email objects
const emails = await mcp.search_emails({ query: "from:newsletter" });
// Then loops to delete each one
for (const email of emails) {
await mcp.delete_email({ id: email.id });
}
// Result: 501 API calls, ~50,000 tokens consumed// Single composite operation with preview
const result = await mcp.search_and_action({
query: "from:newsletter",
action: "trash",
dryRun: false
});
// Result: 1 API call, ~100 tokens consumed
// Returns: { processed: 247, failed: 0 }This is a living standard. Contributions welcome!
- Fork the repository
- Create a feature branch
- Submit a pull request
- New platform-specific patterns
- Reference implementations
- Linting tools
- Additional language examples
MIT License - See LICENSE for details.
Juan C. Guerrero
Founder of Blockchain Jungle | Co-founder of Dojo Coding & All Time High
This standard was developed through hands-on experience building and enhancing multiple MCPs, identifying patterns that waste AI agent resources, and synthesizing best practices that the industry was lacking.
"An MCP is not a human API. It's an interface for an AI agent with unique constraints and capabilities. Design accordingly."