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

Todentaminen ja otsikot

Oppitunti 6 / 12 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Todista kutsujan henkilöllisyys
  2. authorization-parametri
  3. headers ja extra_headers
  4. Täydellinen tuotantokonfiguraatio
  5. Keskeiset asiat

Todista kutsujan henkilöllisyys

DeepWiki ja muut julkiset MCP-palvelimet hyväksyvät kaikki kutsujat, mikä vastaa niiden käyttötarkoitusta. Kun kuitenkin otat omia työkalujasi käyttöön, tilanne muuttuu: ilman todentamista kuka tahansa, joka arvaa URL-osoitteen, voi kysellä CRM-järjestelmääsi tai laukaista prosessejasi. xAI tarjoaa kaksi parametria tämän ratkaisemiseksi: authorization pääsytunnisteelle sekä headers tai extra_headers kaikelle muulle.

authorization-parametri

Se lähettää todennustunnisteen MCP-palvelimelle. Tarkemmin sanottuna antamasi merkkijono sijoitetaan sellaisenaan jokaisen kyseiselle palvelimelle lähetetyn pyynnön HTTP-otsikkoon Authorization.

mcp(
    server_url="https://api.example.com/mcp",
    server_label="internal",
    authorization="Bearer sk-your-token-here"
)

Odotettu muoto riippuu täysin kohdepalvelimesta, sillä authorization hyväksyy minkä tahansa merkkijonon: MCP-palvelin validoi sen, ei xAI. Kolme muotoa kattaa lähes kaikki kohtaamasi tapaukset.

  • Bearer-tunniste: "Bearer sk-xxxx" – yleisin, käytössä useimmissa REST-APIeissa
  • API-avain: "ApiKey your-key" – jotkin palvelut käyttävät mukautettua etuliitettä
  • Basic auth: "Basic base64(user:password)" – base64-koodattu perustodennus

Koska tämä tunniste kulkee mukana jokaisessa pyynnössä, sen käsittely vaatii huolellisuutta. Älä koskaan kovakoodaa sitä lähdekoodiisi: versioituun tiedostoon kirjoitettu salaisuus päätyy ennemmin tai myöhemmin repositorioon, lokitiedostoon tai kuvakaappaukseen. Käytä aina ympäristömuuttujaa. Jos palvelin sen sallii, suosii rajattua tunnistetta, joka avaa vain tarvitsemasi työkalut – tämä on palvelinpuolen vastine allowed_tool_names-rajoitukselle. Suunnittele myös säännöllinen kierrätys, erityisesti tuotantoympäristössä, sillä ikuisesti voimassa oleva tunniste on tunniste, joka vuotaa ennemmin tai myöhemmin.

import os

mcp(
    server_url="https://api.example.com/mcp",
    server_label="internal",
    authorization=f"Bearer {os.getenv('MCP_SERVER_TOKEN')}"
)

headers ja extra_headers

Tunniste vastaa kysymykseen “kuka olet”. Monet palvelimet tarvitsevat lisävastauksia: mille organisaatiolle, missä ympäristössä, millä API-versiolla. Tämä tieto välitetään headers-parametrin kautta tai extra_headers-parametrilla SDK:sta riippuen.

mcp(
    server_url="https://api.example.com/mcp",
    server_label="internal",
    authorization="Bearer sk-token",
    headers={
        "X-Organization-Id": "org-123",
        "X-Project-Id": "proj-456"
    }
)

Yleisin tapaus ovat monivuokraaja-alustat (multi-tenant), joissa sama päätepiste palvelee useita asiakkaita ja luottaa otsikkoon reitittääkseen pyynnön oikeisiin tietoihin. Seuraavaksi tulee API-versiointi, jossa otsikko kuten "X-API-Version": "2024-01" lukitsee tietyn version ja suojaa sinut palvelimen muutoksilta. Jotkin järjestelmät odottavat myös seurantaan liittyvää metadataa – kuten istuntotunniste tai agenttitunniste – pyyntöjen alkuperän jäljittämiseksi, tai nopeusrajoitusotsikoita, jotka määrittävät sovellettavan laskutussuunnitelman.

Parametrin nimi vaihtelee käyttämäsi rajapinnan mukaan. Natiivi xAI SDK käyttää useimmissa tapauksissa headers-parametria; OpenAI-yhteensopiva Responses API saattaa vaatia extra_headers-parametrin välttääkseen yhteentörmäykset otsikoiden kanssa, joita tämä SDK hallinnoi automaattisesti itse. Toiminta on kuitenkin täsmälleen sama: otsikot lisätään jokaiseen MCP-palvelimelle lähetettävään pyyntöön. Jos pyyntösi lähtevät liikkeelle ilman otsikkojasi, tarkista ensin tämä parametrinimi ennen kuin etsit vikaa muualta.

Täydellinen tuotantokonfiguraatio

Näin nämä parametrit yhdistyvät edellisten oppituntien parametrien kanssa realistisessa sisäisen palvelimen tapauksessa.

from xai_sdk.tools import mcp
import os

tools = [
    mcp(
        server_url="https://api.monentreprise.com/mcp",
        server_label="internal",
        server_description="Internal tools: CRM, documentation, tickets",
        authorization=f"Bearer {os.getenv('INTERNAL_MCP_TOKEN')}",
        headers={
            "X-Organization-Id": os.getenv("ORG_ID"),
            "X-Environment": "production"
        },
        allowed_tool_names=["search_docs", "get_ticket", "search_contacts"]
    )
]

Tämä konfiguraatio muodostaa yhteyden sisäiseen MCP-palvelimeen HTTPS:n yli, todentaa käyttäjän ympäristömuuttujaan tallennetulla Bearer-tunnisteella, lähettää organisaatiotunnuksen otsikossa ja rajoittaa pääsyn kolmeen lukutoimintoon. Huomaa, että jokainen rivi lukitsee eri aspektin: salaus suojaa siirtoa, tunniste todistaa henkilöllisyyden, otsikko määrittelee tietojen laajuuden ja sallittujen listaus rajoittaa mahdollisia vahinkoja. Mikään näistä kerroksista ei korvaa toisiaan.

Keskeiset asiat

  • authorization lähettää pääsytunnisteen MCP-palvelimelle HTTP Authorization -otsikon kautta
  • Säilytä tunnisteet aina ympäristömuuttujissa, älä koskaan kovakoodattuina koodissa
  • headers / extra_headers lisäävät ylimääräisiä HTTP-otsikoita jokaiseen pyyntöön
  • Otsikoita käytetään monivuokraajatunnistukseen, API-versiointiin ja seurantaan
  • Yhdistä todentaminen ja työkalurajoitukset maksimaalisen turvallisuuden saavuttamiseksi