Serverul MCP Satelit

Adresa și protocolul

Un singur endpoint pentru ambele ere ale protocolului. Fără flux SSE și fără Mcp-Session-Id: fiecare cerere e completă.

2026-07-28, fără stare

• O cerere care are _meta["io.modelcontextprotocol/protocolVersion"] e în era nouă.
• Antetele MCP-Protocol-Version și Mcp-Method trebuie să fie egale cu corpul, iar Mcp-Name cu instrumentul la tools/call (=?base64?…?= se decodează). Altfel 400 -32020.
• O altă versiune: 400 -32022 cu supported.
• Rezultatele au resultType: "complete" și _meta["io.modelcontextprotocol/serverInfo"]. server/discover și tools/list au ttlMs și cacheScope: public.

2025-11-25, 2025-06-18, 2025-03-26

• initialize răspunde cu versiunea cerută când o știe, altfel cu 2025-11-25.
• notifications/* primesc 202, ping primește {}.
• Antetul MCP-Protocol-Version, când există, trebuie să fie una dintre aceste versiuni.

Restul

• Metodă necunoscută: -32601 (404 în era nouă). Instrument necunoscut: -32602. Un lot de cereri: 400.
• GET și DELETE: 405 cu Allow. Un Origin care nu e https și nici această mașină: 403.
• resources/list și prompts/list răspund cu liste goale.

curl https://api.satelit.md/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: search_prices" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_prices","arguments":{"query":"lapte 2.5%","lang":"ro"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}'

curl https://api.satelit.md/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0"}}}'

Intrarea: OAuth 2.1

Fără token răspund handshake-ul, ping și tools/list, iar câteva căutări de preț pe zi merg (la Planuri). Orice alt apel, sau încercarea consumată, primește 401 cu WWW-Authenticate și adresa metadatei resursei: de acolo pornește autentificarea clientului (autentificare la nevoie). Cu token: Authorization: Bearer, făcut pentru acest server și verificat la fiecare cerere; un token pentru altceva primește 401, unul fără scopul mcp 403 insufficient_scope. tools/list marchează securitySchemes la fiecare instrument.

Metadata

• Resursa protejată (RFC 9728): https://api.satelit.md/.well-known/oauth-protected-resource/mcp, și fără /mcp.
• Serverul de autorizare: https://app.satelit.md, cu /.well-known/oauth-authorization-server și /.well-known/openid-configuration.
• Doar fluxul cu cod și PKCE S256. Scopuri: mcp offline_access; openid e opțional.

Cum se înregistrează aplicația

• Client ID Metadata Documents: un client_id care e o adresă https cu cale. O citim (adrese publice, port 443, 5 s, 32 KB, fără redirect), trebuie să se numească pe sine și să nu poarte numele Satelit. token_endpoint_auth_method: none sau private_key_jwt cu un jwks_uri pe aceeași gazdă. O recitim după 24 de ore.
• Înregistrare dinamică (RFC 7591): POST https://app.satelit.md/api/oauth/register cu redirect_uris. Adrese https, sau http pe localhost, niciodată o gazdă Satelit. 10 pe oră de la o adresă. O aplicație pe care n-a aprobat-o nimeni în 7 zile se șterge.
• O aplicație de pe calculator poate folosi orice port al adresei loopback înregistrate (RFC 8252 7.3).

Tokenuri legate de server

• resource (RFC 8707) la authorize și la token: doar https://api.satelit.md/mcp, altfel invalid_target. Scopul mcp fără resource înseamnă aceeași resursă.
• aud al tokenului de acces e adresa serverului: nu deschide nimic altceva, nici userinfo.
• Accesul trăiește mai mult decât sesiunea din browser: ieșirea de pe site nu deconectează aplicația. Se termină când persoana o deconectează în Setări, la Aplicații conectate, când contul e oprit sau șters, ori după 60 de zile fără folosire.

Ecranul de acord spune gazda la care pleacă codul (chatgpt.com, claude.ai, 127.0.0.1), ce poate face aplicația și ce nu trece niciodată.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
  resource_metadata="https://api.satelit.md/.well-known/oauth-protected-resource/mcp",
  scope="mcp offline_access"

{
  "resource": "https://api.satelit.md/mcp",
  "authorization_servers": [
    "https://app.satelit.md"
  ],
  "scopes_supported": [
    "mcp",
    "offline_access"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "resource_name": "Satelit",
  "resource_documentation": "https://developer.satelit.md/en/mcp/",
  "resource_policy_uri": "https://satelit.md/en/privacy/",
  "resource_tos_uri": "https://satelit.md/en/terms/"
}

Răspunsurile structurate

Un refuz e un rezultat cu isError: true și un corp pe care aplicația AI îl poate spune omului. Conversația continuă. Niciun preț și nicio reclamă în răspunsuri.

• plan_requiredinstrumentul cere un plan mai mare: needed_plan, your_plan, adds, plans_page, message.
• limit_reachedo limită: limit (minute, day, writes, distinct, pool, pages, watches), retry_after_s, apoi next_plan, adds, plans_page, sau bulk (API-ul) peste ultimul plan.
• moreplanul a tăiat o listă: shown, found, next_plan, plans_page. Lipsește când nu s-a tăiat nimic.
• search_firstun id care nu vine dintr-o căutare de azi a persoanei.
• confirm_emailadresa de e-mail a contului nu e confirmată.

{
  "status": "plan_required",
  "needed_plan": "Satelit Familie",
  "your_plan": "Satelit Gratuit",
  "adds": [
    "…"
  ],
  "plans_page": "https://satelit.md/ro/abonamente/",
  "message": "…"
}

{
  "query": "lapte 2.5%",
  "currency": "MDL",
  "page": 1,
  "pages": 1,
  "products": [
    "…"
  ],
  "found": 48,
  "more": {
    "shown": 5,
    "found": 48,
    "message": "…",
    "next_plan": "Satelit Familie",
    "plans_page": "…"
  }
}

Configurarea clienților

ChatGPT, Claude, Perplexity și Gemini primesc adresa în setările lor, apoi deschid intrarea în Satelit. Editorii și liniile de comandă:

Instalează în Cursor Instalează în VS Code

Încearcă

Un apel care cere cont primește 401 cu adresa metadatei: de acolo orice client se autentifică. MCP Inspector și claude mcp add fac tot drumul.

claude mcp add --transport http satelit https://api.satelit.md/mcp

gemini mcp add --transport http satelit https://api.satelit.md/mcp

{
  "mcpServers": {
    "satelit": {
      "url": "https://api.satelit.md/mcp"
    }
  }
}

{
  "servers": {
    "satelit": {
      "type": "http",
      "url": "https://api.satelit.md/mcp"
    }
  }
}