Servidor MCP

Todos los sitios de Jamdesk incluyen un servidor MCP (Model Context Protocol) integrado. Mientras que llms.txt ofrece a las herramientas de IA una instantánea estática de tu documentación, MCP les permite buscar y consultar de forma interactiva, algo útil cuando los agentes de IA necesitan encontrar respuestas concretas en lugar de leerlo todo.

¿Qué es MCP?

El Model Context Protocol es un estándar abierto que permite a las herramientas de IA acceder a fuentes de datos externas. Tu documentación de Jamdesk expone dos herramientas a través de MCP:

Tu URL de endpoint

Tu endpoint de MCP es la URL de tu documentación con /_mcp añadido. Si tienes un dominio personalizado activo, úsalo:

Configuración rápida

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

Herramientas disponibles

searchDocs

Busca en tu documentación y obtén resultados clasificados.

Parámetros:

Solicitud de ejemplo:

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

Respuesta de ejemplo:

{
  "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 página de documentación como Markdown. Las tablas, las listas y los bloques de código llegan intactos, en lugar de extractos cortos. Pasa la url que devolvió searchDocs en url, o la ruta de la página en slug. Las páginas de más de 80 000 caracteres se cortan en esa longitud, con un enlace a la URL .md de la página para el resto.

Parámetros:

Envía uno de los dos. Si envías ambos, se usa slug.

Solicitud de ejemplo:

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

Respuesta de ejemplo:

{
  "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\"}"
    }]
  }
}

Probar el endpoint

Puedes probar tu endpoint de MCP directamente 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"}}}'

Sitios protegidos con inicio de sesión

Si tu sitio usa autenticación por contraseña o JWT, el servidor MCP necesita una clave de API del proyecto. Crea una en Project Settings > API Keys y envíala como encabezado:

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

Con la clave, un cliente MCP puede buscar y leer las páginas con búsqueda habilitada del sitio, el mismo conjunto que cubre la búsqueda del sitio. Las páginas restringidas por grupo nunca están disponibles a través de MCP, con o sin clave. Las páginas ocultas y las páginas con search: false se omiten a menos que las hayas hecho buscables. Trata la clave como una contraseña y revócala en el dashboard si se filtra.

La misma clave también abre las URL de páginas .md, llms.txt y llms-full.txt. Consulta llms.txt y Fuente Markdown. La clave nunca abre las páginas HTML ni el chat de IA, que siguen requiriendo un inicio de sesión.

Sin clave, el servidor responde con 401 y un cuerpo JSON que explica cómo añadir una. Una clave de otro proyecto se rechaza. Los códigos de error son:

Cómo funciona

El endpoint de MCP utiliza un índice de búsqueda que se genera junto con tu documentación:

• Clasificación BM25 - Clasifica los resultados por relevancia
• Coincidencia difusa - Gestiona errores tipográficos (tolerancia de 1 carácter)
• Ponderación de campos - Los títulos y los encabezados de sección tienen más peso que el contenido del cuerpo
• Filtrado por tipo - Filtra los resultados por tipo de contenido (API, guía, etc.)

El índice se reconstruye con cada despliegue.

Límites de frecuencia

Las solicitudes sin clave de API están limitadas a unas 60 por minuto por dirección IP. Es suficiente para el uso normal de un asistente de IA.

En un sitio protegido con inicio de sesión, las solicitudes autenticadas con una clave comparten un límite de 120 por minuto por clave. Cuentan las llamadas MCP, las solicitudes de páginas .md y las de llms.txt o llms-full.txt. La API de búsqueda mantiene su propio límite de 60 por minuto por clave.

Al superar un límite, la respuesta es un 429 con Retry-After: 60.

Solución de problemas

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

¿Qué sigue?