mcp-research

Original source / Raw SKILL.md

---
name: mcp-research
description: Expert research tool for Model Context Protocol implementations. PROACTIVELY use when reviewing MCP server code, planning new MCP tools/resources/prompts, investigating protocol compliance issues, or validating architecture. Specializes in protocol compliance (JSON-RPC 2.0), security patterns, transport layers, and production best practices. Current spec: 2025-06-18.
allowed-tools: Read, Grep, Glob, WebFetch, WebSearch
---

# MCP Implementation Research

## Quick Start

**What are you doing?**
- 📝 **Reviewing MCP server** → `references/implementation-checklist.md`
- 🚀 **Planning MCP feature** → `references/protocol-patterns.md`
- 🐛 **Protocol issue** → `references/common-pitfalls.md`
- ✅ **Architecture validation** → All references + latest spec

## Research Workflow

1. **Understand implementation** - What MCP capabilities? Which transport? What security requirements?
2. **Consult references** - Load relevant reference files progressively
3. **Check latest spec** - WebFetch `https://modelcontextprotocol.io/specification/2025-06-18`
4. **Search community** - WebSearch for "MCP [specific-issue] 2025"
5. **Validate compliance** - Protocol compliance, security, best practices
6. **Report findings** - Structured format (see examples/)

## Critical MCP Requirements

### Protocol Compliance (JSON-RPC 2.0)
- All messages MUST include `jsonrpc: "2.0"`
- Responses include `result` OR `error`, never both
- Initialization: `initialize` → response → `initialized` notification
- Use standard error codes (-32xxx)

### Security & Consent
- User consent MUST be obtained before data access
- Tool execution requires explicit approval
- No hardcoded credentials
- Input/output sanitization required

### Capability Advertisement
- Declare all capabilities in `initialize` response
- Types: `tools`, `resources`, `prompts`, `logging`, `experimental`
- Protocol version: `"2025-06-18"` (latest)

### Transport Layers

**stdio:**
- Newline-delimited JSON-RPC messages
- Use stderr for logging (not stdout)
- Flush after each message

**HTTP/SSE:**
- POST `/mcp` for JSON-RPC requests
- GET `/mcp/sse` for server-sent events
- CORS configured for browser clients

## Key Reference Files

**`implementation-checklist.md`** - Protocol compliance, capabilities, security, production readiness
**`protocol-patterns.md`** - Tool/resource/prompt patterns, best practices, code examples
**`common-pitfalls.md`** - Known issues, edge cases, gotchas

## Research Sources

**Official Spec:** `https://modelcontextprotocol.io/specification/2025-06-18`
**Best Practices:** `https://modelcontextprotocol.info/docs/best-practices/`
**Examples:** `https://github.com/modelcontextprotocol/servers`

## Search Patterns

```
# Protocol issues
WebSearch("MCP JSON-RPC [specific-error] 2025")

# Implementation patterns
WebSearch("MCP server [capability-type] best practices site:github.com")

# Security
WebSearch("MCP consent workflow implementation 2025")
```

## Output Format

**BE EXTREMELY CONCISE.** Senior engineers with limited time.

**MAX 400 words.** Focus on critical issues only:
- Protocol violations (file:line)
- Security gaps (specific CVE/exploit)
- 3 max actionable fixes

### Code Review Template
```
**Protocol:** [compliant/non-compliant + critical issue]
**Security:** [ok/issue + specific vulnerability]
**Critical Fixes:** [1-3 items max, file:line references]
```

### Feature Planning Template
```
**Approach:** [tool/resource/prompt]
**Requirements:** [1-2 critical constraints]
**Security:** [specific consent/privacy needs]
```

**DO NOT:**
- Write long explanations
- Create documentation files
- Provide code examples (unless critical fix)
- Explain basic MCP concepts

## Success Criteria

✅ Protocol compliance (JSON-RPC 2.0 + MCP spec)
✅ Security requirements met (consent + privacy)
✅ Best practices followed
✅ Production ready (monitoring + scaling)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/implementation-checklist.md

