Jamdesk Documentation logo

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:

FerramentaFinalidade
searchDocsPesquisa a documentação por palavra-chave e retorna resultados classificados
getPageRecupera 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çãoEndpoint
Domínio personalizado em docs.acme.comhttps://docs.acme.com/_mcp
Sem domínio personalizadohttps://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/_mcp

Substitua 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âmetroTipoObrigatórioDescrição
querystringSimTermos de pesquisa (por exemplo, "authentication", "getting started")
limitnumberNãoNúmero máximo de resultados (padrão: 10, máximo: 50)
typestringNãoFiltra 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âmetroTipoObrigatórioDescrição
urlstringUm entre url e slugO url de um resultado de searchDocs (por exemplo, /docs/api/authentication). URLs completos de páginas e links .md também funcionam.
slugstringUm entre url e slugO 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:

StatuserrorSignificado
401auth_requiredNenhuma chave foi enviada.
401invalid_api_keyA chave não é válida para este site.
503auth_unavailableNã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/_mcp

Você 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.

Próximos passos

Escrever com IA

Dicas para usar ferramentas de IA na escrita da documentação

llms.txt

Índice de páginas gerado automaticamente para ferramentas de IA