Segurança do servidor MCP

Esta página foi escrita para a pessoa que precisa aprovar a conexão de um agente de IA ao Docsbook. Ela declara o que o servidor MCP realmente faz hoje — como um cliente se autentica, a que cada escopo pode ter acesso, o que é registrado, o que sai da rede — e então identifica, em duas seções separadas, onde o Docsbook fica aquém da especificação do Model Context Protocol e quais artefatos de conformidade ainda não existem.

Nada aqui é aspiracional. Quando um controle está ausente, ele é listado como ausente.

O que você obtém#

Um cliente conectado mantém um token Bearer opaco, vinculado a uma conta do Docsbook, com um de dois escopos. O escopo é escolhido por uma pessoa em uma tela de consentimento — não solicitado pelo cliente. Toda ferramenta que atua em um projeto identifica esse projeto pelo proprietário, portanto um token que nomeia um id de workspace pertencente a outra pessoa não recebe nada de volta, nem mesmo esse workspace: esse é o limite entre os locatários, e ele se aplica a todas as ferramentas.

O limite entre leitura e gravação é mais estreito do que os nomes dos dois escopos sugerem, e a seção abaixo informa exatamente quais ferramentas o impõem e quais não. Leia-a antes de considerar um token somente leitura como uma medida de contenção.

Cada chamada contabilizada grava uma linha no próprio registro de chamadas do seu projeto: qual ferramenta foi usada, o que foi enviado, o que voltou, quanto tempo levou e quanto consumiu. Os argumentos e resultados são ocultados com base na chave antes de serem armazenados, portanto uma chave de API passada a uma ferramenta nunca é registrada.

O que você não obtém: expiração de token, tokens de atualização, limitação de taxa, funções dentro de uma conta ou um relatório de auditoria.

Como funciona a autenticação#

O fluxo de autorização#

O Docsbook é seu próprio servidor de autorização e seu próprio servidor de recursos. Ele emite tokens opacos para si mesmo; nunca aceita, encaminha ou reutiliza um token emitido por outra entidade.

Os metadados publicados declaram um modelo de cliente público — code_challenge_methods_supported: ["S256"], token_endpoint_auth_methods_supported: ["none"], grant_types_supported: ["authorization_code"]. Não há segredo do cliente nem concessão de credenciais do cliente.

O que é o token#

O token tem 48 bytes provenientes do CSPRNG da plataforma, representados como 96 caracteres hexadecimais. Ele não contém nenhuma informação: é uma chave de consulta para uma linha que contém a conta, o escopo e um carimbo de data e hora de revogação.

• Ele não expira. Nenhum expires_in é retornado e nenhum token de atualização é emitido. Um token é válido até ser revogado.
• A revogação é imediata. Revogar no painel registra o carimbo na linha, e todas as chamadas subsequentes falham na consulta — não há cache à frente dela.
• Ele é armazenado como emitido, não com hash. Trate um token do Docsbook MCP como trataria uma senha: se a máquina que o armazena for comprometida, revogue-o em vez de presumir que ele expirou com o tempo. (O que é criptografado em repouso está listado em o que deixa seu espaço de trabalho.)
• O último uso é registrado em cada chamada, portanto um token não utilizado fica visível na lista de tokens do painel.

O que cada escopo pode fazer#

O escopo é uma única string comparada exatamente. Qualquer coisa que não seja o escopo de escrita é tratada como somente leitura — um valor não reconhecido falha de forma segura.

A verificação de escopo não abrange atualmente todos os gravadores, e você deve planejar levando isso em conta. Ela é aplicada exatamente a quatro ferramentas: write_docs, create_issue, connect_source e configure_source. Essas ferramentas recusam um token somente leitura antes de fazer qualquer coisa.

Todas as outras ferramentas que alteram o estado — os gravadores de configurações update_* e set_*, update_access, o registro e a remoção de webhooks, a criação de metas e funis, o upload, a aprovação e a exclusão de traduções, create_workspace — são controladas apenas pela propriedade do projeto, não pelo escopo. Portanto, um token somente leitura pode alterar as configurações de um projeto, ativar um webhook ou excluir uma tradução em um projeto pertencente à conta. Ele ainda não pode publicar uma página, abrir uma issue, conectar uma fonte ou ativar um agente.

Trate o escopo somente leitura como "não pode publicar nem configurar novos recursos", e não como "não pode alterar nada". Se o isolamento for mais importante do que isso, use uma conta Docsbook separada que seja proprietária apenas do projeto que você está disposto a expor. Isso é um defeito, listado novamente em limitações, não uma decisão de design.