```markdown
# MCP Implementation Review Checklist

Quick validation checklist for MCP server implementations.

## Protocol Compliance

### JSON-RPC 2.0
- [ ] All messages include `jsonrpc: "2.0"`
- [ ] Requests have `method`, `params`, `id`
- [ ] Responses have `result` XOR `error` (never both)
- [ ] Error codes: `-32xxx` (JSON-RPC) or custom positive integers
- [ ] Init sequence: `initialize` → response → `initialized` notification

### Capabilities
- [ ] `initialize` response declares all implemented capabilities
- [ ] Protocol version set (e.g., `"2025-06-18"`)
- [ ] Capabilities match actual implementation
- [ ] Types: `tools`, `resources`, `prompts`, `logging`, `experimental`

## Features

### Tools (`tools/list`, `tools/call`)
- [ ] Tool schemas define clear input parameters
- [ ] Results return MCP content types (text/image/resource)
- [ ] Input validation rejects invalid params
- [ ] User consent obtained before execution
- [ ] Errors use MCP error codes

### Resources (`resources/list`, `resources/read`)
- [ ] URIs use valid schemes (custom/file/http)
- [ ] Templates support parameter substitution
- [ ] Large resources paginated/chunked
- [ ] Access control enforced

### Prompts (`prompts/list`, `prompts/get`)
- [ ] Arguments clearly defined
- [ ] Messages properly formatted (role + content)
- [ ] Dynamic prompts tested with arguments
- [ ] Content safe for LLM consumption

## Transport

### stdio
- [ ] Newline-delimited JSON-RPC
- [ ] stderr only for logging (not responses)
- [ ] Output flushed after each message
- [ ] Handles EOF/close gracefully

### HTTP/SSE
- [ ] POST endpoint for requests
- [ ] SSE stream for server-initiated messages
- [ ] CORS configured appropriately
- [ ] Timeouts set for long operations

## Security

- [ ] User consent for data access
- [ ] Tool execution gated behind approval
- [ ] No hardcoded credentials
- [ ] Input validation/sanitization
- [ ] Output sanitization (no data leaks)
- [ ] Rate limiting for expensive ops
- [ ] Audit logging for sensitive actions

## Error Handling

**Standard Codes:**
- `-32700` Parse error
- `-32600` Invalid request
- `-32601` Method not found
- `-32602` Invalid params
- `-32603` Internal error

**Requirements:**
- [ ] Actionable error messages
- [ ] Error context for debugging
- [ ] Graceful handling of external API failures
- [ ] Appropriate logging

## Production

### Performance
- [ ] Async/non-blocking expensive ops
- [ ] Caching for frequently accessed data
- [ ] Connection pooling for external services
- [ ] Stateless (horizontal scaling possible)
- [ ] Timeouts on all external calls

**Targets:**
- Throughput: >1000 req/sec/instance
- Latency P95: <100ms (simple ops)
- Latency P99: <500ms (complex ops)
- Error rate: <0.1%

### Monitoring
- [ ] Structured logging (JSON format)
- [ ] Health check endpoint
- [ ] Metrics collection (request count, latency, errors)
- [ ] Deployment automation
- [ ] Rollback strategy

**Health Check Must Include:**
- Overall status (healthy/degraded/unhealthy)
- Component status (DB, cache, external APIs)
- Resource usage (memory, CPU, connections)

## Testing

- [ ] Protocol compliance tests (JSON-RPC)
- [ ] All capabilities tested (tools/resources/prompts)
- [ ] Error handling coverage
- [ ] Integration tests with real MCP client
- [ ] Load testing performed
- [ ] Security tests (consent, validation)

## Pre-Release Checklist

- [ ] JSON-RPC 2.0 validated
- [ ] Capabilities advertised correctly
- [ ] Security/consent implemented
- [ ] Error handling tested
- [ ] Performance targets met
- [ ] Monitoring configured
- [ ] Health checks working
- [ ] Client integration tested
- [ ] Documentation complete

```

### references/protocol-patterns.md

