# Leagă un asistent prin MCP

Ghid de la cap la coadă: adaugi platforma ca conector în Claude, dai acordul pe firme, verifici legătura și știi cum o oprești.

## Ce obții

La final, asistentul tău (de exemplu Claude) poate răspunde la întrebări ca „ce produse am oprite azi?” sau „cât costă ciorba pe Glovo?”, citind direct din platformă. Asistentul **doar citește**: nu poate schimba prețuri, produse sau alte date. Vede numai firmele pe care le bifezi tu și numai ce ai vedea tu în aplicație.

Îți trebuie:

- un cont în platformă, cu rol pe firma pe care vrei s-o legi;
- un asistent care acceptă conectori MCP la distanță, cu autorizare OAuth (Claude pe web, pe desktop sau Claude Code).

Adresa serverului, pe care o vei lipi în asistent:

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

## Pașii

### Adaugă conectorul în asistent

În Claude, deschide setările conectorilor și adaugă un **conector personalizat** cu adresa de mai sus. Nu ai nimic de completat la „client” sau „secret”: asistentul se înregistrează singur.

În Claude Code, adaugă serverul cu transport HTTP, apoi pornește autentificarea din lista serverelor MCP:

```bash title="Claude Code"
claude mcp add --transport http platforma https://app.ilustromania.com/nucleu/v1/mcp
```

### Lasă asistentul să găsească autorizarea

La prima cerere fără jeton, serverul răspunde `401` cu antetul `WWW-Authenticate`, care arată spre metadatele OAuth. De acolo asistentul află singur unde se înregistrează, unde cere acordul și unde primește jetonul. Detaliile sunt în [OAuth 2.1](#oauth).

Platforma acceptă două feluri de adrese de întoarcere: adresa conectorului Claude și o adresă locală cu port (`http://localhost:<port>/…` sau `http://127.0.0.1:<port>/…`), cum folosește Claude Code. Orice alt client este refuzat la înregistrare.

### Dă acordul

Se deschide pagina platformei **„Permiți accesul?”**. Intră în cont dacă nu ești deja. Pagina arată:

- numele aplicației care cere accesul și adresa spre care pleacă accesul;
- dreptul cerut: „Citește meniul și starea, nu modifică nimic.”;
- firmele tale, **toate bifate la început**. Debifează firmele pe care nu vrei să le vadă asistentul.

Numele aplicației îl declară chiar aplicația, platforma nu îl verifică. Apasă **Permite** doar dacă tu ai pornit conectarea, chiar acum. Altfel, apasă **Refuză**.

Pagina de acord e valabilă 10 minute. Dacă a expirat, pornește din nou conectarea din asistent.

### Verifică legătura

Cere-i asistentului ceva simplu, de exemplu „ce firme vezi în platformă?”. Asistentul cheamă unealta `firme_acord_listeaza` și îți arată firmele bifate la acord.

Dacă ai bifat **mai multe firme**, asistentul trebuie să spună la fiecare întrebare despre ce firmă e vorba. Dacă uită, primește mesajul: „Acordul are mai multe firme: cheamă întâi unealta firme_acord_listeaza și dă id-ul firmei în parametrul firma.” Cu o singură firmă bifată, nu e nevoie de nimic în plus.

### Folosește-l

Uneltele disponibile sunt în [Server MCP](#mcp): produsele și categoriile meniului, un produs anume, prețurile pe Wolt, Bolt și Glovo și produsele oprite într-o zi. Asistentul alege singur unealta potrivită întrebării tale.

## Cât ține legătura

| Ce | Cât |
| --- | --- |
| Pagina de acord | 10 minute |
| Jetonul de acces | 1 oră |
| Jetonul de reîmprospătare | 30 de zile, înlocuit cu unul nou la fiecare folosire |

Asistentul își reînnoiește singur jetonul de acces. Dacă nu folosește legătura 30 de zile, îți va cere din nou acordul.

## Cum oprești accesul

- **Scoate conectorul din asistent.** Asistentul nu mai cere date.
- **Revocă jetonul.** Aplicația care are jetonul îl poate anula cu `POST /v1/oauth/revoca`, cu câmpurile `token` și `client_id`.
- **Retrage rolul pe firmă.** Rolul se verifică la fiecare apel. Dacă un om nu mai are rol pe o firmă, asistentul lui nu mai primește nimic de la acea firmă, chiar dacă jetonul e încă valabil.

## Dacă ceva nu merge

| Ce vezi | Ce înseamnă | Ce faci |
| --- | --- | --- |
| Asistentul spune că serverul cere autentificare | nu are încă jeton sau jetonul a expirat | pornește din nou conectarea din asistent |
| „Cererea de conectare nu este valida.” | linkul de autorizare e greșit sau a expirat | pornește din nou de la asistent, nu din istoricul browserului |
| „Contul tău nu are nicio firmă la care să dai acces.” | contul tău nu are rol pe nicio firmă | cere unui administrator al firmei un rol |
| „Firma nu e în acest acord sau nu mai ai acces la ea.” | firma nu a fost bifată sau ți s-a retras rolul | refă conectarea și bifează firma |
| Eroarea `-32001` („ocupat”) | asistentul a pornit mai mult de 4 apeluri deodată | așteaptă câteva secunde și întreabă din nou |
| Răspuns care se termină cu `[TRUNCHIAT: …]` | rezultatul avea peste 100 000 de caractere | cere o listă mai scurtă, cu un filtru |
| `429` | prea multe cereri fără jeton de pe aceeași adresă (peste 120 în 10 minute) | așteaptă cât spune antetul `Retry-After` |

> [!NOTE]
> Legătura merge doar cu jetonul `mcp_…` primit prin acord. Sesiunea din browser nu este acceptată pe `/v1/mcp`, deci nu poți lega un asistent copiind cookie-ul din aplicație.