Como fiz meu site totalmente legível por agentes: um servidor MCP + NLWeb /ask em Next.js

A maioria dos sites é construída para humanos com navegadores. Cada vez mais, o visitante é um agente de IA — Claude, um assistente personalizado, alguma ferramenta autônoma — e ele não quer sua animação de destaque. Ele quer respostas estruturadas e legíveis por máquinas e ações que pode realizar.

Eu reconstruí meu próprio site, yonyon.ai, para ser legível e usável por agentes de ponta a ponta: um endpoint /ask ao vivo (formato NLWeb da Microsoft), um verdadeiro servidor MCP em /mcp, ferramentas WebMCP no navegador, além de llms.txt e uma árvore de descoberta /.well-known/. Este post é o exemplo prático — as três peças que fizeram o trabalho pesado, com o código real.

A armadilha: roteamento de localidade consome seus endpoints de agente

Meu site é internacionalizado com next-intl. Seu middleware combina cada caminho e o roteia para um segmento [locale]. Assim, no momento em que adicionei uma rota /ask para agentes, o middleware i18n a capturou primeiro e tentou renderizar /[locale]/ask — 404. O mesmo problema ocorreria com /mcp.

Agentes esperam caminhos simples, sem prefixo (/ask, /mcp) — não /en/ask. A solução é interceptar esses caminhos no proxy/middleware, antes que o matcher i18n execute, e reescrevê-los para a rota da API real. rewrite() (não redirect()) preserva o método e o corpo HTTP, então um POST /ask continua sendo um POST:

// src/proxy.ts  (ponto de entrada do middleware next-intl)
import createMiddleware from "next-intl/middleware";
import { NextResponse, type NextRequest } from "next/server";
import { routing } from "./i18n/routing";

const intlMiddleware = createMiddleware(routing);

export default function proxy(request: NextRequest) {
  // Reescreve o /ask simples para o manipulador de rota /api/ask ANTES que o next-intl
  // o puxe para a árvore [locale] (o que resultaria em 404). rewrite() mantém o
  // método + corpo, então POST /ask funciona.
  if (request.nextUrl.pathname === "/ask") {
    return NextResponse.rewrite(new URL("/api/ask", request.url));
  }
  return intlMiddleware(request) as NextResponse;
}

export const config = {
  // Ignorar /api, /_next, arquivos estáticos, etc. — executar apenas em caminhos semelhantes a páginas.
  matcher: "/((?!api|studio|trpc|_next|_vercel|.*\\..*).*)",
};

Esse é todo o truque do alias: caminhos de agentes simples são correspondidos primeiro e reescritos para /api/*, para que nunca alcancem o roteador de localidade. Adicione uma linha por endpoint que você deseja expor sem prefixo.

Um servidor MCP sem dependências

O Modelo de Contexto de Protocolo é como os agentes descobrem e chamam suas ferramentas. O SDK oficial é ótimo — mas ele depende do zod 3, e meu repositório está em zod 4. Em vez de lutar contra a árvore de dependências, eu criei manualmente o manipulador. O transporte Streamable-HTTP do MCP é apenas JSON-RPC 2.0 sobre POST, e eu só precisava de um punhado de métodos: initialize, tools/list, tools/call, ping. Zero risco de dependência:

// src/app/api/mcp/route.ts
export const dynamic = "force-dynamic";

const SERVER_INFO = { name: "yonyon.ai", version: "1.0.0" };
const PROTOCOL_VERSION = "2025-06-18";

const TOOLS = [
  {
    name: "ask_yonatan",
    description: "Pergunte sobre o trabalho, projetos ou experiência de Yonatan Gross.",
    inputSchema: {
      type: "object",
      properties: { question: { type: "string"