```markdown
# MCP Protocol Patterns

Essential implementation patterns for MCP servers.

## Tool Pattern

**tools/list** - Declare available tools with JSON schema
**tools/call** - Execute tool, return content array

```typescript
// Result format
{
  "content": [{ "type": "text", "text": JSON.stringify(data) }],
  "isError": false  // true for domain errors
}
```

**Best Practices:**
- Validate inputs against schema
- Return structured data as JSON string
- Use `isError: true` for domain errors (not JSON-RPC errors)

## Resource Pattern

**resources/list** - Declare resources/templates
**resources/read** - Return resource content by URI

```typescript
// URI schemes: custom (myapp://), file (file://), http (https://)
// Templates: "myapp://events/{date}"
```

**Best Practices:**
- Custom URI schemes for domain resources
- Templates for dynamic resources
- Chunk large resources (>1MB)

## Prompt Pattern

**prompts/list** - Declare prompts with arguments
**prompts/get** - Return formatted messages

```typescript
// Message format
{
  "messages": [{
    "role": "user" | "assistant",
    "content": { "type": "text", "text": "..." }
  }]
}
```

## Error Handling

**JSON-RPC Codes:**
- `-32700` Parse error
- `-32600` Invalid request
- `-32601` Method not found
- `-32602` Invalid params
- `-32603` Internal error

**Custom Codes:** Positive integers for domain errors

```typescript
// Include actionable context
{
  "error": {
    "code": -32602,
    "message": "Invalid calendar ID",
    "data": {
      "parameter": "calendarId",
      "expected": "Valid ID or 'primary'"
    }
  }
}
```

## Transport

### stdio
- Newline-delimited JSON-RPC
- stderr for logging
- Flush after each message

### HTTP/SSE
- POST `/mcp` - JSON-RPC requests
- GET `/mcp/sse` - Server-sent events
- GET `/health` - Health check

## Security

**Consent:** Check before tool execution/data access
**Validation:** Validate all inputs, sanitize all outputs
**Credentials:** Environment vars, never hardcoded

## Performance

**Caching:** In-memory with TTL for frequent data
**Pooling:** Reuse connections/clients
**Async:** Long operations return task IDs
**Timeouts:** Set on all external calls

## Monitoring

**Logging:** JSON structured to stderr
**Metrics:** Request count, duration (P95/P99), errors
**Health:** Overall status + component status

```typescript
// Health response
{
  "status": "healthy" | "degraded" | "unhealthy",
  "components": {
    "database": "healthy",
    "cache": "degraded"
  }
}
```

## Key Requirements

✅ JSON-RPC 2.0 format (jsonrpc, method, params, id)
✅ Accurate capability advertisement
✅ User consent workflows
✅ Input validation + output sanitization
✅ Appropriate error codes
✅ Structured logging
✅ Health checks
✅ Stateless design (for scaling)

```

### references/common-pitfalls.md

```markdown
# MCP Common Pitfalls

Known issues and edge cases in MCP server implementations.

## Protocol Errors

### Missing jsonrpc Field
**Problem:** Responses missing `"jsonrpc": "2.0"` field
**Impact:** Clients reject messages as invalid JSON-RPC
**Fix:** Include in all requests and responses

### Both result and error
**Problem:** Response includes both `result` and `error` fields
**Impact:** Invalid JSON-RPC 2.0 (must be XOR)
**Fix:** Return one or the other, never both

### Skipped initialized Notification
**Problem:** Server doesn't send `initialized` notification after `initialize`
**Impact:** Client waits indefinitely, connection hangs
**Fix:** Always send `initialized` after successful `initialize` response

### Incorrect Error Codes
**Problem:** Using custom codes for standard JSON-RPC errors
**Impact:** Clients misinterpret error types
**Fix:** Use `-32xxx` for protocol errors, positive integers for domain errors

## Capability Issues

### Undeclared Capabilities
**Problem:** Server implements features not declared in `initialize` response
**Impact:** Clients don't discover features, functionality hidden
**Fix:** Declare all capabilities (`tools`, `resources`, `prompts`, etc.)

### Outdated Protocol Version
**Problem:** Using old protocol version string
**Impact:** Missing new features, potential incompatibility
**Fix:** Use latest spec version (currently `"2025-06-18"`)

### Capability Mismatch
**Problem:** Declared capabilities don't match actual implementation
**Impact:** Client calls fail unexpectedly
**Fix:** Keep capability list synchronized with implementation

## Security Gaps

### Missing Consent Workflows
**Problem:** Tool execution without user approval
**Impact:** Unauthorized actions, data leaks, security violations
**Fix:** Require explicit consent before tool execution and data access

### Hardcoded Credentials
**Problem:** API keys, passwords in source code
**Impact:** Credential exposure, security breach
**Fix:** Use environment variables, secure credential storage

### No Input Validation
**Problem:** Accepting unsanitized user input
**Impact:** Injection attacks, crashes, data corruption
**Fix:** Validate all inputs, use schema enforcement

### Output Leakage
**Problem:** Returning sensitive data without sanitization
**Impact:** Data privacy violations
**Fix:** Sanitize outputs, remove sensitive fields

## Transport Layer Issues

### stdout Contamination (stdio)
**Problem:** Logging or debug output to stdout instead of stderr
**Impact:** JSON-RPC messages corrupted, client parsing fails
**Fix:** All logging to stderr, only JSON-RPC to stdout

### Missing Output Flush (stdio)
**Problem:** Buffered output not flushed immediately
**Impact:** Delayed responses, client timeouts
**Fix:** Flush stdout after each message

### CORS Not Configured (HTTP)
**Problem:** Missing CORS headers for browser clients
**Impact:** Browser blocks requests
**Fix:** Configure appropriate CORS headers

### SSE Connection Drops (HTTP)
**Problem:** SSE stream closes unexpectedly
**Impact:** Server can't send notifications to client
**Fix:** Implement keep-alive, reconnection logic

## Tool Implementation

### Missing Input Schema
**Problem:** Tools without proper JSON schema for inputs
**Impact:** Clients can't validate parameters, errors at runtime
**Fix:** Define complete input schema for all tools

### Incorrect Content Type
**Problem:** Returning wrong content type (e.g., object instead of text)
**Impact:** Client can't parse response
**Fix:** Use MCP content types: `text`, `image`, `resource`

### Blocking Operations
**Problem:** Long-running tools block entire server
**Impact:** Other requests timeout, poor performance
**Fix:** Run async, return task ID for long operations

### No Error Context
**Problem:** Generic error messages without details
**Impact:** Users can't debug issues
**Fix:** Include parameter names, expected values in error data

## Resource Implementation

### Invalid URI Schemes
**Problem:** Using unsupported or malformed URI schemes
**Impact:** Clients can't fetch resources
**Fix:** Use valid schemes: custom, `file://`, `https://`

