Skip to main content

Connect from a Python client

You do not need an AI app to use an MCP server. This guide shows how to call the Edumaths360 server from your own Python code, for example in a test, a script or a backend service.

Before you start: run uv sync --extra dev in server/.

The complete client​

snippets/client.py runs one full practice round:

snippets/client.py
"""Minimal Python client for the Edumaths360 Practice Server.

Launches the server as a subprocess over stdio (the same way Claude Desktop
or Cursor would), then walks through one practice round:
generate a problem -> wrong answer -> hint -> correct answer.

Usage (from the repository root, after installing the server):
python snippets/client.py
"""

from __future__ import annotations

import asyncio
import json
import sys

from mcp import Client, StdioServerParameters

# Start the server with the same Python interpreter that runs this script.
SERVER = StdioServerParameters(command=sys.executable, args=["-m", "edumaths360_mcp"])


async def main() -> None:
async with Client(SERVER) as client:
info = client.server_info
print(f"Connected to {info.title} v{info.version} (protocol {client.protocol_version})\n")

tools = await client.list_tools()
print("Tools:", ", ".join(tool.name for tool in tools.tools))

# 1. Generate a reproducible problem.
result = await client.call_tool(
"generate_problem",
{"topic": "profit_loss", "difficulty": "hard", "seed": 42},
)
problem = result.structured_content
print(f"\nProblem {problem['problem_id']}: {problem['statement']}")

# 2. A wrong answer: feedback, but no answer revealed.
result = await client.call_tool("check_answer", {"problem_id": problem["problem_id"], "answer": "1040"})
print("Attempt '1040' ->", result.structured_content["feedback"])

# 3. Ask for progressively stronger hints.
for level in (1, 2):
result = await client.call_tool("get_hint", {"problem_id": problem["problem_id"], "level": level})
print(f"Hint {level}:", result.structured_content["hint"])

# 4. The correct answer unlocks the worked solution.
result = await client.call_tool("check_answer", {"problem_id": problem["problem_id"], "answer": "Rs 1,300"})
check = result.structured_content
print("Attempt 'Rs 1,300' ->", check["feedback"], "| Solution:", check["solution"])

# 5. Errors come back as a normal result with is_error=True.
result = await client.call_tool("check_answer", {"problem_id": problem["problem_id"], "answer": "no idea"})
print("\nError example ->", result.is_error, result.content[0].text)

# 6. Read a resource and fetch a prompt.
syllabus = await client.read_resource("syllabus://section/quant")
topics = [t["topic"] for t in json.loads(syllabus.contents[0].text)["topics"]]
print("Quant topics:", ", ".join(topics))

prompt = await client.get_prompt("socratic_tutor", {"topic": "time_work", "difficulty": "hard"})
print("Prompt starts:", prompt.messages[0].content.text.splitlines()[0])


if __name__ == "__main__":
asyncio.run(main())

Run it from the repository root:

cd server
uv run python ../snippets/client.py

Expected output​

Connected to Edumaths360 Practice Server v0.3.0 (protocol 2026-07-28)

Tools: generate_problem, check_answer, get_hint

Problem pl-hard-42: By selling an article for Rs 800, a trader loses 20%. At what price, in rupees, should he sell it to gain 30%?
Attempt '1040' -> The gain % is worked out on the cost price, not on the old selling price.
Hint 1: Find the cost price first. A loss of 20% means Rs 800 is 80% of the cost price.
Hint 2: To get the cost price, divide Rs 800 by 80 and multiply by 100.
Attempt 'Rs 1,300' -> Correct! Well done. Now try to solve the next one faster. | Solution: CP = 800 × 100/80 = 1000 → new SP = 1000 × 130/100 = 1300

Error example -> True Error executing tool check_answer: I could not find a number in that answer. Expected format: a number, for example 450 (no units, % or Rs sign needed).
Quant topics: percentages, profit_loss, ratio_proportion, time_speed_distance, time_work, interest, linear_equations, quadratics, number_system
Prompt starts: You are a patient quantitative aptitude and reasoning coach for a CAT/MBA aspirant practising time and work at hard difficulty.

The problem is the same every time because the client passes seed=42. The server also writes log lines to stderr; they are not shown here.

Key points​

Launching the server​

StdioServerParameters(command=..., args=[...]) tells the client how to start the server as a subprocess. The client owns the process: it starts when you enter async with Client(...) and stops when the block ends.

Reading results​

Every call_tool result has:

AttributeContains
structured_contentThe JSON object that matches the tool's outputSchema. Use this in code.
contentA list of content blocks (usually text) intended for the AI model.
is_errorTrue when the tool reported an error, such as invalid input.

Two kinds of error​

  1. Tool errors come back as a normal result with is_error=True, as in step 5 of the client. Bad arguments and answers the server cannot read work this way, so a model can read the message and correct itself.
  2. Protocol errors raise an MCPError exception in the client. For example, reading syllabus://section/gk fails with JSON-RPC error code -32602. See the error reference.
from mcp import MCPError

try:
await client.read_resource("syllabus://section/gk")
except MCPError as exc:
print(exc.error.code, exc.error.message)
# -32602 No syllabus for section 'gk'. Use one of: quant, reasoning, varc.

Testing in-process​

For unit tests you can skip the subprocess and pass the server object straight to the client. The test suite does this in server/tests/test_server.py:

from mcp import Client
from edumaths360_mcp.server import mcp

async with Client(mcp) as client:
result = await client.call_tool("generate_problem", {"topic": "time_work"})

This runs the full MCP message exchange in memory, which is fast and needs no process management.

Protocol version​

The SDK client negotiates the newest protocol version both sides support. With SDK 2.x on both sides, that is 2026-07-28, as the first line of the output shows. Hosts that use the older initialize handshake get 2025-11-25, as shown in the JSON-RPC examples.