Server MCP

Ogni sito Jamdesk dispone di un server MCP (Model Context Protocol) integrato. llms.txt fornisce agli strumenti AI un'istantanea statica della tua documentazione. MCP permette loro di cercare e interrogare la documentazione per trovare risposte specifiche senza doverla leggere per intero.

Che cos’è MCP?

Model Context Protocol è uno standard aperto per collegare strumenti AI a fonti di dati esterne. La tua documentazione Jamdesk espone due strumenti MCP:

URL dell’endpoint

Il tuo endpoint MCP è l'URL della documentazione con /_mcp aggiunto. Se hai un dominio personalizzato attivo, usalo:

Configurazione rapida

claude mcp add --transport http my-docs https://docs.acme.com/_mcp

Strumenti disponibili

searchDocs

Cerca nella tua documentazione e ottieni risultati ordinati.

Parametri:

Esempio di richiesta:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "searchDocs",
    "arguments": {
      "query": "authentication",
      "limit": 5
    }
  }
}

Esempio di risposta:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"query\":\"authentication\",\"total\":1,\"results\":[{\"title\":\"Authentication\",\"description\":\"How to authenticate API requests\",\"url\":\"/docs/api/authentication\",\"type\":\"api\",\"score\":0.95}]}"
    }]
  }
}

getPage

Recupera una pagina della documentazione come Markdown. Tabelle, elenchi e blocchi di codice vengono restituiti integri, non come brevi estratti. Passa come url il valore restituito da searchDocs, oppure il percorso della pagina come slug. Le pagine più lunghe di 80.000 caratteri vengono troncate a quella lunghezza, con un rimando all'URL .md della pagina per il resto.

Parametri:

Invia uno solo. Se invii entrambi, viene usato slug.

Esempio di richiesta:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "getPage",
    "arguments": {
      "url": "/docs/api/authentication"
    }
  }
}

Esempio di risposta:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"title\":\"Authentication\",\"description\":\"How to authenticate\",\"content\":\"## Overview\\n\\nUse API keys to authenticate...\",\"url\":\"/docs/api/authentication\"}"
    }]
  }
}

Testare l’endpoint

Testa il tuo endpoint MCP con curl:

# List available tools
curl -X POST https://docs.acme.com/_mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Search for content
curl -X POST https://docs.acme.com/_mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"searchDocs","arguments":{"query":"getting started"}}}'

Siti protetti da login

Se il tuo sito usa l'autenticazione con password o JWT, il server MCP richiede una chiave API di progetto. Creala in Project Settings > API Keys e inviala come header:

claude mcp add --transport http my-docs https://docs.example.com/_mcp \
  --header "Authorization: Bearer jd_live_..."

Una chiave permette a un client MCP di cercare e leggere le pagine ricercabili del sito, lo stesso insieme coperto dalla ricerca del sito. Le pagine con accesso limitato a gruppi non sono mai disponibili tramite MCP, con o senza chiave. Le pagine nascoste e le pagine con search: false sono escluse, a meno che tu non le abbia rese ricercabili. Tratta la chiave come una password. Revocala dalla dashboard se viene divulgata.

La stessa chiave apre anche gli URL delle pagine .md, llms.txt e llms-full.txt. Vedi llms.txt e Markdown Source. La chiave non apre mai le pagine HTML né la chat AI. Per quelle serve comunque un login.

Senza chiave, il server risponde con 401 e un corpo JSON che spiega come aggiungerne una. Una chiave di un altro progetto viene rifiutata. I codici di errore sono:

Come funziona

L'endpoint MCP usa un indice di ricerca creato insieme alla documentazione:

• Ranking BM25: ordina i risultati per pertinenza
• Corrispondenza approssimata: tollera errori di battitura di 1 carattere
• Peso dei campi: titoli e intestazioni di sezione pesano più del contenuto del corpo
• Filtro per tipo: filtra i risultati per tipo di contenuto (API, guida, ecc.)

L'indice viene ricostruito a ogni deploy.

Limiti di frequenza

Le richieste senza chiave API sono limitate a circa 60 al minuto per indirizzo IP. È sufficiente per l'assistente AI di una persona. Tutti coloro che si trovano dietro un IP condiviso, come una rete d'ufficio o il tuo backend, attingono alla stessa quota.

Le richieste che inviano una chiave API di progetto saltano il limite per IP e ricevono invece 120 al minuto per chiave, su qualsiasi sito. Aggiungi la chiave alla configurazione del client MCP nello stesso modo previsto per i siti protetti da login.

Su un sito protetto da login, anche le richieste di pagine .md e di llms.txt o llms-full.txt fatte con una chiave contano nel limite di quella chiave. La Search API mantiene un proprio limite di 60 al minuto per chiave.

Le richieste oltre il limite ricevono una risposta 429 con Retry-After: 60.

Risoluzione dei problemi

curl https://docs.acme.com/_mcp

Prossimi passi