### Large Resources Not Chunked
**Problem:** Returning multi-MB resources in single response
**Impact:** Memory issues, timeouts
**Fix:** Chunk resources >1MB, implement pagination

### Missing Access Control
**Problem:** No authorization checks for sensitive resources
**Impact:** Data leaks
**Fix:** Verify user permissions before returning resource

## Performance Issues

### No Caching
**Problem:** Fetching same data repeatedly from external APIs
**Impact:** Slow responses, API rate limits hit
**Fix:** Implement caching with appropriate TTL

### No Connection Pooling
**Problem:** Creating new connections for each request
**Impact:** Slow performance, resource exhaustion
**Fix:** Pool connections, reuse clients

### Synchronous External Calls
**Problem:** Blocking on external API calls
**Impact:** Poor throughput, cascading delays
**Fix:** Use async/await, non-blocking I/O

### Missing Timeouts
**Problem:** No timeout on external API calls
**Impact:** Requests hang indefinitely
**Fix:** Set timeouts (3-5 seconds typical)

## Production Issues

### No Health Checks
**Problem:** Server has no health/readiness endpoint
**Impact:** Load balancers can't detect failures
**Fix:** Implement `/health` with component status

### Unstructured Logging
**Problem:** Plain text logs, inconsistent format
**Impact:** Difficult to parse, monitor, alert on
**Fix:** Use JSON structured logging

### Stateful Design
**Problem:** Server stores state in memory
**Impact:** Can't scale horizontally, data loss on restart
**Fix:** Design stateless, use external state storage

### No Metrics
**Problem:** No telemetry or monitoring
**Impact:** Can't diagnose performance issues, outages
**Fix:** Expose metrics (request count, latency, errors)

## Testing Gaps

### No Protocol Compliance Tests
**Problem:** Not validating JSON-RPC 2.0 format
**Impact:** Non-compliant messages, client incompatibility
**Fix:** Add JSON-RPC schema validation tests

### Missing Error Path Tests
**Problem:** Only testing success cases
**Impact:** Unhandled errors crash server
**Fix:** Test all error conditions

### No Load Testing
**Problem:** Not testing under realistic load
**Impact:** Performance issues in production
**Fix:** Run load tests, identify bottlenecks

## Quick Fixes Reference

**Protocol:** Always include `jsonrpc: "2.0"`, never both `result` and `error`
**Capabilities:** Declare all features in `initialize` response
**Security:** Require consent, validate inputs, sanitize outputs, no hardcoded credentials
**Transport:** stderr for logs (stdio), CORS headers (HTTP), flush after writes
**Performance:** Cache, pool connections, async operations, timeouts
**Production:** Health checks, structured logging, stateless design, metrics

```