Next.js MCP Server

[!CAUTION] Este projeto está arquivado e não é mais suportado. Consulte a documentação para obter as informações mais recentes sobre como conectar seu agente às APIs da plataforma LlamaParse. Nosso endpoint MCP hospedado em produção está aqui.

Servidor MCP OAuth 2.1 como um aplicativo Next.js na Vercel

Este é um aplicativo baseado em Next.js que fornece um servidor MCP (Model Context Protocol) com suporte à autenticação OAuth 2.1. Ele foi criado como um modelo para você construir seu próprio servidor MCP em um contexto Next.js. Ele usa o @vercel/mcp-adapter para lidar com o protocolo MCP, a fim de suportar tanto os transportes SSE quanto Streamable HTTP.

Além de ser um servidor OAuth, ele também exige que o usuário se autentique. Atualmente, ele está configurado para usar o Google como provedor, mas você pode autenticar usuários da maneira que preferir (X, GitHub, seu próprio banco de dados de usuário/senha, etc.) sem quebrar o fluxo OAuth.

Como usar com

Claude Desktop e Claude.ai

O Claude atualmente suporta apenas o transporte SSE mais antigo, então você precisa fornecer a ele uma URL diferente da usada por todos os outros clientes listados aqui.

Use o botão "Connect Apps" e selecione "Add Integration". Forneça a URL como https://example.com/mcp/sse (o /sse no final é importante!). Observe que o Claude Desktop e o Web não aceitarão uma URL localhost.

Cursor

Edite seu mcp.json para que fique assim:

{
  "mcpServers": {
      "MyServer": {
        "name": "LlamaIndex MCP Demo",
        "url": "https://example.com/mcp/mcp",
        "transport": "http-stream"
      },
  }
}

VSCode

O VSCode atualmente não remove corretamente o ID do cliente, então o registro do cliente falha se você excluir acidentalmente o cliente (a solução alternativa nesse problema resolverá isso). Caso contrário, funciona normalmente. Adicione isto ao seu settings.json:

"mcp": {
    "servers": {
        "My Server": {
            "url": "https://example.com/mcp/mcp"
        }
    }
}

MCP Inspector

Diga ao Inspector para se conectar a https://example.com/mcp/mcp, com transporte Streamable HTTP. Você também pode usar o transporte SSE conectando-se a https://example.com/mcp/sse.

Executando o servidor

npm install
prisma generate
npm run dev

Na primeira vez, você também precisará executar prisma db push para criar as tabelas do banco de dados.

Variáveis de ambiente

As variáveis de ambiente obrigatórias devem estar em .env: (não em .env.local porque o Prisma não suporta isso)

DATABASE_URL="postgresql://user:pass@server/database"
AUTH_SECRET="any random string"
GOOGLE_CLIENT_ID="a Google OAuth client ID"
GOOGLE_CLIENT_SECRET="a Google OAuth client secret"
REDIS_URL="rediss://user:pass@host:6379"

DATABASE_URL é necessário para que a autenticação OAuth funcione; é aqui que as sessões etc. são armazenadas.

REDIS_URL é necessário se você precisar que o transporte SSE funcione (ou seja, se quiser suportar Claude Desktop e Web).

Arquitetura

Se você estiver usando este projeto como modelo para seu próprio aplicativo Next.js, as partes importantes são:

• /src/app/api/oauth/* - estes implementam o registro do cliente OAuth e a troca de tokens
• /src/app/oauth/authorize/page.tsx - este implementa a tela de consentimento OAuth (é extremamente básico no momento)
• /src/mcp/[transport]/route.ts - este implementa o próprio servidor MCP. Suas ferramentas, recursos etc. devem ser definidos aqui.

Para lidar com OAuth, seu aplicativo precisa ser capaz de persistir clientes, tokens de acesso etc. Para isso, ele usa um banco de dados PostgreSQL acessado via Prisma. Você pode trocar isso por outro banco de dados, se quiser (será mais fácil se for outro banco de dados suportado pelo Prisma).

Você também notará:

• src/app/auth.ts - este implementa a autenticação Auth.js para o seu próprio aplicativo. Ele está configurado para usar o Google como provedor, mas você pode alterá-lo para usar qualquer outro provedor suportado pelo Auth.js. Isso não é obrigatório para o servidor MCP funcionar, mas é uma boa ideia tê-lo em vigor para o seu próprio aplicativo.
• src/app/api/auth/[...nextauth]/route.ts - este conecta a autenticação Auth.js e também não faz parte da implementação OAuth.

Implantação em produção

Este aplicativo só funciona se implantado na Vercel atualmente, devido à sua dependência do pacote @vercel/mcp-adapter, que por sua vez é necessário para suportar o transporte SSE antigo. Não quisemos implementar um protocolo extra inteiro apenas para o Claude Desktop.

Implante como de costume. Você precisará adicionar prisma generate ao seu comando de build e, é claro, precisará de todas as mesmas variáveis de ambiente do ambiente de desenvolvimento.