MCP Deployment Operations FAQ & Answers

MCP 2025-03-26 is built on JSON-RPC 2.0 with stateful session protocol. Core requirements: (1) All messages MUST be UTF-8 encoded JSON-RPC 2.0 with three types: Requests (bidirectional, mandatory non-null IDs), Responses (result or error), Notifications (one-way, no IDs). (2) Initialization must be first interaction with protocol version negotiation: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}. (3) Two standard transports: stdio (stdin/stdout) or Streamable HTTP (single POST endpoint). (4) OAuth 2.1: RFC8414 metadata discovery, RFC7591 dynamic client registration, PKCE mandatory for all clients. (5) Session IDs: globally unique, cryptographically secure (UUID/JWT), visible ASCII only (0x21-0x7E). (6) Explicit user consent required before tool invocation. (7) RFC2119 compliance: MUST, SHALL, REQUIRED are strictly interpreted.

Three-step handshake: (1) Client sends 'initialize' JSON-RPC request with protocolVersion it supports, (2) Server responds with same or compatible version + capabilities list, (3) If versions incompatible, client disconnects. Version negotiation: client should send latest version it supports; server responds with same or another supported version. Capabilities determine available features (tools, resources, prompts). After successful init, server advertises what it can do. This establishes foundation for all subsequent MCP operations. Example: {jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2025-03-26',capabilities:{tools:{}}}}

For POST requests: (1) Content-Type: application/json (required), (2) Accept: application/json, text/event-stream (both listed, required), (3) Mcp-Session-Id: [session-id] (required for all requests after initialization if server assigns one). For GET requests (SSE): (1) Accept: text/event-stream (required), (2) Last-Event-ID: [event-id] (optional, for resuming after broken connection). Session IDs must be: globally unique, cryptographically secure (UUID/JWT/hash), visible ASCII only (0x21-0x7E). Security: Always validate Origin header to prevent DNS rebinding attacks.

JSON-RPC 2.0 response with "result" object containing "content" array. Each content block has "type" field: text, image, audio, resource, or embedded resource. Standard format: {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"Response data"}],"isError":false}}. New in 2025: "structuredContent" field for machine-readable JSON alongside text serialization for backwards compatibility: {"structuredContent":{"temperature":22.5,"conditions":"Partly cloudy"},"content":[{"type":"text","text":"{...}"}]}. Tool design best practices: (1) Single responsibility, (2) Minimize parameters with explicit types, (3) Names: ^[a-zA-Z0-9_-]{1,64}$, use snake_case for optimal GPT-4o tokenization, (4) Prefix with service name (github-add_issue), (5) Return structured data in structuredContent, (6) Set isError:true for failures. Always include text fallback for structured responses.

2025 best practice: Use specific path /mcp. Streamable HTTP (single POST /mcp) is simpler than HTTP+SSE (dual: GET /mcp, POST /messages). Production servers should support both transports for compatibility during 2025 transition. Required endpoints: (1) /mcp or /[service]/mcp for protocol, (2) /health for readiness/liveness checks, (3) /.well-known/oauth-authorization-server (RFC8414), (4) /.well-known/oauth-protected-resource for OAuth discovery, (5) /capabilities for tool/schema listing. Multi-server setup: mount at different paths (/mcp-discovery, /mcp-kb). Example nginx: location /mcp {proxy_pass http://localhost:3001/mcp; proxy_http_version 1.1; proxy_set_header Connection "";} Protocol detection routes requests to appropriate transport handler based on HTTP method and path. Use MCP 'roots' to define operational boundaries and security scopes. Avoid mapping every API endpoint to separate tool—consolidate around use cases.

Official regex: ^[a-zA-Z0-9_-]{1,64}$. Over 90% use snake_case - recommended for best GPT-4o tokenization. AVOID: spaces, dots (.), brackets () []. Prefix with service name for organization: github-add_issue_comment. Benefits: (1) Natural grouping, (2) Prevents name collisions, (3) Easier discovery. Design names reflecting conceptual purpose, not technical implementation. Each tool needs unique name + description. Use similar naming for similar parameters across endpoints. Maximize interoperability (how well LLM can use feature) and discoverability (how easily found). Clients list tools via tools/list endpoint. Examples: get_weather, search_documents, analyze_data.

Two aspects: Technical (correct responses) + Behavioral (AI usability). Tools: (1) MCP Inspector (official, interactive, primary tool), (2) CLI + jq: echo '{jsonrpc:2.0,method:tools/list,id:1}' | server-cmd | jq, (3) Unit tests (pytest/Mocha) for endpoints, (4) Integration tests simulating client-server interactions. Essential tests: List Tools (what AI sees), Tool Calling (success/failure paths), Error handling (precise messages). Behavioral: Fire prompts at GPT-4 to check tool selection. Logging: stderr for logs/debug, stdout only for JSON-RPC. Metrics: Track hit rate (appropriate tool calls) and success rate. Start with technical tests, layer behavioral tests for subtle issues.

MCP introduced OAuth 2.1 in March 2025. Required endpoints: (1) GET /.well-known/oauth-authorization-server (Server Metadata Discovery, RFC8414), (2) POST /oauth/register (Dynamic Client Registration, RFC7591), (3) GET /oauth/authorize (Authorization page), (4) POST /oauth/authorize (Authorization processing), (5) POST /oauth/token (Token endpoint). PKCE is mandatory for all clients (public clients like CLI tools). Token passthrough is anti-pattern and explicitly forbidden. Best practices: (1) Short-lived, scoped tokens, (2) Infrastructure-based attestation for client auth, (3) Centralized Authorization Server for all MCP servers, (4) Integration with existing SSO. Security: Session-based auth is forbidden; use token-based only.

Three discovery mechanisms: (1) Desktop Extensions (.mcpb files): Single-click installation bundling server + dependencies. Access via Settings > Extensions > Browse extensions. Files now use .mcpb extension (replacing .dxt, though .dxt still works). Extensions from official directory auto-update by default; private distributions require manual updates. (2) Dynamic tool discovery: Automatic detection with 🔨 icon in bottom-right when ≥1 server detected. (3) Manual configuration: Edit claude_desktop_config.json with {"mcpServers":{"server-name":{"command":"path","args":[],"env":{}}}}. Cross-tool discovery: VS Code can detect/reuse Claude Desktop configs via chat.mcp.discovery.enabled. Local servers work on Windows/macOS/Linux with automatic runtime detection. Important: Allowlist replaces blocklist on Oct 31, 2025—organizations must configure new allowlist to manage user access. Remote MCP (Claude.ai): Requires OAuth 2.1 with RFC7591 DCR for dynamic credential acquisition.

OpenTelemetry is ideal for MCP—shares openness, interoperability, language-agnostic design. Three metric layers: (1) Protocol: Tool invocation count, execution durations, success/failure rates, error classification (permission/params/timeout/internal). (2) Performance: p50/p95/p99 latencies per tool, request throughput, context propagation via W3C Trace Context standard. (3) Behavioral: Tool hit rate (appropriate calls), success rate (initial + retries). Traces: Capture each tool invocation as spans showing internal step durations and failure points. Platforms: SigNoz + OpenTelemetry (precise telemetry, scaling decisions, exports to Grafana/AWS X-Ray/Langfuse), Sentry (protocol-aware breakdown by transport/tool/resource), Moesif (JSON-RPC payload visibility). 2025 advancement: OpenTelemetry proposal to transmit trace data from server back to client for end-to-end observability. Context propagation uses open W3C standards linking requests across services. Critical for new tech reliability.