Skip to main content

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, a method and usually params. The response carries the same id.
  • A notification has no id and gets no response.
  • A response has either a result or an error, never both.
  • A tool failure is a result with "isError": true (example 8). A protocol failure is an error (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​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "initialize",
"id": 1,
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {
"name": "capture-script",
"version": "1.0"
}
}
}
Response (server → client)
{
"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"
}
}
}

2. Handshake: initialized notification​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "notifications/initialized"
}

Notifications have no id and get no response.

3. Discover tools​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 2,
"params": {}
}
Response (server → client)
{
"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"
}
]
}
}

4. Generate a problem​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 3,
"params": {
"name": "generate_problem",
"arguments": {
"topic": "profit_loss",
"difficulty": "hard",
"seed": 42
}
}
}
Response (server → client)
{
"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
}
}
}

5. Check a wrong answer (percentage of the wrong base)​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 4,
"params": {
"name": "check_answer",
"arguments": {
"problem_id": "pl-hard-42",
"answer": "1040"
}
}
}
Response (server → client)
{
"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
}
}
}

6. Ask for a level 2 hint​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 5,
"params": {
"name": "get_hint",
"arguments": {
"problem_id": "pl-hard-42",
"level": 2
}
}
}
Response (server → client)
{
"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."
}
}
}

7. Check the correct answer​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 6,
"params": {
"name": "check_answer",
"arguments": {
"problem_id": "pl-hard-42",
"answer": "Rs 1,300"
}
}
}
Response (server → client)
{
"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"
}
}
}

8. Tool error: answer without a number​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 7,
"params": {
"name": "check_answer",
"arguments": {
"problem_id": "pl-hard-42",
"answer": "no idea"
}
}
}
Response (server → client)
{
"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
}
}

9. Generate a VARC problem (para summary)​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 8,
"params": {
"name": "generate_problem",
"arguments": {
"topic": "para_summary",
"difficulty": "medium",
"seed": 42
}
}
}
Response (server → client)
{
"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
}
}
}

10. Check a VARC answer (a narrow distractor)​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 9,
"params": {
"name": "check_answer",
"arguments": {
"problem_id": "sum-medium-42",
"answer": "A"
}
}
}
Response (server → client)
{
"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
}
}
}

11. List static resources​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "resources/list",
"id": 10,
"params": {}
}
Response (server → client)
{
"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"
}
]
}
}

12. List resource templates​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "resources/templates/list",
"id": 11,
"params": {}
}
Response (server → client)
{
"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}"
}
]
}
}

13. Read a resource​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "resources/read",
"id": 12,
"params": {
"uri": "syllabus://section/varc"
}
}
Response (server → client)
{
"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"
}
]
}
}

14. List prompts​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "prompts/list",
"id": 13,
"params": {}
}
Response (server → client)
{
"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"
}
]
}
}

15. Get a prompt​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "prompts/get",
"id": 14,
"params": {
"name": "socratic_tutor",
"arguments": {
"topic": "time_work",
"difficulty": "hard"
}
}
}
Response (server → client)
{
"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"
}
]
}
}

16. Protocol error: resource not found​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "resources/read",
"id": 15,
"params": {
"uri": "syllabus://section/gk"
}
}
Response (server → client)
{
"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"
}
}
}

17. Protocol error: unknown method​

Request (client → server)
{
"jsonrpc": "2.0",
"method": "tools/unknown_method",
"id": 16,
"params": {}
}
Response (server → client)
{
"jsonrpc": "2.0",
"id": 16,
"error": {
"code": -32601,
"message": "Method not found",
"data": "tools/unknown_method"
}
}

Error codes used by this server​

CodeMeaningExample
-32601Method not foundExample 17
-32602Invalid params: unknown resource, or invalid prompt argumentsExample 16
isError: trueNot a JSON-RPC error: the tool ran and reported a problemExample 8