# Server MCP

Leagă Claude sau alt asistent compatibil MCP de platformă, ca să citească datele firmei tale.

## Ce este

Platforma are un server [Model Context Protocol](https://modelcontextprotocol.io) la adresa:

```text title="Adresa serverului"
https://app.ilustromania.com/nucleu/v1/mcp
```

Un asistent conectat aici primește un set de **unelte doar de citire**. Uneltele citesc aceleași date ca rutele platformei, cu aceleași drepturi (`firme_acord_listeaza` o servește direct serverul MCP): asistentul nu poate vedea nimic din ce nu ai vedea tu în aplicație.

> [!NOTE]
> Toate uneltele sunt de citire. Serverul MCP nu poate schimba prețuri, produse sau date ale firmei.

## Conectarea

1. În asistent (de exemplu Claude), adaugă un conector personalizat cu adresa de mai sus.
2. Asistentul descoperă singur serverul de autorizare prin metadatele OAuth și se înregistrează ca client (vezi [OAuth](#oauth)).
3. Te trimite pe pagina de acord a platformei, unde intri în cont și alegi **firmele** la care îi dai acces.
4. După acord, asistentul primește un jeton `mcp_…` și îl trimite la fiecare apel.

## Protocolul

| Caracteristică | Valoare |
| --- | --- |
| Transport | HTTP, `POST /v1/mcp`, mesaje JSON-RPC 2.0, răspuns JSON (fără flux SSE) |
| Autentificare | `Authorization: Bearer mcp_…`; cookie-ul de sesiune nu este acceptat |
| Versiuni | `2025-06-18` (implicită), `2025-03-26`, `2024-11-05` |
| Capabilități | `tools` |
| Metode | `initialize`, `ping`, `tools/list`, `tools/call` |
| Notificări | răspuns `202` fără corp |
| `GET /v1/mcp` | `405`, antet `Allow: POST` |

```bash title="Lista uneltelor"
curl https://app.ilustromania.com/nucleu/v1/mcp \
  -H "Authorization: Bearer $JETON_MCP" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

```json title="Apelul unei unelte"
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "firme_acord_listeaza",
    "arguments": {}
  }
}
```

## Uneltele

| Unealtă | Ce întoarce |
| --- | --- |
| `firme_acord_listeaza` | firmele la care ai dat acces acestui client și pe care mai ai rol (doar id și nume); id-ul se dă ca parametrul `firma` celorlalte unelte |
| `agenti_executori_listeaza` | agenții din registrul platformei, cu starea lor |
| `claude_sesiuni_stare_citeste` | starea sesiunilor Claude din ultimele 24 de ore |
| `acces_roluri_listeaza` | rolurile platformei și drepturile fiecăruia (doar nume, fără persoane) |

## Siguranță și limite

- Rolul tău se citește **live** la fiecare apel. Dacă rolul îți este retras într-o firmă, uneltele refuză imediat acea firmă, chiar dacă jetonul este încă valid.
- Răspunsul unei unelte are cel mult 100 000 de caractere; un apel durează cel mult 20 de secunde.
- Pe același jeton rulează cel mult 4 apeluri `tools/call` deodată; al cincilea primește eroarea JSON-RPC `-32001` (ocupat).
- Fără jeton valid, serverul primește cel mult 120 de cereri la 10 minute de pe aceeași adresă IP, apoi răspunde `429`.
- Jetonul se poate revoca oricând (`POST /v1/oauth/revoca`).