Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

MCP-palvelimen täydellinen määritys

Oppitunti 7 / 12 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Kaiken yhdistäminen
  2. Yksinkertaisin tapaus
  3. Vain luku -oikeuksilla varustettu sisäinen palvelin
  4. Kattava määritys
  5. Tarkista ennen käyttöönottoa
  6. Keskeiset asiat

Kaiken yhdistäminen

Olet kohdannut jokaisen parametrin erillään. Tässä oppitunnissa yhdistämme ne kokonaisvaltaisiksi määrityksiksi aivan kuten kirjoitat ne käytännössä, esittäen vastaavuuden kummassakin pääasiallisessa SDK:ssa joka kerta. Tavoitteena ei ole esitellä uusia käsitteitä, vaan antaa sinulle malleja, joita voit soveltaa suoraan.

Tässä on yleiskatsaus kuuteen parametriin sekä niiden pakollisuus tai vapaaehtoisuus.

ParametriPakollinenRooli
server_urlKylläMCP-palvelimen HTTPS-osoite
server_labelKylläTyökutsujen etuliite
server_descriptionEiOhjaa Grokia palvelimen valinnassa
allowed_tool_namesEiRajoittaa käytettävissä olevia työkaluja
authorizationEiTodennuspoletti
headersEiLisä-HTTP-otsikot

Yksinkertaisin tapaus

Kaksi parametria riittää, kun palvelin on julkinen eikä vaadi todennusta.

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

Näin kirjoitat määrityksen DeepWikille. Grokilla on tällöin pääsy kaikkiin palvelimen työkaluihin, mikä on tässä hyväksyttävää, koska kyseessä on julkinen vain luku -palvelu. Heti kun palvelin kuuluu organisaatiollesi, tämä määritys ei enää riitä.

Vain luku -oikeuksilla varustettu sisäinen palvelin

Siirrytään seuraavalle tasolle: yrityksen CRM-järjestelmä, jota agentin on pystyttävä kysymään, mutta ei koskaan muokkaamaan. Lisäämme kolme parametria, joista jokaisella on oma syynsä: kuvaus ohjaa mallia, poletti todentaa identiteetin ja sallittujen lista kieltää kirjoitustoiminnot.

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

Vertaa näitä kahta lohkoa: sisältö on identtinen, vain kääre muuttuu. mcp()-apufunktio ottaa vastaan nimettyjä argumentteja, kun taas OpenAI-muoto odottaa sanakirjaa, jossa on ylimääräinen "type"-avain. Tämä on ainoa ero, joka sinun tulee muistaa kääntäessäsi määritystä toisesta SDK:sta toiseen.

Kattava määritys

Viimeinen vaihe: kaikki kuusi parametria yhdistettynä todelliseen xAI SDK:n kutsuun.

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"],
)

Huomaa tämän esimerkin sisäinen johdonmukaisuus. Kuvaus ilmoittaa vain luku -oikeudet, ja viisi sallittua työkalua ovat kaikki kyselytoimintoja – ristiriitaa ei ole sen välillä, mitä malli luulee voivansa tehdä, ja sen välillä, mitä määritys sallii. X-Environment-otsikon asettaminen arvoon production estää testagenttia kirjoittamasta elävään dataan, ja X-Request-Source tekee palvelimesi jäljistä toimivia, jos joudut selvittämään, mistä odottamaton pyyntö on peräisin.

Tarkista ennen käyttöönottoa

Kuusi kohtaa vaatii tarkistuksen ennen tuotantokäyttöön ottoa, ja kukin niistä vastaa aiemmin tällä kurssilla kohdattua sudenkuoppaa. URL-osoitteen on oltava HTTPS ja sillä on oltava voimassa oleva varmenne, muuten mikään ei läpäise. Etukkeen on pysyttävä lyhyenä, kuvaavana ja ainutlaatuisena määrityksen sisällä. Kuvauksen on vastattava todellisuudessa tarjolla olevia työkaluja, muuten malli yrittää tehdä kutsuja, jotka ovat tuomittuja epäonnistumaan. Sallitut työkalut on rajoitettava ehdottomaan minimiin. Poletin on tultava ympäristömuuttujasta, ei lähdekoodista. Lisäotsikoiden on oltava täsmälleen sitä, mitä palvelimesi odottaa, oikealla kirjainkoolla – X-Organization-Id:n kirjainkokovirhe aiheuttaa hiljaisen epäonnistumisen, jota on erityisen tuskallista diagnosoida.

Keskeiset asiat

  • Minimimääritys vaatii vain server_url:n ja server_label:n
  • Lisää server_description ohjataksesi Grokia, erityisesti usean palvelimen ympäristöissä
  • Rajoita käyttöä allowed_tool_names:lla turvallisuuden ja suorituskyvyn vuoksi
  • Käytä authorization:ia ja headers:ia todennukseen
  • Molemmat SDK:t (natiivi xAI ja OpenAI Responses) hyväksyvät samat parametrit eri syntaksilla