mcp-developer

MCP Developer

Senior MCP developer expertise in constructing servers and clients linking AI systems to external tools and data sources. Current spec: 2025-11-25.

Core Workflow

1. Analyze requirements
2. Initialize project — uv add "mcp[cli]>=1.25,<2" (Python) or npm i @modelcontextprotocol/sdk zod (TypeScript)
3. Design protocol with resource URIs and tool schemas
4. Implement and register handlers with appropriate transport (stdio for local, Streamable HTTP for remote)
5. Test using MCP inspector to verify protocol compliance
6. Deploy with auth, rate-limiting, and monitoring

Key Requirements

Must implement:

• JSON-RPC 2.0 protocol (2025-11-25 spec)
• Input validation via schemas (Pydantic for Python, Zod for TypeScript)
• Transport: stdio for local, Streamable HTTP for remote (HTTP+SSE is deprecated since 2025-03-26)
• Tool annotations on every tool (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
• Tool names: 1–128 chars, A-Za-z0-9_-. only (no spaces, slashes, commas)
• Error handling with McpError + JSON-RPC error codes
• Authentication (environment variables for stdio; OAuth 2.1 + PKCE for HTTP)
• Protocol logging, compliance testing, capability documentation

Must avoid:

• HTTP+SSE transport (old two-endpoint pattern — deprecated since 2025-03-26)
• Tool names with spaces, slashes (/), commas, or other special chars
• Writing to stdout in stdio servers (use stderr for all logging)
• Token passthrough to upstream APIs (servers MUST obtain their own tokens)
• Exposing sensitive data or stack traces in error responses
• Mixing sync/async patterns; hardcoding secrets
• Deploying without rate limits or authentication

Reference Files

File	Contents
references/protocol.md	JSON-RPC 2.0 message types, connection lifecycle, core methods, error codes
references/transport.md	Streamable HTTP (current), stdio, deprecated HTTP+SSE, migration guide
references/python-sdk.md	Server/client setup, Pydantic validation, Streamable HTTP, error handling
references/typescript-sdk.md	Server/client setup, Zod validation, Streamable HTTP, error handling
references/tools.md	Tool definitions, naming rules, annotations, structured output, input schemas
references/resources.md	URI schemes, resource templates, content types, subscriptions, security