MCP Best Practices

Purpose

Document and apply MCP implementation best practices: server design, client integration, testing, versioning, observability, and operational readiness for production MCP deployments.

Input: MCP server/client implementation (existing or planned), deployment target, team constraints
Output: MCP Best Practices Compliance Report with gap analysis, recommended patterns, and operational playbook Examples: See examples.md for worked input/output.

Workflow

Step 1: Assess current implementation

Score each practice area:

Step 2: Apply server best practices

Step 3: Apply client best practices

Step 4: Define testing strategy

Step 5: Plan observability and operations

Document runbook: server restart, token rotation, rollback procedure.

Step 6: Validate

Run Validation checklist.

Decision Rules

Validation

• All 8 practice areas assessed with gaps identified
• Server practices: naming, schemas, errors, timeouts documented
• Client practices: discovery, validation, resilience documented
• Testing strategy covers unit, integration, contract, security
• Observability signals and alerts defined
• Versioning and changelog policy stated
• README complete: setup, config, tools, troubleshooting
• Operational runbook for common incidents

Anti-patterns

• Copy-paste handlers — duplicated logic without shared lib layer.
• No changelog — breaking changes without consumer notice.
• Production debugging via printf — unstructured logs without levels.
• Skipping contract tests — server deploy breaks clients silently.
• Monorepo chaos — server and unrelated app code interleaved.

Best Practices

• Pin MCP SDK versions; test upgrades in staging.
• Publish JSON Schema for tools as machine-readable artifact.
• Use semantic versioning for server packages.
• Document breaking changes with migration guide.
• Schedule periodic security re-review with mcp-security-review.

Output Structure

# MCP Best Practices Report: [Project Name]

## Compliance Summary
| Area | Score (1-5) | Critical gaps |
|------|-------------|---------------|

## Server Practices
[Checklist with pass/fail]

## Client Practices
[Checklist with pass/fail]

## Testing Strategy
| Level | Status | Action items |
|-------|--------|--------------|

## Observability
| Signal | Implementation | Alert |
|--------|----------------|-------|

## Versioning Policy
[Semver rules, changelog format]

## Operational Runbook
| Incident | Detection | Resolution |
|----------|-----------|------------|

## Improvement Roadmap
| Priority | Item | Effort |
|----------|------|--------|

Next Skills