{"title":"Exercise: Building MCP Clients","description":null,"content":"# Exercise 1: Drive the MCP Client Flow\n\nImplement the client side of an MCP session: initialize the connection, list the server's tools, then call one tool and read its result. To keep the exercise self-contained, you talk to a mock transport that returns canned JSON-RPC responses, so you can focus on the request/response sequence rather than networking.\n\nAn MCP client follows the same handshake every time: initialize, discover what the server offers, then invoke tools. The real SDK wraps this in `stdio_client` and `ClientSession`, but the logic underneath is a sequence of JSON-RPC requests and responses. Driving that sequence by hand is the clearest way to understand what the SDK does for you.\n\n### Requirements\n\n- Send an `initialize` request and confirm the server responds.\n- Send a `tools/list` request and print the available tool names.\n- Send a `tools/call` request for one tool and print the result.\n- Use the provided `transport(request)` function, which returns the server's JSON-RPC response.\n\n\n**main.py**\n\n```python\nimport json\n\n# A mock MCP server: takes a JSON-RPC request and returns a JSON-RPC response.\n# Stands in for a real stdio or HTTP transport so this runs standalone.\ndef transport(request: dict) -> dict:\n method = request[\"method\"]\n rid = request[\"id\"]\n if method == \"initialize\":\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"result\": {\"serverInfo\": {\"name\": \"demo\"}}}\n if method == \"tools/list\":\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"result\": {\"tools\": [\n {\"name\": \"add\"}, {\"name\": \"echo\"},\n ]}}\n if method == \"tools/call\":\n args = request[\"params\"][\"arguments\"]\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"result\": {\"content\": str(args[\"a\"] + args[\"b\"])}}\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"error\": {\"message\": \"unknown method\"}}\n\n# TODO: send an \"initialize\" request via transport and confirm a result came back\n\n# TODO: send a \"tools/list\" request and print the tool names\n\n# TODO: send a \"tools/call\" request for the \"add\" tool with arguments {\"a\": 2, \"b\": 3}\n# and print the result\n```\n\n\n### Expected Output\n\nThe client completes the handshake, lists tools, and gets a tool result back.\n\n\n```plaintext\nConnected to server: demo\nAvailable tools: ['add', 'echo']\nTool result: 5\n```\n\n\n### Solution\n\n\n**main.py**\n\n```python\nimport json\n\ndef transport(request: dict) -> dict:\n method = request[\"method\"]\n rid = request[\"id\"]\n if method == \"initialize\":\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"result\": {\"serverInfo\": {\"name\": \"demo\"}}}\n if method == \"tools/list\":\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"result\": {\"tools\": [\n {\"name\": \"add\"}, {\"name\": \"echo\"},\n ]}}\n if method == \"tools/call\":\n args = request[\"params\"][\"arguments\"]\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"result\": {\"content\": str(args[\"a\"] + args[\"b\"])}}\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"error\": {\"message\": \"unknown method\"}}\n\ndef request(method: str, rid: int, params: dict | None = None) -> dict:\n message = {\"jsonrpc\": \"2.0\", \"method\": method, \"id\": rid}\n if params is not None:\n message[\"params\"] = params\n return transport(message)\n\n# 1. Initialize the session\ninit = request(\"initialize\", 1)\nprint(f\"Connected to server: {init['result']['serverInfo']['name']}\")\n\n# 2. Discover the available tools\ntools = request(\"tools/list\", 2)\nnames = [tool[\"name\"] for tool in tools[\"result\"][\"tools\"]]\nprint(f\"Available tools: {names}\")\n\n# 3. Call a tool and read the result\ncalled = request(\"tools/call\", 3, {\"name\": \"add\", \"arguments\": {\"a\": 2, \"b\": 3}})\nprint(f\"Tool result: {called['result']['content']}\")\n```\n\n\nThe `request` helper builds a JSON-RPC message and hands it to the transport, which is exactly the boundary the real SDK draws between protocol logic and the connection. The handshake order is not arbitrary: a client initializes first, then discovers tools, then calls them, because it cannot invoke a tool it has not learned about. Swapping the mock `transport` for `stdio_client` and `ClientSession` connects this same flow to a real server without changing how you initialize, list, and call.\n\n---\n\n# Exercise 2: Handle a Tool Error and Retry\n\nA JSON-RPC response carries either a `result` or an `error`, and a robust client checks which it got. Call a tool with a wrong name, detect the error response, and retry with the correct name. Distinguishing result from error is the basic reliability check every MCP client needs.\n\n### Requirements\n\n- Use the provided mock `transport` that returns an `error` object for an unknown tool.\n- Call the tool with a wrong name and check whether the response contains `error`.\n- On error, retry with the correct name, then print the error message and the final result.\n\n\n**main.py**\n\n```python\nimport json\n\n# Mock MCP server: returns an error for an unknown tool, otherwise a result.\ndef transport(request):\n rid = request[\"id\"]\n if request[\"method\"] == \"tools/call\":\n name = request[\"params\"][\"name\"]\n if name not in {\"add\"}:\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"error\": {\"code\": -32601, \"message\": f\"unknown tool: {name}\"}}\n args = request[\"params\"][\"arguments\"]\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"result\": {\"content\": str(args[\"a\"] + args[\"b\"])}}\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"error\": {\"message\": \"unsupported\"}}\n\ndef call_tool(name, arguments, rid):\n return transport({\"jsonrpc\": \"2.0\", \"id\": rid, \"method\": \"tools/call\", \"params\": {\"name\": name, \"arguments\": arguments}})\n\n# TODO: call tool \"sum\" (wrong name) with {\"a\": 2, \"b\": 3}. Detect the error response.\n# TODO: on error, retry with the correct tool name \"add\". Print the error and the final result.\n```\n\n\n### Expected Output\n\nThe first call returns a JSON-RPC error; the client detects it and retries with the valid tool name.\n\n\n```plaintext\nError: unknown tool: sum\nResult: 5\n```\n\n\n### Solution\n\n\n**main.py**\n\n```python\nimport json\n\ndef transport(request):\n rid = request[\"id\"]\n if request[\"method\"] == \"tools/call\":\n name = request[\"params\"][\"name\"]\n if name not in {\"add\"}:\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"error\": {\"code\": -32601, \"message\": f\"unknown tool: {name}\"}}\n args = request[\"params\"][\"arguments\"]\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"result\": {\"content\": str(args[\"a\"] + args[\"b\"])}}\n return {\"jsonrpc\": \"2.0\", \"id\": rid, \"error\": {\"message\": \"unsupported\"}}\n\ndef call_tool(name, arguments, rid):\n return transport({\"jsonrpc\": \"2.0\", \"id\": rid, \"method\": \"tools/call\", \"params\": {\"name\": name, \"arguments\": arguments}})\n\narguments = {\"a\": 2, \"b\": 3}\nresponse = call_tool(\"sum\", arguments, 1)\n\nif \"error\" in response:\n print(\"Error:\", response[\"error\"][\"message\"])\n response = call_tool(\"add\", arguments, 2)\n\nprint(\"Result:\", response[\"result\"][\"content\"])\n```\n\n\nChecking for an `error` key before reaching for `result` is mandatory in JSON-RPC, because a response has exactly one of the two. Treating the error as a recoverable signal (retry with a corrected call) rather than a crash is what makes a client resilient to a bad tool name or arguments. Swapping the mock `transport` for the real `stdio_client` and `ClientSession` keeps this same result-or-error handling, which is the part that matters for reliability.","pageType":"ai-engineering"}

Get Premium