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

server_url ja server_label

Oppitunti 4 / 12 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Kaksi parametria, joita et voi jättää pois
  2. server_url: Tarkka päätepisteen osoite
  3. server_label: Palvelimen identiteetti keskustelussa
  4. Minimikonfiguraatio molemmissa SDK:issa
  5. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI:n Remote MCP Tools -sivun perusteella: server_label lisää etuliitteen työpyyntöihin, mutta dokumentaatio ei määrittele tarkkaa etuliitteen muotoa; tässä kurssissa käytetty label__tool-merkintä on lukukäytäntö – varmista todellinen muoto API-vastauksistasi. Lähde: Remote MCP Tools.

Kaksi parametria, joita et voi jättää pois

Jokainen Grokin ja etä-MCP-palvelimen välinen yhteys perustuu kahteen parametriin: server_url ja server_label. Ne ovat ehdottomia – ilman niitä API hylkää pyynnön ennen kuin yrittää mitään. Kaikki muut myöhemmin kohtaamasi parametrit vain hienosäätävät tätä perustaa; ne eivät koskaan korvaa sitä.

server_url
Missä palvelin sijaitsee
server_label
Miten palvelin tunnistetaan

server_url: Tarkka päätepisteen osoite

Parametri server_url sisältää täydellisen URL-osoitteen MCP-palvelimelle, johon Grokin tulee muodostaa yhteys, ja tämä URL noudattaa tiukkoja sääntöjä.

Ensimmäinen sääntö on HTTPS. URL-osoitteen on alettava merkkijonolla https://, ja xAI hylkää kaikki salaamattomat HTTP-yhteydet. Syy on yksinkertainen: Grokin ja MCP-palvelimen väliset vaihdot sisältävät käyttäjiesi pyyntöjä, työkalujen tuloksia ja joskus jopa itsessään tunnistetun tokenin. Näiden tietojen päästäminen liikkumaan selväkielisenä olisi puolustamatonta.

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

# API hylkää tämän
mcp(server_url="http://mcp.deepwiki.com/mcp")

Toinen sääntö koskee polun tarkkuutta. URL-osoitteen on osoitettava nimenomaan MCP-päätepisteeseen, ei verkkotunnuksen juureen. Lähes kaikki palvelimet paljastavat päätepisteensä omalla polullaan, ja käytäntö vaihtelee palvelimesta toiseen. Tässä on kolme validia muotoa, joita tulet kohtaamaan:

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

Kolmas sääntö seuraa kahdesta edellisestä: localhost ja yksityiset IP-osoitteet on suljettu pois. Palvelimen on oltava tavoitettavissa xAI:n infrastruktuurista julkisessa verkkotunnuksessa, ja sillä on oltava voimassa oleva SSL-varmenne. Tämä herättää konkreettisen kysymyksen kehitysvaiheessa, sillä kirjoittamasi MCP-palvelin pyörii omalla koneellasi. Tavallinen ratkaisu on käyttää tunnelia – esimerkiksi ngrokia tai Cloudflare Tunnelia – joka paljastaa paikallisen instanssisi julkisen HTTPS-URL-osoitteen taakse testiesi ajaksi.

server_label: Palvelimen identiteetti keskustelussa

server_label on lyhyt tunniste, jota Grok käyttää lisäämään etuliitteen tämän palvelimen työpyyntöihin. Sen rooli on kaksinkertainen: tehdä jäljistä luettavia ja poistaa epäselvyydet, kun useita palvelimia on käytössä samanaikaisesti.

xAI:n dokumentaatio toteaa, että tunniste lisää etuliitteen palvelimen työpyyntöihin, määrittelemättä kuitenkaan tarkkaa etuliitteen muotoa. Tässä kurssissa merkitsemme deepwiki-palvelimen search_docs-työkalun muodossa deepwiki__search_docs luettavuuden vuoksi: varmista todellinen muoto API-vastauksista ennen logiikan rakentamista sen varaan.

mcp(
    server_url="https://mcp.deepwiki.com/mcp",
    server_label="deepwiki"
)
# Tämän palvelimen työpyynnöt saavat etuliitteeksi "deepwiki"

Hyvän tunnisteen valintaa ohjaavat kolme kriteeriä. Sen on oltava lyhyt, sillä se lisätään jokaisen pyynnön nimeen, ja puhelias tunniste turhaan paisuttaa loktejasi. Sen on oltava kuvaava, jotta pyynnön lähde on luettavissa silmäyksellä ilman konfiguraation tarkistamista. Sen on oltava yksilöllinen konfiguraatiossasi, muuten et pysty erottamaan kahta palvelinta toisistaan. Alla olevat esimerkit täyttävät nämä kolme vaatimusta:

server_label="deepwiki"     # GitHub-dokumentaatio
server_label="crm"          # Asiakkuudenhallintajärjestelmä
server_label="jira"         | Lippujen seuranta
server_label="search"       # Sisäinen hakukone

Tämä muuttuu paljon konkreettisemmaksi heti, kun yhdistät useita palvelimia samaan istuntoon. Oletetaan, että sekä sisäinen dokumentaatiosi että DeepWiki paljastavat työkalun nimeltä search. Ilman erillisiä tunnisteita työkalujen nimet törmäävät toisiinsa, eikä Grokilla ole keinoa tietää, kumpaan se kohdistaa pyynnön. Tunnisteiden avulla kahdelle työkalulle annetaan eri etuliitteet – tässä merkittynä deepwiki__search ja internal-docs__search – ja sekaannus katoaa. Palaat tähän kohtaan monipalvelimia käsittelevässä oppitunnissa.

Minimikonfiguraatio molemmissa SDK:issa

Nämä kaksi parametria riittävät yhdessä saamaan julkisen MCP-palvelimen toimimaan. Natiivilla xAI SDK:lla:

from xai_sdk.tools import mcp

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

Ja täysin vastaava toteutus Responses API:lla OpenAI-muodossa:

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

Keskeiset asiat

  • server_url ja server_label ovat ainoat kaksi pakollista parametria
  • URL-osoitteen on oltava HTTPS ja sillä on oltava voimassa oleva SSL-varmenne; localhost ei kelpaa
  • Tunniste lisää etuliitteen kaikille tämän palvelimen työpyynnöille (tarkka muoto ei ole dokumentoitu; tämä kurssi merkitsee sen muodossa label__tool)
  • Valitse tunnisteet, jotka ovat lyhyitä, kuvaavia ja yksilöllisiä palvelinta kohden
  • Tunniste on välttämätön monipalvelinympäristöissä nimiristiriitojen välttämiseksi