Ce face Mesaje JSON-RPC, _meta și coduri de eroare MCP
Toate mesajele MCP urmează JSON-RPC 2.0 și sunt codificate UTF-8. Cererile au un id string sau întreg, care nu poate fi null și nu poate repeta id-ul unei alte cereri aflate încă în așteptare. Răspunsurile au același id și conțin fie result, fie error (cu code întreg și message). Notificările nu au id și nu primesc răspuns. În 2026-07-28 serverele nu inițiază cereri, iar clienții nu trimit răspunsuri.
Orice result conține câmpul resultType: complete pentru rezultatul final și input_required pentru rezultatul intermediar al unei cereri în mai mulți pași (MRTR). Extensiile pot adăuga valori proprii. Un rezultat fără resultType, venit de la un server cu o revizie mai veche, se tratează ca complete; o valoare necunoscută clientului este invalidă.
Câmpul _meta poartă metadatele de protocol. Fiecare cerere include obligatoriu io.modelcontextprotocol/protocolVersion și io.modelcontextprotocol/clientCapabilities; lipsa lor duce la eroarea -32602 (pe HTTP cu 400). Dacă o cerere are nevoie de o capabilitate pe care clientul n-a declarat-o, serverul întoarce MissingRequiredClientCapabilityError (-32021) cu data.requiredCapabilities. Prefixele de cheie a căror a doua etichetă este modelcontextprotocol sau mcp (de exemplu io.modelcontextprotocol/, dev.mcp/) sunt rezervate protocolului.
Sintaxă și opțiuni
| Opțiune / Parametru | Descriere |
|---|---|
io.modelcontextprotocol/protocolVersion |
Obligatoriu în fiecare cerere, de exemplu "2026-07-28". |
io.modelcontextprotocol/clientCapabilities |
Obligatoriu în fiecare cerere: capabilitățile clientului relevante pentru cerere. |
io.modelcontextprotocol/clientInfo |
Opțional, dar recomandat în fiecare cerere: numele și versiunea clientului. |
io.modelcontextprotocol/logLevel |
Opțional: nivelul minim de log pentru această cerere (Logging, depreciat). |
progressToken |
Cere notificări notifications/progress pentru cerere. |
io.modelcontextprotocol/subscriptionId |
Pe notificările unui stream subscriptions/listen: id-ul cererii care l-a deschis. |
io.modelcontextprotocol/serverInfo |
În _meta-ul rezultatelor (recomandat): numele și versiunea serverului. |
traceparent, tracestate, baggage |
Propagarea contextului OpenTelemetry, în formatele W3C Trace Context și W3C Baggage. |
-32700, -32600 … -32603 |
Codurile standard JSON-RPC (parse error, invalid request, method not found, invalid params, internal error). |
-32020 HeaderMismatch |
Antetele HTTP nu corespund corpului cererii sau lipsesc. |
-32021 MissingRequiredClientCapability |
Cererea cere o capabilitate nedeclarată de client. |
-32022 UnsupportedProtocolVersion |
Versiunea cerută nu este implementată de server. |
-32000 … -32019 |
Interval legacy: nu se alocă coduri noi aici. Intervalul -32020 … -32099 este rezervat specificației. |
Exemple practice
Exemplul 1: Context OpenTelemetry în _meta
Exemplul neformativ din specificație; restul câmpurilor _meta obligatorii sunt omise pentru scurtime.
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"location": "New York"
},
"_meta": {
"traceparent": "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
}
}
}Exemplul 2: Forma generală a unui rezultat
{
jsonrpc: "2.0";
id: string | number;
result: {
resultType: string;
[key: string]: unknown;
};
}Greșeli frecvente și bune practici
- Trimiți capabilitățile o singură dată și te bazezi pe conexiune. Serverul nu are voie să deducă context din cererile anterioare; fiecare cerere își poartă propriile metadate.
- Emiți coduri din intervalul
-32020…-32099care nu sunt definite de specificație. Codurile proprii se alocă în afara intervalului rezervat JSON-RPC (-32768…-32000). - Folosești
clientInfoca identitate verificată. Este auto-raportat; identitatea vine din autorizare.