Servidor MCP
Todos os sites Jamdesk incluem um servidor MCP integrado para que assistentes de IA, como Claude e Cursor, pesquisem e leiam sua documentação.
Todos os sites Jamdesk têm um servidor MCP (Model Context Protocol) integrado. llms.txt fornece às ferramentas de IA uma captura estática da sua documentação. O MCP permite que elas pesquisem e consultem sua documentação para encontrar respostas específicas sem precisar ler tudo.
O que é MCP?
O Model Context Protocol é um padrão aberto para conectar ferramentas de IA a fontes de dados externas. Sua documentação Jamdesk expõe duas ferramentas MCP:
| Ferramenta | Finalidade |
|---|---|
searchDocs | Pesquisa a documentação por palavra-chave e retorna resultados classificados |
getPage | Recupera uma página como Markdown completo |
URL do endpoint
O endpoint MCP é a URL da sua documentação com /_mcp acrescentado. Se você tiver um domínio personalizado ativo, use-o:
| Configuração | Endpoint |
|---|---|
Domínio personalizado em docs.acme.com | https://docs.acme.com/_mcp |
| Sem domínio personalizado | https://my-project.jamdesk.app/_mcp |
Use o endpoint do domínio personalizado quando ele estiver conectado. Assim, sua marca aparece em todos os URLs vistos pelas ferramentas de IA. Ele também continuará funcionando se você ocultar seu subdomínio .jamdesk.app mais tarde com a opção Somente domínio personalizado.
Configuração rápida
Adicione sua documentação como servidor MCP:
claude mcp add --transport http my-docs https://docs.acme.com/_mcpSubstitua docs.acme.com pelo domínio da sua documentação. Use my-project.jamdesk.app se ainda não tiver conectado um domínio personalizado.
Agora, Claude pode pesquisar e ler sua documentação quando você fizer perguntas sobre seu projeto.
Ferramentas disponíveis
searchDocs
Pesquise sua documentação e obtenha resultados classificados.
Parâmetros:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
query | string | Sim | Termos de pesquisa (por exemplo, "authentication", "getting started") |
limit | number | Não | Número máximo de resultados (padrão: 10, máximo: 50) |
type | string | Não | Filtra por tipo de conteúdo: all, api, guide, quickstart, help, component |
Exemplo de solicitação:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "searchDocs",
"arguments": {
"query": "authentication",
"limit": 5
}
}
}
Exemplo de resposta:
{
"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
Recupere uma página da documentação como Markdown. Tabelas, listas e blocos de código são retornados completos, não como trechos curtos. Passe o url retornado por searchDocs como url ou o caminho da página como slug. Páginas com mais de 80,000 caracteres são cortadas nesse limite, com uma indicação do URL .md da página para acessar o restante.
Parâmetros:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | string | Um entre url e slug | O url de um resultado de searchDocs (por exemplo, /docs/api/authentication). URLs completos de páginas e links .md também funcionam. |
slug | string | Um entre url e slug | O caminho da página sem o prefixo /docs (por exemplo, api/authentication) |
Envie um dos dois. Se enviar ambos, slug será usado.
Exemplo de solicitação:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "getPage",
"arguments": {
"url": "/docs/api/authentication"
}
}
}
Exemplo de resposta:
{
"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\"}"
}]
}
}
Testar o endpoint
Teste seu endpoint MCP com 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"}}}'
Sites protegidos por login
Se seu site usar autenticação por senha ou JWT, o servidor MCP precisará de uma chave de API do projeto. Crie uma em Project Settings > API Keys e envie-a em um cabeçalho:
claude mcp add --transport http my-docs https://docs.example.com/_mcp \
--header "Authorization: Bearer jd_live_..."
A chave permite que um cliente MCP pesquise e leia as páginas pesquisáveis do site, o mesmo conjunto coberto pela pesquisa do site. Páginas restritas a grupos nunca ficam disponíveis pelo MCP, com ou sem uma chave. Páginas ocultas e páginas com search: false são excluídas, a menos que você as torne pesquisáveis. Trate a chave como uma senha. Revogue-a no dashboard se ela vazar.
A mesma chave também permite acessar URLs de páginas .md, llms.txt e llms-full.txt. Consulte llms.txt e Origem Markdown. A chave nunca permite acessar páginas HTML nem o chat de IA. Para isso, ainda é necessário fazer login.
Sem uma chave, o servidor responde com 401 e um corpo JSON que explica como adicionar uma. Uma chave de outro projeto é rejeitada. Os códigos de erro são:
| Status | error | Significado |
|---|---|---|
| 401 | auth_required | Nenhuma chave foi enviada. |
| 401 | invalid_api_key | A chave não é válida para este site. |
| 503 | auth_unavailable | Não foi possível verificar a chave. Tente novamente após o número de segundos indicado no cabeçalho Retry-After. |
Como funciona
O endpoint MCP usa um índice de pesquisa criado junto com sua documentação:
- Classificação BM25: classifica os resultados por relevância
- Correspondência aproximada: tolera erros de digitação de 1 caractere
- Peso dos campos: títulos e cabeçalhos de seção têm mais peso que o conteúdo do corpo
- Filtragem por tipo: filtra resultados por tipo de conteúdo (API, guia etc.)
O índice é reconstruído a cada publicação.
Limites de taxa
As solicitações sem uma chave de API são limitadas a cerca de 60 por minuto por endereço IP. Isso é suficiente para o assistente de IA de uma pessoa. Todos que compartilham um IP, como em uma rede de escritório ou no seu próprio backend, usam a mesma cota.
As solicitações que enviam uma chave de API do projeto ignoram o limite por IP e passam a ter um limite de 120 por minuto por chave, em qualquer site. Adicione a chave à configuração do cliente MCP da mesma forma que para sites protegidos por login.
Em um site protegido por login, as solicitações de páginas .md e as solicitações de llms.txt ou llms-full.txt feitas com uma chave também contam para o limite dessa chave. A API de pesquisa tem seu próprio limite de 60 por minuto por chave.
As solicitações que excedem um limite recebem uma resposta 429 com Retry-After: 60.
Solução de problemas
Verifique se o URL do endpoint está correto e acessível:
curl https://docs.acme.com/_mcpVocê deve ver uma resposta JSON com informações do servidor. Caso contrário, verifique se sua documentação foi compilada pelo menos uma vez.
O Jamdesk gera o índice de pesquisa durante o build. Inicie uma nova compilação no dashboard do Jamdesk para indexar o conteúdo novo.
Passe o url de um resultado de searchDocs para evitar incompatibilidades de slug. Se enviar um slug, ele deve corresponder exatamente ao caminho da página, sem a extensão .mdx. Uma página em api/authentication.mdx tem o slug api/authentication.
O site usa autenticação por senha ou JWT. A solicitação precisa de uma chave de API do projeto. Adicione o cabeçalho Authorization: Bearer com uma chave de Project Settings > API Keys. Consulte Sites protegidos por login.
