Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Konfigurazzjoni Sħiħa tas-Server MCP

Lezzjoni 7 / 12 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Ingħaqdu Flimkien
  2. L-Iżjed Każ Sempliċi
  3. Server Intern ta’ Qari Biss
  4. Konfigurazzjoni Komprensiva
  5. Iċċekkja Qabel ma Tiddispjega
  6. Punti Ewlenin

Ingħaqdu Flimkien

Iltaqt ma’ kull parametru waħdu. Din il-lezzjoni tiġborhom flimkien f’konfigurazzjonijiet sħaħ, eżattament kif se tiktbihom fil-prattika, u turi l-ekwivalenti fiż-żewġ SDKs ewlenin kull darba. L-għan mhuwiex li jintroduċi kunċetti ġodda iżda li jagħtik mudelli li tista’ tadatta direttament.

Hawn ħarsa ġenerali lejn is-sitt parametri, bl-istatus tagħhom jekk humiex meħtieġa jew fakultattivi.

ParametruMeħtieġRwol
server_urlIvaURL HTTPS tas-server MCP
server_labelIvaPrefiss għas-sejħa tal-għodda
server_descriptionLeJiggwida lil Grok fl-għażla tas-server
allowed_tool_namesLeJirrestrinġi l-għodod aċċessibbli
authorizationLeToken tal-awtentikazzjoni
headersLeIntestazzjonijiet HTTP addizzjonali

L-Iżjed Każ Sempliċi

Żewġ parametri biżżejjed meta s-server huwa pubbliku u ma jeħtiġx awtentikazzjoni.

# 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"
}]

Dan huwa eżattament dak li se tikteb għal DeepWiki. Grok imbagħad ikollu aċċess għall-għodod kollha tas-server, li jibqa’ aċċettabbli hawnhekk peress li huwa servizz pubbliku ta’ qari biss. Hekk kif is-server ikun tal-organizzazzjoni tiegħek, din il-konfigurazzjoni ssir insuffiċjenti.

Server Intern ta’ Qari Biss

Ejja nieħdu pass ‘il quddiem: CRM tal-intrapriża li l-aġent irid ikun jista’ jikkonsulta iżda qatt ma jimmodifika. Jiżdiedu tliet parametri, kull wieħed għal raġuni distinta—id-deskrizzjoni tiggwida l-mudell, it-token jipprova l-identità, u l-lista ta’ permessi tipprojbixxi l-kitba.

# xAI SDK
tools = [
    mcp(
        server_url="https://api.monentreprise.com/mcp",
        server_label="crm",
        server_description="Internal CRM. Contact and company lookup only.",
        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": "Internal CRM. Contact and company lookup only.",
    "authorization": f"Bearer {os.getenv('CRM_TOKEN')}",
    "allowed_tool_names": ["search_contacts", "get_contact", "list_companies"]
}]

Qabbel iż-żewġ blokok: il-kontenut huwa identiku; jinbidel biss il-”wrapper”. L-għajnuna mcp() tieħu argumenti msemmija; il-format ta’ OpenAI jistenna dizzjunarju b’key addizzjonali "type". Din hija l-unika differenza li trid tiftakar meta tittraduċi konfigurazzjoni minn SDK għall-ieħor.

Konfigurazzjoni Komprensiva

L-aħħar pass, b’sitt parametri kkombinati f’sejħa reali għall-xAI SDK.

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="Internal tools platform: document management, support tickets, knowledge base. Read-only access.",
            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"],
)

Innota l-konsistenza interna ta’ dan l-eżempju. Id-deskrizzjoni tħabbar aċċess ta’ qari biss, u l-ħames għodod permessi huma kollha operazzjonijiet ta’ mistoqsija—l-ebda kontradizzjoni bejn dak li l-mudell jemmen li jista’ jagħmel u dak li l-konfigurazzjoni tippermetti. L-intestazzjoni X-Environment imsettja għal production tipprevjeni aġent ta’ test milli jikteb fuq data ħajja, u X-Request-Source se jgħamel it-traċċi tas-server tiegħek azzjonabbli jekk ikollok bżonn issib minn fejn oriġinat talba mhux mistennija.

Iċċekkja Qabel ma Tiddispjega

Sitt punti jiġġustifikaw reviżjoni qabel kwalunkwe dispjegament tal-produzzjoni, u kull wieħed jikkorrispondi għal trap li ntlaqa’ qabel f’dan il-kors. L-URL irid ikun HTTPS b’ċertifikat validu, inkella xejn ma jgħaddi. It-tikketta (label) trid tibqa’ qasira, deskrittiva, u unika fil-konfigurazzjoni. Id-deskrizzjoni trid taqbel mal-għodod esposti attwalment, inkella l-mudell se jipprova sejħiet destinati li jfallu. L-għodod permessi jridu jitnaqqsu għall-minimu strett. It-token irid jiġi minn varjabbli tal-ambjent, mhux mill-kodiċi sors. U l-intestazzjonijiet addizzjonali jridu jkunu eżattament dak li jistenna s-server tiegħek, bil-kaxxa (casing) korretta—żball fil-kaxxa fuq X-Organization-Id jipproduċi falliment sieket li huwa partikolarment doloruż biex tiddijanostika.

Punti Ewlenin

  • Il-konfigurazzjoni minima teħtieġ biss server_url u server_label
  • Żid server_description biex tiggwida lil Grok, speċjalment f’installazzjonijiet b’ħafna servers
  • Irrestrinġi b’allowed_tool_names għas-sigurtà u l-prestazzjoni
  • Uża authorization u headers għall-awtentikazzjoni
  • Iż-żewġ SDKs (xAI nativ u OpenAI Responses) jaċċettaw l-istess parametri b’sintassi differenti