Uma ferramenta que aplica a verificação responde a um token somente leitura com um erro estruturado READ_ONLY_TOKEN que identifica a ferramenta e informa como autorizar novamente — não um 403 simples nem uma operação silenciosa. O mesmo formato se aplica quando o saldo de um projeto está vazio (INSUFFICIENT_BALANCE, identificando o projeto, o preço e o restante) e quando um plano não inclui o recurso (PLAN_RESTRICTION, identificando o nível).

O search anônimo é a única ferramenta sem token que lê um projeto, e é recusado de três formas: em um endpoint fixado a nenhum projeto, em um projeto cuja visibilidade seja privada (o que também abrange um plano expirado) e quando o projeto não tiver saldo restante para pagar pela incorporação da consulta. Ele não aceita um argumento de projeto, portanto só pode ler o site ao qual está fixado.

O que um token não pode alcançar#

Cada ferramenta resolve seu espaço de trabalho de destino a partir do workspace_id explícito, do argumento repo ou da própria fixação do endpoint — e, nos três casos, a consulta é filtrada pela conta do token. Um espaço de trabalho que a conta não possui não é encontrado, e a ferramenta responde "workspace not found". O resolvedor de faturamento aplica o mesmo filtro, portanto informar o id do projeto de outra pessoa também não pode consumir o saldo dela.

Vale mencionar mais dois limites, pois eles surpreendem algumas pessoas:

• write_docs faz commits no repositório hospedado pelo Docsbook usando as próprias credenciais do GitHub do Docsbook. Um site servido a partir de um repositório na sua própria conta do GitHub é recusado com NO_GITHUB_ACCESS, em vez de receber um commit. Portanto, um token MCP não é uma forma de fazer push para a sua organização do GitHub.
• Uma skill executada no modo de auditoria não pode fazer mutações. Enquanto uma skill no modo audit estiver ativa, uma lista explícita de gravadores, além de toda ferramenta cujo nome comece com update_, set_, register_webhook_, enable_ ou disable_, é recusada antes de ser executada. O executor que costumava definir esse modo para uma execução completa no lado do servidor foi removido em 12.09.2026, portanto a proteção agora resguarda uma rodada que tenha pré-carregado uma skill audit e nada mais.

O que é registrado#

Cada chamada MCP — com cobrança ou não, bem-sucedida ou não — grava uma linha no registro de chamadas do projeto, e o proprietário do projeto pode lê-la no painel Feeds.

Dois detalhes da redação são importantes para a revisão. Ela corresponde à chave, sem distinção entre maiúsculas e minúsculas e como uma substring, não ao formato do valor — tentar adivinhar o formato de um segredo não funciona. E é executada tanto na saída quanto na entrada, portanto uma ferramenta que repete sua própria entrada não pode vazar uma chave por meio do resultado. Cada lado é limitado a 8 000 caracteres, com um marcador informando quantos foram removidos.

As análises no nível do leitor nunca transmitem uma identidade a um cliente MCP. Um visitante é um pseudônimo: sha256(salt | repository | ip), truncado para 16 caracteres hexadecimais, com o salt mantido no lado do servidor. get_top_visitors, get_page_journeys e get_visitor_activity retornam esse pseudônimo, um país e eventos no nível da página; nenhuma ferramenta retorna um endereço IP, um nome ou um e-mail. O pseudônimo é restrito a um único repositório, portanto o mesmo leitor em dois dos seus sites corresponde a dois IDs não relacionados.

O que sai do seu espaço de trabalho#

Duas afirmações que a página de segurança de um fornecedor de documentação costuma fazer, corrigidas:

• "Seu conteúdo nunca sai do seu repositório" não é verdade aqui. O Docsbook armazena uma cópia pesquisável do texto das suas páginas e de suas incorporações vetoriais, e envia o texto das páginas a um provedor de modelos para criar essas incorporações e responder a chamadas de chat e de agentes. O que é verdade é que o GitHub continua sendo a fonte de verdade, portanto interromper o pagamento interrompe o trabalho medido sem excluir seu Markdown.
• As buscas de saída são protegidas, não apenas confiadas. Antes de qualquer busca, o esquema é verificado, o nome do host é resolvido e um endereço resolvido em um intervalo privado ou reservado é recusado — e a verificação é executada novamente a cada redirecionamento, para que uma URL pública não possa redirecionar para uma URL interna. robots.txt é respeitado e a resposta é limitada. O buscador de habilidades é ainda mais restrito: ele só buscará no próprio host e no prefixo de caminho do catálogo, portanto não pode ser transformado em um proxy de URL arbitrária.

Webhooks e hooks de chat não são a mesma coisa#

As entregas de webhooks de saída são assinadas. A assinatura é HMAC-SHA256 sobre os bytes exatos enviados, em X-Docsbook-Signature-256: sha256=<hex>, juntamente com X-Docsbook-Event. Uma URL de incoming webhook do Discord ou do Slack é adaptada para essa plataforma antes da assinatura, portanto a assinatura sempre abrange o que seu endpoint realmente recebe. O segredo é definido no registro, tem pelo menos 16 caracteres e nunca é retornado em texto simples posteriormente. As tentativas de entrega expiram após 15 segundos, e a resposta é armazenada de forma truncada.

