JSON-RPC examples
MCP messages are JSON-RPC 2.0 objects. On the stdio transport, each message is one line of JSON. This page shows a complete session with the Edumaths360 server, from the handshake to two protocol errors.
:::info Real payloads, not hand-written ones
These messages were captured from the running server by snippets/capture_payloads.py and saved to snippets/example_payloads.json. This page reads that file at build time, so it cannot drift from the captured data. To refresh it after changing the server, run python snippets/capture_payloads.py.
:::
Reading the messages
- A request has an
id, amethodand usuallyparams. The response carries the sameid. - A notification has no
idand gets no response. - A response has either a
resultor anerror, never both. - A tool failure is a
resultwith"isError": true(example 8). A protocol failure is anerror(examples 16 and 17). - Examples 9 and 10 show a VARC item: a para summary question, and a wrong option that gets feedback naming the kind of trap (a narrow distractor) without revealing the right letter.
The capture script uses the initialize handshake with protocol version 2025-11-25, which is what most hosts send today. The MCP Python SDK 2.x client negotiates the newer 2026-07-28 version automatically, but the tool, resource and prompt messages look the same.
The Python SDK tab shows the equivalent call with the SDK client from Connect from a Python client.
The session
1. Handshake: initialize
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "initialize",
"id": 1,
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {
"name": "capture-script",
"version": "1.0"
}
}
}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"capabilities": {
"prompts": {
"listChanged": false
},
"resources": {
"listChanged": false,
"subscribe": false
},
"tools": {
"listChanged": false
}
},
"instructions": "CAT-style practice in quantitative aptitude, DILR/reasoning and VARC for MBA and other competitive-exam aspirants. Use generate_problem to create a problem, let the student attempt it, and use check_answer to mark it. If the student is stuck, call get_hint with level 1 first and only move to higher levels if they are still stuck. Do not solve the problem for the student yourself.",
"protocolVersion": "2025-11-25",
"serverInfo": {
"name": "edumaths360-practice",
"title": "Edumaths360 Practice Server",
"version": "0.3.0"
}
}
}
# The SDK client performs the handshake for you:
async with Client(server) as client:
print(client.server_info, client.protocol_version)
2. Handshake: initialized notification
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "notifications/initialized"
}
Notifications have no id and get no response.
# Sent automatically by the SDK client after initialize.
3. Discover tools
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 2,
"params": {}
}
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"tools": [
{
"annotations": {
"idempotentHint": true,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "Create a CAT-style practice problem in quant, reasoning or VARC. Returns the problem statement and a problem_id, but never the answer. Show the statement to the student and let them attempt it.",
"inputSchema": {
"properties": {
"topic": {
"description": "Quant, reasoning or VARC topic to practise.",
"enum": [
"percentages",
"profit_loss",
"ratio_proportion",
"time_speed_distance",
"time_work",
"interest",
"linear_equations",
"quadratics",
"number_system",
"number_series",
"para_jumbles",
"odd_sentence_out",
"para_summary"
],
"title": "Topic",
"type": "string"
},
"difficulty": {
"default": "medium",
"description": "How challenging the problem should be.",
"enum": [
"easy",
"medium",
"hard"
],
"title": "Difficulty",
"type": "string"
},
"seed": {
"anyOf": [
{
"maximum": 999999,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional seed for a reproducible problem. Omit for a random one.",
"title": "Seed"
}
},
"required": [
"topic"
],
"type": "object",
"title": "generate_problemArguments"
},
"name": "generate_problem",
"outputSchema": {
"properties": {
"problem_id": {
"description": "Stable ID. Pass it to check_answer and get_hint.",
"title": "Problem Id",
"type": "string"
},
"section": {
"description": "Exam section: 'quant', 'reasoning' or 'varc'.",
"title": "Section",
"type": "string"
},
"topic": {
"title": "Topic",
"type": "string"
},
"difficulty": {
"title": "Difficulty",
"type": "string"
},
"seed": {
"description": "Seed used. The same topic, difficulty and seed give the same problem.",
"title": "Seed",
"type": "integer"
},
"statement": {
"description": "The question to show the student.",
"title": "Statement",
"type": "string"
},
"answer_format": {
"description": "How the student should write their answer.",
"title": "Answer Format",
"type": "string"
},
"max_hint_level": {
"title": "Max Hint Level",
"type": "integer"
}
},
"required": [
"problem_id",
"section",
"topic",
"difficulty",
"seed",
"statement",
"answer_format",
"max_hint_level"
],
"type": "object",
"description": "A new practice problem. The answer is deliberately not included.",
"title": "GeneratedProblem"
},
"title": "Generate a practice problem"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": false
},
"description": "Mark a student's answer and give feedback. A wrong answer never reveals the correct one on the first attempts. The worked solution appears only once the student is correct, or after 3 wrong attempts.",
"inputSchema": {
"properties": {
"problem_id": {
"description": "ID returned by generate_problem.",
"maxLength": 32,
"pattern": "^(pct|pl|ratio|tsd|work|int|lin|quad|num|series|pj|odd|sum)-(easy|medium|hard)-(\\d{1,6})$",
"title": "Problem Id",
"type": "string"
},
"answer": {
"description": "The student's answer, for example '1300', 'Rs 1,300', '37.5', '2, -5', '2-4-1-3' (para jumbles), '3' (odd sentence out) or 'B' (para summary).",
"maxLength": 300,
"minLength": 1,
"title": "Answer",
"type": "string"
}
},
"required": [
"problem_id",
"answer"
],
"type": "object",
"title": "check_answerArguments"
},
"name": "check_answer",
"outputSchema": {
"properties": {
"problem_id": {
"title": "Problem Id",
"type": "string"
},
"correct": {
"title": "Correct",
"type": "boolean"
},
"attempt": {
"description": "How many times this problem has been checked in this session.",
"title": "Attempt",
"type": "integer"
},
"feedback": {
"description": "Encouraging, specific feedback. Never contains the answer before the reveal.",
"title": "Feedback",
"type": "string"
},
"solution": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Worked solution. Only present when correct, or after 3 wrong attempts.",
"title": "Solution"
}
},
"required": [
"problem_id",
"correct",
"attempt",
"feedback"
],
"type": "object",
"description": "The result of marking one attempt.",
"title": "AnswerCheck"
},
"title": "Check a student's answer"
},
{
"annotations": {
"idempotentHint": true,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "Give a progressive hint for a problem. Start at level 1 and only go higher if the student is still stuck. Hints guide the student's thinking and never state the final answer.",
"inputSchema": {
"properties": {
"problem_id": {
"description": "ID returned by generate_problem.",
"maxLength": 32,
"pattern": "^(pct|pl|ratio|tsd|work|int|lin|quad|num|series|pj|odd|sum)-(easy|medium|hard)-(\\d{1,6})$",
"title": "Problem Id",
"type": "string"
},
"level": {
"default": 1,
"description": "1 = gentle nudge, 2 = key step, 3 = last step before the answer.",
"maximum": 3,
"minimum": 1,
"title": "Level",
"type": "integer"
}
},
"required": [
"problem_id"
],
"type": "object",
"title": "get_hintArguments"
},
"name": "get_hint",
"outputSchema": {
"properties": {
"problem_id": {
"title": "Problem Id",
"type": "string"
},
"level": {
"title": "Level",
"type": "integer"
},
"max_level": {
"title": "Max Level",
"type": "integer"
},
"hint": {
"title": "Hint",
"type": "string"
},
"next_step": {
"title": "Next Step",
"type": "string"
}
},
"required": [
"problem_id",
"level",
"max_level",
"hint",
"next_step"
],
"type": "object",
"description": "One step of guidance. Hints never state the final answer.",
"title": "Hint"
},
"title": "Get a hint"
}
]
}
}
tools = await client.list_tools()
4. Generate a problem
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 3,
"params": {
"name": "generate_problem",
"arguments": {
"topic": "profit_loss",
"difficulty": "hard",
"seed": 42
}
}
}
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"text": "{\n \"problem_id\": \"pl-hard-42\",\n \"section\": \"quant\",\n \"topic\": \"profit_loss\",\n \"difficulty\": \"hard\",\n \"seed\": 42,\n \"statement\": \"By selling an article for Rs 800, a trader loses 20%. At what price, in rupees, should he sell it to gain 30%?\",\n \"answer_format\": \"a number, for example 450 (no units, % or Rs sign needed)\",\n \"max_hint_level\": 3\n}",
"type": "text"
}
],
"isError": false,
"structuredContent": {
"problem_id": "pl-hard-42",
"section": "quant",
"topic": "profit_loss",
"difficulty": "hard",
"seed": 42,
"statement": "By selling an article for Rs 800, a trader loses 20%. At what price, in rupees, should he sell it to gain 30%?",
"answer_format": "a number, for example 450 (no units, % or Rs sign needed)",
"max_hint_level": 3
}
}
}
result = await client.call_tool(
"generate_problem",
{"topic":"profit_loss","difficulty":"hard","seed":42},
)
print(result.is_error, result.structured_content)
5. Check a wrong answer (percentage of the wrong base)
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 4,
"params": {
"name": "check_answer",
"arguments": {
"problem_id": "pl-hard-42",
"answer": "1040"
}
}
}
{
"jsonrpc": "2.0",
"id": 4,
"result": {
"content": [
{
"text": "{\n \"problem_id\": \"pl-hard-42\",\n \"correct\": false,\n \"attempt\": 1,\n \"feedback\": \"The gain % is worked out on the cost price, not on the old selling price.\",\n \"solution\": null\n}",
"type": "text"
}
],
"isError": false,
"structuredContent": {
"problem_id": "pl-hard-42",
"correct": false,
"attempt": 1,
"feedback": "The gain % is worked out on the cost price, not on the old selling price.",
"solution": null
}
}
}
result = await client.call_tool(
"check_answer",
{"problem_id":"pl-hard-42","answer":"1040"},
)
print(result.is_error, result.structured_content)
6. Ask for a level 2 hint
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 5,
"params": {
"name": "get_hint",
"arguments": {
"problem_id": "pl-hard-42",
"level": 2
}
}
}
{
"jsonrpc": "2.0",
"id": 5,
"result": {
"content": [
{
"text": "{\n \"problem_id\": \"pl-hard-42\",\n \"level\": 2,\n \"max_level\": 3,\n \"hint\": \"To get the cost price, divide Rs 800 by 80 and multiply by 100.\",\n \"next_step\": \"Try the problem again. If still stuck, ask for level 3.\"\n}",
"type": "text"
}
],
"isError": false,
"structuredContent": {
"problem_id": "pl-hard-42",
"level": 2,
"max_level": 3,
"hint": "To get the cost price, divide Rs 800 by 80 and multiply by 100.",
"next_step": "Try the problem again. If still stuck, ask for level 3."
}
}
}
result = await client.call_tool(
"get_hint",
{"problem_id":"pl-hard-42","level":2},
)
print(result.is_error, result.structured_content)
7. Check the correct answer
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 6,
"params": {
"name": "check_answer",
"arguments": {
"problem_id": "pl-hard-42",
"answer": "Rs 1,300"
}
}
}
{
"jsonrpc": "2.0",
"id": 6,
"result": {
"content": [
{
"text": "{\n \"problem_id\": \"pl-hard-42\",\n \"correct\": true,\n \"attempt\": 2,\n \"feedback\": \"Correct! Well done. Now try to solve the next one faster.\",\n \"solution\": \"CP = 800 × 100/80 = 1000 → new SP = 1000 × 130/100 = 1300\"\n}",
"type": "text"
}
],
"isError": false,
"structuredContent": {
"problem_id": "pl-hard-42",
"correct": true,
"attempt": 2,
"feedback": "Correct! Well done. Now try to solve the next one faster.",
"solution": "CP = 800 × 100/80 = 1000 → new SP = 1000 × 130/100 = 1300"
}
}
}
result = await client.call_tool(
"check_answer",
{"problem_id":"pl-hard-42","answer":"Rs 1,300"},
)
print(result.is_error, result.structured_content)
8. Tool error: answer without a number
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 7,
"params": {
"name": "check_answer",
"arguments": {
"problem_id": "pl-hard-42",
"answer": "no idea"
}
}
}
{
"jsonrpc": "2.0",
"id": 7,
"result": {
"content": [
{
"text": "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).",
"type": "text"
}
],
"isError": true
}
}
result = await client.call_tool(
"check_answer",
{"problem_id":"pl-hard-42","answer":"no idea"},
)
print(result.is_error, result.structured_content)
9. Generate a VARC problem (para summary)
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 8,
"params": {
"name": "generate_problem",
"arguments": {
"topic": "para_summary",
"difficulty": "medium",
"seed": 42
}
}
}
{
"jsonrpc": "2.0",
"id": 8,
"result": {
"content": [
{
"text": "{\n \"problem_id\": \"sum-medium-42\",\n \"section\": \"varc\",\n \"topic\": \"para_summary\",\n \"difficulty\": \"medium\",\n \"seed\": 42,\n \"statement\": \"Read the passage and choose the option that best captures its essence.\\n\\nPassage: Many museums in Europe hold objects that were taken from other countries during colonial rule. For decades, curators argued that these collections were safer and more widely seen in major museums. That argument has weakened as countries of origin have built well-equipped museums of their own, and as visitors have grown more interested in how objects were acquired. Several institutions have now returned items, while others are lending them back or sharing ownership.\\n\\nA. Countries of origin have built well-equipped museums of their own.\\nB. As the old case for keeping colonial-era artefacts weakens, museums are increasingly returning, lending or sharing them.\\nC. All museums will soon have to return every object that came from another country.\\nD. Museums keep colonial-era objects because they are still safer in Europe.\",\n \"answer_format\": \"the letter of one option (A, B, C or D), or the option's full text\",\n \"max_hint_level\": 3\n}",
"type": "text"
}
],
"isError": false,
"structuredContent": {
"problem_id": "sum-medium-42",
"section": "varc",
"topic": "para_summary",
"difficulty": "medium",
"seed": 42,
"statement": "Read the passage and choose the option that best captures its essence.\n\nPassage: Many museums in Europe hold objects that were taken from other countries during colonial rule. For decades, curators argued that these collections were safer and more widely seen in major museums. That argument has weakened as countries of origin have built well-equipped museums of their own, and as visitors have grown more interested in how objects were acquired. Several institutions have now returned items, while others are lending them back or sharing ownership.\n\nA. Countries of origin have built well-equipped museums of their own.\nB. As the old case for keeping colonial-era artefacts weakens, museums are increasingly returning, lending or sharing them.\nC. All museums will soon have to return every object that came from another country.\nD. Museums keep colonial-era objects because they are still safer in Europe.",
"answer_format": "the letter of one option (A, B, C or D), or the option's full text",
"max_hint_level": 3
}
}
}
result = await client.call_tool(
"generate_problem",
{"topic":"para_summary","difficulty":"medium","seed":42},
)
print(result.is_error, result.structured_content)
10. Check a VARC answer (a narrow distractor)
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 9,
"params": {
"name": "check_answer",
"arguments": {
"problem_id": "sum-medium-42",
"answer": "A"
}
}
}
{
"jsonrpc": "2.0",
"id": 9,
"result": {
"content": [
{
"text": "{\n \"problem_id\": \"sum-medium-42\",\n \"correct\": false,\n \"attempt\": 1,\n \"feedback\": \"That option is true to the passage but covers only one detail or example, not the main point.\",\n \"solution\": null\n}",
"type": "text"
}
],
"isError": false,
"structuredContent": {
"problem_id": "sum-medium-42",
"correct": false,
"attempt": 1,
"feedback": "That option is true to the passage but covers only one detail or example, not the main point.",
"solution": null
}
}
}
result = await client.call_tool(
"check_answer",
{"problem_id":"sum-medium-42","answer":"A"},
)
print(result.is_error, result.structured_content)
11. List static resources
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "resources/list",
"id": 10,
"params": {}
}
{
"jsonrpc": "2.0",
"id": 10,
"result": {
"resources": [
{
"description": "Every topic the server can generate, grouped by exam section (quant, reasoning or varc).",
"mimeType": "application/json",
"name": "all_topics",
"title": "All topics",
"uri": "syllabus://topics"
}
]
}
}
resources = await client.list_resources()
12. List resource templates
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "resources/templates/list",
"id": 11,
"params": {}
}
{
"jsonrpc": "2.0",
"id": 11,
"result": {
"resourceTemplates": [
{
"description": "Topics and difficulty levels in one section: 'quant', 'reasoning' or 'varc'.",
"mimeType": "application/json",
"name": "section_syllabus",
"title": "Syllabus for one exam section",
"uriTemplate": "syllabus://section/{section}"
}
]
}
}
templates = await client.list_resource_templates()
13. Read a resource
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "resources/read",
"id": 12,
"params": {
"uri": "syllabus://section/varc"
}
}
{
"jsonrpc": "2.0",
"id": 12,
"result": {
"contents": [
{
"mimeType": "application/json",
"text": "{\n \"section\": \"varc\",\n \"description\": \"Verbal ability (VARC): para jumbles, odd sentence out and para summary, on original passages.\",\n \"topics\": [\n {\n \"topic\": \"para_jumbles\",\n \"section\": \"varc\",\n \"area\": \"verbal ability\",\n \"description\": \"Arrange four or five shuffled sentences into a coherent paragraph (TITA order answer).\",\n \"difficulties\": [\n \"easy\",\n \"medium\",\n \"hard\"\n ]\n },\n {\n \"topic\": \"odd_sentence_out\",\n \"section\": \"varc\",\n \"area\": \"verbal ability\",\n \"description\": \"Find the one sentence out of five that does not belong to the paragraph (TITA).\",\n \"difficulties\": [\n \"easy\",\n \"medium\",\n \"hard\"\n ]\n },\n {\n \"topic\": \"para_summary\",\n \"section\": \"varc\",\n \"area\": \"verbal ability\",\n \"description\": \"Choose the option (A to D) that best summarises a short passage.\",\n \"difficulties\": [\n \"easy\",\n \"medium\",\n \"hard\"\n ]\n }\n ]\n}",
"uri": "syllabus://section/varc"
}
]
}
}
result = await client.read_resource("syllabus://section/varc")
print(result.contents[0].text)
14. List prompts
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "prompts/list",
"id": 13,
"params": {}
}
{
"jsonrpc": "2.0",
"id": 13,
"result": {
"prompts": [
{
"arguments": [
{
"name": "topic",
"required": false
},
{
"name": "difficulty",
"required": false
}
],
"description": "Run a CAT-style practice session where the assistant asks guiding questions instead of giving answers.",
"name": "socratic_tutor",
"title": "Socratic quant tutor"
}
]
}
}
prompts = await client.list_prompts()
15. Get a prompt
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "prompts/get",
"id": 14,
"params": {
"name": "socratic_tutor",
"arguments": {
"topic": "time_work",
"difficulty": "hard"
}
}
}
{
"jsonrpc": "2.0",
"id": 14,
"result": {
"description": "Run a CAT-style practice session where the assistant asks guiding questions instead of giving answers.",
"messages": [
{
"content": {
"text": "You are a patient quantitative aptitude and reasoning coach for a CAT/MBA aspirant practising time and work at hard difficulty.\n\nRules:\n1. Call generate_problem with topic='time_work' and difficulty='hard', then show the student the statement.\n2. Never solve the problem for the student and never state the final answer yourself.\n3. Ask one short guiding question at a time, for example 'What is the cost price here?'.\n4. When the student gives an answer, call check_answer and share the feedback in your own words.\n5. If the student is stuck, call get_hint starting at level 1. Only go to the next level if they are still stuck after trying.\n6. Praise method and reasoning, not only correct answers. Once they are correct, ask whether a faster approach (a shortcut or an elimination trick) would also work, as it would in the exam.\n\nStart by greeting the student and generating the first problem.",
"type": "text"
},
"role": "user"
}
]
}
}
prompt = await client.get_prompt("socratic_tutor", {"topic":"time_work","difficulty":"hard"})
16. Protocol error: resource not found
- JSON-RPC
- Python SDK
{
"jsonrpc": "2.0",
"method": "resources/read",
"id": 15,
"params": {
"uri": "syllabus://section/gk"
}
}
{
"jsonrpc": "2.0",
"id": 15,
"error": {
"code": -32602,
"message": "No syllabus for section 'gk'. Use one of: quant, reasoning, varc.",
"data": {
"uri": "syllabus://section/gk"
}
}
}
result = await client.read_resource("syllabus://section/gk")
print(result.contents[0].text)
17. Protocol error: unknown method
- JSON-RPC
{
"jsonrpc": "2.0",
"method": "tools/unknown_method",
"id": 16,
"params": {}
}
{
"jsonrpc": "2.0",
"id": 16,
"error": {
"code": -32601,
"message": "Method not found",
"data": "tools/unknown_method"
}
}
Error codes used by this server
| Code | Meaning | Example |
|---|---|---|
-32601 | Method not found | Example 17 |
-32602 | Invalid params: unknown resource, or invalid prompt arguments | Example 16 |
isError: true | Not a JSON-RPC error: the tool ran and reported a problem | Example 8 |