Salt la conținutul principal
Română— Alege o limbă
Meniu

server_url și server_label

Lecția 4 din 12 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Cei doi parametri indispensabili
  2. server_url: Adresa exactă a endpoint-ului
  3. server_label: Identitatea serverului în conversație
  4. Configurație minimă în ambele SDK-uri
  5. Puncte cheie

Actualizat la 3 noiembrie 2026 pe baza paginii Remote MCP Tools de la xAI: server_label adaugă un prefix apelurilor de instrumente, dar documentația nu specifică formatul exact al prefixului; notația label__tool folosită în acest curs este o convenție de lectură—verificați formatul real în răspunsurile API. Sursă: Remote MCP Tools.

Cei doi parametri indispensabili

Fiecare conexiune între Grok și un server MCP la distanță se bazează pe doi parametri: server_url și server_label. Aceștia sunt non-negociabili—fără ei, API respinge cererea înainte de a încerca orice altceva. Toți ceilalți parametri pe care îi veți întâlni ulterior rafinează această fundație; nu o înlocuiesc niciodată.

server_url
Unde este localizat serverul
server_label
Cum se identifică serverul

server_url: Adresa exactă a endpoint-ului

Parametrul server_url conține URL-ul complet al serverului MCP la care trebuie să se conecteze Grok, iar acest URL respectă reguli stricte.

Prima regulă este HTTPS. URL-ul trebuie să înceapă cu https://, iar xAI respinge orice conexiune HTTP necriptată. Motivul este simplu: schimburile dintre Grok și serverul MCP transportă cererile utilizatorilor dumneavoastră, rezultatele instrumentelor și, uneori, chiar token-ul de autentificare. Lăsarea acestor date să circule în text clar ar fi indefensabilă.

# Corect
mcp(server_url="https://mcp.deepwiki.com/mcp")

# Respins de API
mcp(server_url="http://mcp.deepwiki.com/mcp")

A doua regulă privește precizia căii. URL-ul trebuie să indice direct către endpoint-ul MCP, nu către rădăcina domeniului. Aproape toate serverele își expun endpoint-ul pe o cale dedicată, iar convenția variază de la unul la altul. Iată trei forme valide pe care le veți întâlni:

https://mcp.deepwiki.com/mcp
https://api.example.com/mcp
https://tools.monentreprise.com/v1/mcp

A treia regulă decurge din primele două: localhost și adresele IP private sunt excluse. Serverul trebuie să fie accesibil din infrastructura xAI, pe un domeniu public, cu un certificat SSL valid. Aceasta ridică o întrebare concretă în timpul dezvoltării, deoarece serverul MCP pe care îl scrieți rulează pe mașina dumneavoastră. Soluția uzuală este utilizarea unui tunel—de exemplu ngrok sau Cloudflare Tunnel—care expune instanța locală în spatele unui URL HTTPS public pe durata testelor.

server_label: Identitatea serverului în conversație

server_label este un identificator scurt pe care Grok îl folosește pentru a adăuga un prefix apelurilor de instrumente provenite de la acest server. Rolul său este dublu: să facă urmele (traces) lizibile și să elimine orice ambiguitate atunci când coexistă mai multe servere.

Documentația xAI afirmă că eticheta adaugă un prefix apelurilor de instrumente de la acest server, fără a specifica formatul exact al prefixului. În acest curs, notăm un instrument search_docs de la serverul deepwiki ca deepwiki__search_docs, pentru lizibilitate: verificați formatul real în răspunsurile API înainte de a construi logică pe baza lui.

mcp(
    server_url="https://mcp.deepwiki.com/mcp",
    server_label="deepwiki"
)
# Apelurile de instrumente de la acest server vor avea prefixul "deepwiki"

Trei criterii ghidează alegerea unei etichete bune. Trebuie să fie scurtă, deoarece se adaugă la numele fiecărui apel, iar o etichetă verbose umflă inutil jurnalele. Trebuie să fie descriptivă, astfel încât sursa unui apel să fie lizibilă dintr-o privire, fără a consulta configurația. Trebuie să fie unică în configurația dumneavoastră, altfel nu veți putea face distincția între două servere. Exemplele de mai jos îndeplinesc aceste trei cerințe:

server_label="deepwiki"     # Documentație GitHub
server_label="crm"          # Sistem de gestionare a clienților
server_label="jira"         # Urmărirea tichetelor
server_label="search"       # Motor de căutare intern

Acest aspect devine mult mai tangibil imediat ce conectați mai multe servere la aceeași sesiune. Să presupunem că documentația internă și DeepWiki expun ambele un instrument numit search. Fără etichete distincte, numele instrumentelor intră în coliziune, iar Grok nu are nicio modalitate de a ști pe care să îl țintească. Cu etichete, cele două instrumente primesc prefixe diferite—notate aici ca deepwiki__search și internal-docs__search—iar confuzia dispare. Veți reveni asupra acestui punct în lecția dedicată multi-server.

Configurație minimă în ambele SDK-uri

Împreună, acești doi parametri sunt suficienți pentru a face funcțional un server MCP public. Cu SDK-ul nativ xAI:

from xai_sdk.tools import mcp

tools = [
    mcp(
        server_url="https://mcp.deepwiki.com/mcp",
        server_label="deepwiki"
    )
]

Și echivalentul exact cu API-ul Responses în format OpenAI:

tools = [{
    "type": "mcp",
    "server_url": "https://mcp.deepwiki.com/mcp",
    "server_label": "deepwiki",
}]

Puncte cheie

  • server_url și server_label sunt singurii doi parametri obligatorii
  • URL-ul trebuie să fie HTTPS cu un certificat SSL valid, fără localhost
  • Eticheta adaugă un prefix tuturor apelurilor de instrumente de la acest server (formatul exact nu este documentat; acest curs îl notează ca label__tool)
  • Alegeți etichete care sunt scurte, descriptive și unice per server
  • Eticheta este esențială pentru multi-server pentru a evita conflictele de nume