MCP

Nordvec toteuttaa Model Context Protocol-protokollan (MCP), joten agentti tai avustaja, joka osaa MCP:tä, voi löytää työtilasi toiminnot työkaluina ja kutsua niitä natiivisti ilman OpenAPI-dokumenttia pääteltäväksi.

Palvelimia on kaksi:

Molemmat toimivat EU:ssa, samalla infrastruktuurilla kuin muukin API.

Asiakkaan yhdistäminen

Ohjaa MCP-asiakas tietopohjapalvelimeen API-avaimesi kanssa kantajamerkkinä. Useimmat asiakkaat ottavat vastaan määrityslohkon, joka näyttää tältä:

{
  "mcpServers": {
    "nordvec": {
      "url": "https://nordvec.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer nv_your_api_key"
      }
    }
  }
}

Palvelin on tilaton Streamable HTTP: jokainen viesti on yksi POST, joka sisältää yhden JSON-RPC-pyynnön, ja vastaus tulee takaisin vastauksen rungossa. Istuntoja ei säilytetä eikä palvelin aloita virtaa, joten GET-metodi URL-osoitteessa vastaa 405-koodilla, ja POST, jonka Content-Type ei ole application/json, vastaa 415-koodilla ennen kuin runkoa luetaan.

Palvelin tunnistautuu staattisella kantajamerkillä eikä tarjoa OAuth-hakua. Asiakas, jonka avulla voit asettaa pyyntöotsakkeita (koodaavat agentit, IDE-laajennukset, MCP Inspector otsaketilassa), yhdistää kuten yllä on esitetty. Isännöity asiakas, joka tukee vain OAuth-tunnistautumisvirtausta, ei voi vielä yhdistää.

Asiakas, joka lähettää MCP-Protocol-Version-otsakkeen, saa vastauksen kyseisessä versiossa, jos palvelin tukee sitä (2025-06-18 ja 2024-11-05), ja hylätään 400-koodilla, jos ei, joten versioiden yhteensopimattomuus raportoidaan ensimmäisessä viestissä eikä virheellisenä vastauksena myöhemmin.

Työkalut

Työkalut johdetaan REST API:sta, yksi työkalu kutakin API-avaimen sallimaa toimintoa kohti. Työkalun nimi on toiminnon SDK-polku snake case -muodossa, ja toistuva segmentti pudotetaan pois:

tools/list on virallinen katalogi: se näyttää avaimelle vain ne työkalut, joiden käyttöoikeudet se sallii, ja jokaisen työkalun kuvaus nimeää vaaditun käyttöoikeuden. Työkalun inputSchema on toiminnon pyyntökaavio ja, jos toiminto palauttaa objektin, sen outputSchema on vastauskaavio ja tulokset sisältävät structuredContent-kentän JSON-tekstin rinnalla.

Työkalun kutsu, jota avaimen käyttöoikeudet eivät salli, vastaa työkaluvirheellä, jossa mainitaan FORBIDDEN, sama hylkäys kuin REST-reitillä, joten asiakas, jolla on välimuistissa lista toisella avaimella, saa selville syyn eikä vain tiedon työkalun puuttumisesta.

Rajoitukset ja virheet

Työkalukutsu käyttää samaa rajoituslaskuria kuin vastaava REST-toiminto, ja kaikki muut viestit käyttävät päätepisteen omaa laskuria. X-RateLimit-*-otsakkeet, 429-vastaus Retry-After-kentällään ja virhekuori ovat samat kuin REST API:ssa, joten asiakas, joka jo käsittelee niitä RESTissä, käsittelee ne tässäkin.

Epäonnistunut työkalukutsu palauttaa MCP-työkalutuloksen, jossa on isError: true-kenttä ja jonka teksti on REST-virheen runko (code, message, data). Validointivirheet sisältävät saman fieldErrors-muodon kuin REST API. JSON-RPC-virhe on varattu protokollalle itselleen: jäsennysvirhe, tuntematon metodi tai palvelinvika.

Pyyntöjen rungot on rajattu 1 Mt:n kokoon, sama raja kuin REST-reiteillä.

Ensimmäinen vaihto

# Discover the tools your key can call
curl https://nordvec.com/api/v1/mcp \
  -H "Authorization: Bearer $NORDVEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Search the workspace
curl https://nordvec.com/api/v1/mcp \
  -H "Authorization: Bearer $NORDVEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"documents_search","arguments":{"query":"data retention policy"}}}'

Dokumentaatiopalvelin

Dokumentaatiopalvelin osoitteessa /api/mcp ei tarvitse avainta. Se tarjoaa list_guides-, get_guide-, search_docs- ja list_connectors-toiminnot, joten agentti, joka rakentaa integraatiota, voi lukea nämä oppaat suoraan. Se on rajoitettu IP-osoitteen mukaan kuten muutkin julkiset päätepisteet.