How JSON‑RPC Batch Processing and Tool Annotations Boost MCP Protocol Efficiency

JSON‑RPC Batch Processing

Background and motivation : In the previous MCP version each request had to be sent individually, which limited efficiency for scenarios that need to invoke several tools or perform bulk operations. Batch processing allows a client to package multiple calls into one request, reducing round‑trip latency and server load.

The MCP specification now aligns with JSON‑RPC 2.0 batch mode, permitting an array of request objects to be sent via a single POST.

[
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {"name": "sum", "arguments": {"a": 1, "b": 2}}
  },
  {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {"name": "multiply", "arguments": {"x": 5, "y": 6}}
  }
]

When the server receives this batch, it can execute the calls in parallel or sequentially and return an array of corresponding responses:

[
  {"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "3"}]}},
  {"jsonrpc": "2.0", "id": 2, "result": {"content": [{"type": "text", "text": "30"}]}}
]

Impact and considerations : Clients must track each request’s id to match responses, and error handling becomes more complex because a single batch may contain a mix of successful results and error objects. When communicating with older servers that do not support batch mode, clients should fall back to individual requests after version negotiation.

Enhanced Tool Annotations

Background and motivation : Automatic tool calls by AI agents can pose security and usability risks if the model lacks insight into a tool’s side effects. The new optional annotations field in tool metadata supplies hints about behavior, read‑only status, destructiveness, idempotency, and external interactions.

title : Human‑readable name shown to users or models.

readOnlyHint : true if the tool does not modify the environment.

destructiveHint : true if the tool may perform harmful actions.

idempotentHint : true if repeated calls with the same arguments produce the same result.

openWorldHint : true if the tool interacts with external systems such as web searches or databases.

These hints are advisory; clients should not rely on them unless the tool source is trusted.

@app.tool(
    name="delete_file",
    annotations=types.ToolAnnotations(
        title="文件删除工具",
        readOnlyHint=False,
        destructiveHint=True,
        idempotentHint=True,
        openWorldHint=False
    )
)

def delete_file(query: str) -> str:
    ...

Impact and applications : With annotations, LLMs can prioritize safe, read‑only tools, request user confirmation before invoking destructive ones, and display warning icons in UI panels. For complex workflows involving many tools, annotations help trace which calls affect external state, aiding debugging and audit trails.