server_url și server_label
Pe această pagină
Actualizat la 3 noiembrie 2026 pe baza paginii Remote MCP Tools de la xAI:
server_labeladaugă un prefix apelurilor de instrumente, dar documentația nu specifică formatul exact al prefixului; notațialabel__toolfolosită î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: 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șiserver_labelsunt 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