Os hooks de chat não carregam nenhuma assinatura. Os hooks de pré-processamento, pós-processamento e streaming do assistente de documentação são objetos JSON simples POST, com tempo limite de 5 segundos e sem cabeçalho HMAC. Não reutilize seu código de verificação de webhook nesses hooks presumindo que ele verificou alguma coisa. O pre-hook também pode retornar inject_context, cujo texto entra no prompt do assistente — portanto, um endpoint para o qual você aponta um hook de chat pode influenciar o que o assistente diz; trate-o como uma infraestrutura confiável, autentique-o de alguma outra maneira e não aponte um hook para uma URL que você não controla.

Por que esta é a maneira correta (evidências)#

Mais um ponto cabe ao seu cliente, e não a nós: a especificação do MCP orienta os clientes a "considerarem as anotações de ferramentas não confiáveis, a menos que sejam provenientes de servidores confiáveis" e a manterem "uma pessoa no circuito com a capacidade de negar invocações de ferramentas" (Ferramentas MCP). Um token do Docsbook com acesso de leitura e gravação é exatamente o caso que merece essa intervenção humana.

Onde o Docsbook não atende à especificação MCP atualmente#

Estas são avaliadas em relação à revisão 2026-07-28. Cada uma representa uma lacuna no Docsbook, não uma discordância em relação à especificação.

O que o Docsbook ainda não tem#

Listado para que uma análise possa descartar o Docsbook em uma hora, em vez de na terceira semana.

Uma capacidade é frequentemente confundida com a segunda e a quarta linhas: um espaço de trabalho privado pode ser protegido por uma senha ou pelo seu próprio provedor OIDC por meio de update_access, em qualquer plano. Isso é logon único para os leitores do seu site de documentação. Não é logon único para os membros da sua conta do Docsbook e não concede acesso ao MCP.

Se a sua organização precisa de um artefato específico — um DPA do GDPR, um BAA, um questionário preenchido — escreva para support@docsbook.io e pergunte o que existe. A resposta hoje pode muito bem ser que não existe.

Limites e questões em aberto#

• Regiões de hospedagem em questão. Esta página deliberadamente não informa nenhuma região para o banco de dados ou para o armazenamento de análises. Ambos são serviços gerenciados cuja região é uma configuração de implantação, e não algo que um leitor possa verificar pelo comportamento do Docsbook, e uma versão anterior desta página informava regiões sem fonte. Se a residência dos dados fizer parte da sua análise, solicite ao suporte a resposta atual por escrito.
• O ID pseudônimo do visitante é um pseudônimo, não uma anonimização. Ele é um hash com salt de um endereço IP truncado para 64 bits. Qualquer pessoa que possua o salt e o armazenamento bruto de eventos poderia rederivá-lo; a garantia é que o salt não está nos dados e nenhuma API retorna um IP. Se isso atende ao seu órgão regulador é uma questão para o seu órgão regulador.
• Um token de leitura e escrita é uma credencial administrativa completa. Não há como conceder "pode editar páginas, mas não pode alterar configurações" ou "pode ler análises, mas não transcrições de chat". A hierarquia de escopos tem dois níveis.
• O escopo somente leitura é aplicado de forma incompleta. Oito ferramentas o verificam; os escritores de configurações, webhook, metas e traduções não o fazem, e as descrições de algumas dessas próprias ferramentas afirmam que exigem um token de leitura e escrita, quando nada faz essa verificação. Até que isso seja corrigido, o limite confiável é a propriedade da conta, não o escopo — portanto, isole por conta e consulte a lista aplicada acima, em vez da descrição de uma ferramenta.
• Nada aqui foi atestado de forma independente. Toda afirmação acima pode ser verificada no comportamento do Docsbook — emita um token somente leitura e observe um escritor recusá-lo; conecte um projeto que não é seu e observe que ele não é localizado —, mas nenhum terceiro o auditou. Trate esta página como uma especificação que você pode testar, não como uma certificação.
• A disponibilidade e o preço estão na página de preços. Nenhum valor é informado aqui, porque um preço copiado para a documentação fica desatualizado silenciosamente.

Relacionados#

• Servidor MCP — as próprias ferramentas e no que uma chamada se baseia
• Conteúdo pronto para agentes — as quatro interfaces para máquinas e como elas se integram
• Habilidades de documentação — o que uma habilidade pode e não pode fazer durante sua execução
• Webhooks — o esquema completo de eventos e a verificação de assinaturas
• Ganchos do chat de IA — os ganchos não assinados de pré, pós e streaming
• Fontes — o que um agente pode ler em seu nome