Servidor MCP

Hospede um servidor Model Context Protocol para que agentes de programação possam buscar e ler sua documentação diretamente — ferramentas, recursos, documentos de descoberta, filtros de tipo de conteúdo e facetas, o menu Connect to MCP e a saída de servidor que ele precisa.

Hospede um servidor Model Context Protocol para que agentes de programação (Claude Code, Cursor, VS Code, conectores do claude.ai) possam buscar e ler sua documentação diretamente — sem scraping. É opcional:

agents: {
  mcp: {
    enabled: true,
    route: "/mcp", // where the server is mounted
  },
}

Se uma página de conteúdo ou personalizada já ocupa essa rota, o servidor não é gerado: o build emite um aviso, e o llms.txt e os outros documentos de descoberta o deixam de fora.

Adicione um servidor MCP à sua documentação mostra o passo a passo, desde ativá-lo até implantar o servidor e conectar um cliente.

Ferramentas e recursos

O servidor expõe ferramentas somente leitura — search_docs, get_page, list_pages e get_navigation — e cada página como um recurso MCP (resources/list enumera as páginas em suas URLs servidas com o tipo text/markdown, deixando de fora as cópias de fallback de i18n das páginas não traduzidas, assim como list_pages faz; resources/read retorna o Markdown para agentes da página, a mesma saída de get_page), então clientes que anexam contexto por URI podem navegar pela documentação sem chamar uma ferramenta. Ele publica documentos de descoberta em /.well-known/mcp.json e /.well-known/mcp/server-card.json. O server card segue o schema da extensão Server Card da SEP-2127 (name em DNS reverso, endpoints de transporte remotes), com campos de compatibilidade no formato de initialize (serverInfo, capabilities, transports) para scanners construídos com base na revisão anterior da proposta. O menu Connect to MCP de cada página oferece instalação copiar-e-colar para Claude Code, Cursor, VS Code e Codex (exibido assim que deployment.site estiver definido), e você pode escolher os clientes que ele lista.

search_docs roda seu próprio índice de texto completo, então funciona independentemente do seu provedor de busca — e até mesmo com search: false. O servidor MCP é um recurso separado da busca na página.

Páginas ocultas ficam de fora de list_pages e resources/list, e de search_docs a menos que search.indexing.includeHiddenPages esteja ativado, assim como ficam de fora da busca do site e do llms.txt. get_page e resources/read ainda retornam uma página oculta pela sua rota: oculta não quer dizer privada, e a página continua sendo servida na sua URL e como Markdown.

As mesmas ferramentas estão disponíveis via HTTP simples como a API JSON, para frameworks que não falam MCP.

O endpoint lê o corpo da requisição somente até 64 KB e responde a qualquer coisa maior com 413. Uma chamada a uma ferramenta que não existe, ou com arguments que não sejam um objeto, recebe o erro Invalid params do JSON-RPC (-32602).

Escopo por tipo de conteúdo e facetas

search_docs e list_pages aceitam um filtro opcional contentTypes, restringindo os resultados a páginas dos types de frontmatter informados — ["rfc"], ["blog", "changelog"] — para que um agente trabalhando em um site que mistura documentação com RFCs, runbooks ou políticas consiga limitar a recuperação ao tipo de página de que precisa. Todo resultado informa seu tipo de conteúdo, e a saída de list_pages mostra os tipos em uso.

As duas ferramentas também aceitam um objeto filters que faz correspondência com as facetas que um site declara por tipo de conteúdo (content.types.<type>.facets) — chaves de frontmatter personalizadas cujos valores viram metadados filtráveis:

{
  "query": "OpenAPI request schemas",
  "contentTypes": ["rfc"],
  "filters": { "domain": "architecture", "status": "enforced" }
}

Cada entrada de filters precisa corresponder (os resultados carregam seus valores de faceta, e list_pages mostra os de cada página), então uma base de conhecimento pode conduzir fluxos de trabalho de agentes com divulgação progressiva — enumerar os padrões aplicados, buscar somente dentro deles — sem nenhum servidor próprio.

Um valor precisa corresponder exatamente ao que list_pages mostra, incluindo maiúsculas e minúsculas: "enforced" não corresponde a uma página cujo status é Enforced. Valores de faceta são strings, então um número ou booleano em filters corresponde à sua forma em string ({"priority": 1} encontra priority: 1), e um valor de qualquer outro formato, como uma lista, é ignorado em vez de filtrar.

Menu Connect to MCP

A ação de página Connect to MCP copia a URL do servidor e, em seguida, lista os clientes nos quais ela instala o servidor: comandos para copiar para Claude Code e Codex, e links de instalação para Cursor e VS Code. clients escolhe quais aparecem. true (o padrão) lista todos os clientes embutidos, false nenhum, o que deixa só Copy server URL no menu, e uma lista mostra os clientes que você indicar, na ordem, com um divisor entre os comandos e os links.

Um cliente que o Blume não inclui é um objeto com um label e o command a copiar. {name} no comando vira o nome do servidor como id: name, ou o título do site, em minúsculas, com cada sequência de caracteres fora de a–z e 0–9 trocada por um hífen e as pontas aparadas (docs se não sobrar nada). {url} vira a URL do servidor. Em um site multilíngue, o label pode ser um mapa de código de locale para texto. icon aceita o nome de um ícone embutido, um caminho/URL de imagem ou um SVG inline, e tem terminal como padrão.

agents: {
  mcp: {
    enabled: true,
    clients: [
      "claude-code",
      "codex",
      {
        label: "Copy Copilot CLI command",
        command: "copilot mcp add --transport http {name} {url}",
      },
      "cursor",
      "vscode",
    ],
  },
}

Saída de servidor obrigatória

O servidor MCP é um endpoint ativo (/mcp), então não pode rodar em um build estático. Informe um adaptador de host de blume/deploy para mudar para a saída de servidor:

import { node } from "blume/deploy"; // or vercel, netlify, cloudflare

export default defineConfig({
  deployment: node({ site: "https://docs.example.com" }),
});

Um build estático com agents.mcp.enabled falha imediatamente com uma mensagem pedindo que você defina um adaptador de host. Veja Deployment para os adaptadores. Depois de implantado, conecte-se pelo Claude Code com:

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