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

Configurație completă a serverului MCP

Lecția 7 din 12 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Integrarea tuturor elementelor
  2. Cel mai simplu caz
  3. Un server intern read-only
  4. O configurație cuprinzătoare
  5. Verificare înainte de lansare
  6. Puncte cheie

Integrarea tuturor elementelor

Ați întâlnit fiecare parametru izolat. Această lecție le reunește în configurații complete, exact așa cum le veți scrie în practică, prezentând de fiecare dată echivalentul în cele două SDK-uri principale. Scopul nu este introducerea unor concepte noi, ci oferirea unor modele pe care le puteți adapta direct.

Iată o prezentare generală a celor șase parametri, cu statutul lor obligatoriu sau opțional.

ParametruObligatoriuRol
server_urlDaURL HTTPS al serverului MCP
server_labelDaPrefix pentru apelarea instrumentelor
server_descriptionNuGhidează Grok în selectarea serverului
allowed_tool_namesNuRestricționează instrumentele accesibile
authorizationNuToken de autentificare
headersNuAntete HTTP suplimentare

Cel mai simplu caz

Doi parametri sunt suficienți atunci când serverul este public și nu necesită autentificare.

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

# Responses API (OpenAI)
tools = [{
    "type": "mcp",
    "server_url": "https://mcp.deepwiki.com/mcp",
    "server_label": "deepwiki"
}]

Acesta este exact codul pe care îl veți scrie pentru DeepWiki. Grok are astfel acces la toate instrumentele serverului, ceea ce rămâne acceptabil aici, deoarece este un serviciu public de tip read-only. De îndată ce serverul aparține organizației dumneavoastră, această configurație devine insuficientă.

Un server intern read-only

Să trecem la nivelul următor: un CRM enterprise pe care agentul trebuie să îl poată interoga, dar niciodată modifica. Se adaugă trei parametri, fiecare pentru un motiv distinct – descrierea ghidează modelul, token-ul dovedește identitatea, iar lista de允许 (allowlist) interzice scrierea.

# xAI SDK
tools = [
    mcp(
        server_url="https://api.monentreprise.com/mcp",
        server_label="crm",
        server_description="CRM intern. Doar căutare contacte și companii.",
        authorization=f"Bearer {os.getenv('CRM_TOKEN')}",
        allowed_tool_names=["search_contacts", "get_contact", "list_companies"]
    )
]

# Responses API (OpenAI)
tools = [{
    "type": "mcp",
    "server_url": "https://api.monentreprise.com/mcp",
    "server_label": "crm",
    "server_description": "CRM intern. Doar căutare contacte și companii.",
    "authorization": f"Bearer {os.getenv('CRM_TOKEN')}",
    "allowed_tool_names": ["search_contacts", "get_contact", "list_companies"]
}]

Comparați cele două blocuri: conținutul este identic; doar wrapper-ul se schimbă. Funcția helper mcp() primește argumente numite; formatul OpenAI așteaptă un dicționar cu o cheie suplimentară "type". Aceasta este singura diferență de reținut atunci când traduceți o configurație de la un SDK la celălalt.

O configurație cuprinzătoare

Pasul final, cu toți cei șase parametri combinați într-un apel real către SDK-ul xAI.

import os
from xai_sdk import Client
from xai_sdk.tools import mcp

client = Client(api_key=os.getenv("XAI_API_KEY"))

chat = client.chat.create(
    model="grok-4.20-0309-reasoning",
    tools=[
        mcp(
            server_url="https://tools.monentreprise.com/v1/mcp",
            server_label="outils-internes",
            server_description="Platformă de instrumente interne: gestionare documente, tichete de suport, bază de cunoștințe. Acces read-only.",
            authorization=f"Bearer {os.getenv('TOOLS_MCP_TOKEN')}",
            headers={
                "X-Organization-Id": os.getenv("ORG_ID"),
                "X-Environment": "production",
                "X-Request-Source": "grok-agent"
            },
            allowed_tool_names=[
                "search_documents",
                "get_document",
                "search_tickets",
                "get_ticket",
                "search_knowledge_base"
            ]
        )
    ],
    include=["verbose_streaming"],
)

Observați coerența internă a acestui exemplu. Descrierea anunță un acces read-only, iar cele cinci instrumente permise sunt toate operațiuni de interogare – nicio contradicție între ceea ce modelul crede că poate face și ceea ce permite configurația. Antetul X-Environment setat la production împiedică un agent de testare să scrie în datele live, iar X-Request-Source va face urmele (traces) de pe server acționabile, dacă va trebui să urmăriți originea unei cereri neașteptate.

Verificare înainte de lansare

Șase puncte necesită o revizuire înainte de orice implementare în producție, iar fiecare corespunde unei capcane întâlnite anterior în acest curs. URL-ul trebuie să fie HTTPS cu un certificat valid; altfel, nimic nu va funcționa. Eticheta (label) trebuie să rămână scurtă, descriptivă și unică în cadrul configurației. Descrierea trebuie să corespundă instrumentelor expuse efectiv; altfel, modelul va încerca apeluri destinate eșecului. Instrumentele permise trebuie reduse la strictul necesar. Token-ul trebuie să provină dintr-o variabilă de mediu, nu din codul sursă. Iar antetele suplimentare trebuie să fie exact cele așteptate de serverul dumneavoastră, cu majuscule/minuscule corecte – o eroare de scriere la X-Organization-Id produce un eșec silențios, deosebit de dureros de diagnosticat.

Puncte cheie

  • Configurația minimă necesită doar server_url și server_label
  • Adăugați server_description pentru a ghida Grok, în special în configurările cu mai multe servere
  • Restricționați accesul cu allowed_tool_names pentru securitate și performanță
  • Utilizați authorization și headers pentru autentificare
  • Ambele SDK-uri (xAI nativ și OpenAI Responses) acceptă aceiași parametri, cu sintaxe diferite