MCP Protocol Fundamentals Skill

MCP Protocol Fundamentals Skill

Metadata (Tier 1)

Keywords: mcp, model context protocol, json-rpc, protocol, specification

File Patterns: **/​mcp_server.py, **/​protocol.py

Modes: backend_python, api_development

---

Instructions (Tier 2)

JSON-RPC 2.0 Foundation

MCP is built on JSON-RPC 2.0 for bidirectional communication between Claude and servers.

Request Structure:

{
  "jsonrpc": "2.0",
  "method": "tools/​call",
  "params": {
    "name": "search",
    "arguments": {"query": "test"}
  },
  "id": 1
}

Response Structure:

{
  "jsonrpc": "2.0",
  "result": {"data": "..."},
  "id": 1
}

Error Response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found"
  },
  "id": 1
}

Core Concepts

Tools (Model-Controlled):

• Exposed by server, invoked by Claude
• Have strict input/​output schemas (Pydantic V2)
• Can have side effects (create, update, delete)
• Examples: search_code, create_file, execute_query

Resources (App-Controlled):

• Provide context to Claude (read-only)
• URI-based identification (file://, db://, api://)
• Returned in list_resources, read via read_resource
• Examples: project docs, database schemas, logs

Prompts (Optional):

• Pre-defined prompt templates
• Can include dynamic arguments
• Help standardize common workflows

Protocol Methods

Server → Client (Server exposes):

tools/​list       → List available tools
tools/​call       → Execute a tool
resources/​list   → List available resources
resources/​read   → Read resource content
prompts/​list     → List prompt templates
prompts/​get      → Get prompt with arguments

Client → Server (Server can request):

sampling/​createMessage → Request Claude to generate text
roots/​list             → Get workspace roots

Message Flow

Claude Desktop          MCP Server
      |                      |
      |---tools/​list-------->|
      |<--[tool schemas]-----|
      |                      |
      |---tools/​call-------->|
      |   {name, arguments}  |
      |<--result/​error-------|

Pydantic V2 Integration

CRITICAL: Use Pydantic strict mode for all schemas.

from pydantic import BaseModel, ConfigDict

class ToolInput(BaseModel):
    model_config = ConfigDict(strict=True)
    param: str

# Auto-generates inputSchema:
# {
#   "type": "object",
#   "properties": {"param": {"type": "string"}},
#   "required": ["param"]
# }

Transport Layer

MCP supports two transports:

1. stdio (Standard I/​O):

   async def main():
       async with stdio_server() as (read, write):
           await server.run(read, write)
   

2. HTTP/​SSE (Server-Sent Events):

   @app.post("/​mcp")
   async def handle_mcp(request: JsonRpcRequest):
       return await server.handle_request(request)
   

Error Codes (JSON-RPC 2.0)

-32700 → Parse error (invalid JSON)
-32600 → Invalid request
-32601 → Method not found
-32602 → Invalid params
-32603 → Internal error
-32000 to -32099 → Server-defined errors

Anti-Patterns

❌ Manual JSON schema writing (use Pydantic) ❌ Blocking operations in async handlers ❌ Missing error handling ❌ Invalid JSON-RPC 2.0 structure

---

Resources (Tier 3)

Official Specification: https://spec.modelcontextprotocol.io/ JSON-RPC 2.0 Spec: https://www.jsonrpc.org/specification Python SDK: https://github.com/modelcontextprotocol/python-sdk

Example Servers:

• Filesystem MCP: Read/​write local files
• GitHub MCP: Repository operations
• Database MCP: SQL query execution