nextjs-mcp-kit

Un servidor MCP, un cliente MCP y una interfaz de chat agnóstica respecto al proveedor para Next.js App Router — como manejadores de rutas, componentes y estado tipado que puedes instalar.

Dale a tu aplicación un pequeño chat que de verdad sabe cosas sobre tu aplicación.

Chat inteligente — las respuestas son las que tú escribiste, documentos subidos por ti

• las herramientas que añades Añades las respuestas desde un formulario en el navegador para crear la herramienta. Sin reentrenamiento, sin base de datos vectorial, sin redespliegue.

No es deliberadamente inteligente. Es el pequeño chat que saluda y conoce tu horario de apertura, y tener uno lleva aproximadamente un minuto.

npm i nextjs-mcp-kit && npx nextjs-mcp-kit init

nextjs-mcp-kit — opciones del scaffolder

npx nextjs-mcp-kit init // crea el andamiaje en el directorio actual

npx nextjs-mcp-kit init --force // sobrescribe los archivos que ya existen

npx nextjs-mcp-kit init --dir web // crea el andamiaje en ./web

Luego salta a Tu primera herramienta, en 60 segundos.

Seis superficies, deliberadamente separadas:

Añade una herramienta desde el navegador y estará disponible en el chat inmediatamente — y se sirve a través de MCP a cualquier cosa que apunte a tu aplicación, incluido el cliente de otra persona.

Related MCP server: Example Next.js MCP Server

Tu primera herramienta, en 60 segundos

Sin API, sin clave, sin código. Ejecuta npm run dev, abre /add-tool y deja la primera opción en "Devuelve el texto que yo escribo":

Deja los parámetros vacíos. Pulsa Añadir herramienta.

Ahora abre /personal-chat, marca opening_hours y pregunta "¿estás abierto el sábado?"

El modelo responde "no — cerrado los fines de semana", y debajo de la respuesta dice que se ejecutó opening_hours y muestra exactamente lo que devolvió la herramienta. No lo sabía. Se lo dijiste hace treinta segundos, a través de un formulario.

Ese es todo el ciclo. Todo lo demás en este README es ese ciclo con más opciones.

Por qué la descripción importa más de lo que parece

La descripción no es documentación — es cómo decide el modelo si llamar o no a la herramienta. "opening hours" se ignora la mitad de las veces. "The shop opening hours. Call this when asked when we are open." hace que se llame. Una descripción vaga significa una herramienta que está registrada y nunca se elige.

Para qué sirve esto

Un pequeño chat para tus visitantes. No es lo bastante inteligente para ser un agente de soporte, y no pretende serlo. Lo bastante inteligente para saludar a alguien y responder a las seis preguntas que de verdad le hacen a tu aplicación, a partir de respuestas que tú escribiste. Cada una de esas respuestas es una herramienta skill: un nombre, una descripción y el texto que debe devolver.

Respuestas fundamentadas en lo que le contaste. Cuando una herramienta encaja con la pregunta, el modelo la llama y responde a partir de lo que devolvió — no de lo que recuerda a medias sobre las tiendas en general. Una pregunta que cubren tus herramientas la responden tus herramientas.

Siempre puedes ver qué ha pasado. Cada respuesta que usó una herramienta la nombra y muestra lo que devolvió. Si la respuesta vino de tu texto, puedes demostrarlo; si el modelo respondió por su cuenta, el rastro está vacío y también puedes verlo. Sin adivinar cuál de las dos te ha tocado.

Sin fallbacks silenciosos. Si un proveedor no puede llamar a herramientas, o un modelo de Ollama no tiene esa capacidad, recibes un 503 con el motivo antes de que se ejecute el turno — nunca una respuesta que ignoró silenciosamente las herramientas que marcaste.

Gratis de ejecutar. Ollama es local, así que un chat de visitante no cuesta nada por mensaje y ningún dato sale de la máquina. Cambia a Claude para uno mejor con las mismas herramientas — el selector muestra 💳 para un turno de pago, 🖥️ para uno local.

También es un servidor MCP. Las mismas herramientas que añadiste desde el navegador se sirven a través de MCP, así que Claude Desktop — o el cliente de cualquiera — puede apuntar a tu aplicación desplegada y usarlas. Consulta Conexión de un cliente MCP.

Qué página dar a tus visitantes

/smart-chat es a la que debes apuntarles. Una pregunta entra, una respuesta sale — comprueba todas las herramientas que tienes registradas, usa la que encaje y dice cuál se ejecutó. Sin conversación que mantener, sin historial que almacenar, nada que un visitante tenga que configurar.

// app/ask/page.tsx — your public "ask us anything" page
export { SmartChatPage as default } from 'nextjs-mcp-kit/pages';

O coloca solo el componente en una página propia:

import { SmartChat } from 'nextjs-mcp-kit/components';

/personal-chat es la que es para ti: una conversación completa, instrucciones y una lista de verificación de qué herramientas puede usar esta conversación. Es donde pruebas una herramienta nueva antes de dejar que nadie más se acerque a ella.

/add-tool y /mcp-dashboard también son tuyas, no de tus visitantes. Ninguna tiene autenticación — ponlas detrás de la tuya, o no las incluyas en la aplicación pública.

Funciona con Ollama (local, gratis) y Claude (Anthropic). Añadir un tercer proveedor es un archivo y una entrada de array.

Instalación

Requiere Next.js 16+ y Node 20.9+. El rango de pares es >=16.0.0 en lugar de >=15.0.0 deliberadamente: 16 es la única versión principal contra la que esto se ha construido y probado, y un rango de pares debe describir lo que realmente se ha verificado, no lo que podría funcionar. En Next 15, npm i informará de un conflicto de pares — esa es la señal prevista, no un error.

En una aplicación Next.js existente

npm i nextjs-mcp-kit
npx nextjs-mcp-kit init

init escribe los manejadores de rutas y /chat. No toca tu layout raíz — añade dos líneas tú mismo:

// app/layout.tsx
import { GlobalProvider } from 'nextjs-mcp-kit/context';
import 'nextjs-mcp-kit/styles.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <GlobalProvider>{children}</GlobalProvider>
      </body>
    </html>
  );
}

Luego cp env.local.example .env.local y npm run dev.

Importar un componente: lo único que hace tropezar a la gente

Los componentes no se exportan desde la raíz del paquete. Esto falla:

import { AgentChat } from 'nextjs-mcp-kit';
// The export AgentChat was not found in module .../dist/index.js [app-rsc]
// Did you mean to import initialAgent?

Esto funciona:

import { AgentChat } from 'nextjs-mcp-kit/components';

La entrada raíz es segura para servidor a propósito — consulta Exportaciones. Regla general: si renderiza, no está en la raíz.

Arreglar la importación es necesario pero no suficiente: AgentChat necesita que /api/providers, /api/chat y /api/instructions existan en tu aplicación, y GlobalProvider por encima. npx nextjs-mcp-kit init escribe las rutas; el layout es tuyo. Una aplicación completa y funcional — además de una lista de solución de problemas en el orden en que las cosas se rompen realmente — está en la rama examples.

Independiente, desde un directorio vacío

mkdir my-app && cd my-app
npm init -y
npm i nextjs-mcp-kit
npx nextjs-mcp-kit init          # detects the empty dir, writes a whole app
npm i next react react-dom
npm i -D typescript@^5 @types/node @types/react @types/react-dom
cp env.local.example .env.local
npm run dev

typescript@^5 está fijado deliberadamente. Un npm i -D typescript a secas actualmente resuelve a TypeScript 7, cuyo lib/ reestructurado Next 16 no detecta — informa de que "no tienes instalados los paquetes requeridos" aunque esté instalado, y la compilación falla.

Configuración

OLLAMA_API_URL=http://localhost:11434   # 11434 is Ollama's default port
ANTHROPIC_API_KEY=                      # empty is fine — runs local-only
NEXTJS_MCP_DATA_DIR=                    # defaults to ./.data

Dejar ANTHROPIC_API_KEY vacía es un modo admitido, no uno roto: el selector muestra Claude como no disponible con el motivo, y Ollama sigue funcionando. Ese es el sentido de isAvailable() — una clave ausente es un estado normal que se informa de antemano, no una excepción que se lanza al pulsar Enviar.

En hosts serverless, define NEXTJS_MCP_DATA_DIR=/tmp/nextjs-mcp-kit; su sistema de archivos empaquetado es de solo lectura salvo /tmp. Consulta Persistencia.

Rutas

Los códigos de estado tienen significado: 503 cuando un proveedor simplemente no está disponible (la solicitud era correcta), 400 en entrada incorrecta, 500 en un fallo real.

curl -X POST localhost:3000/api/chat -H 'content-type: application/json' -d '{
  "provider": "ollama",
  "model": "llama3.1:8b",
  "system": "Answer in one word.",
  "messages": [{ "role": "user", "content": "Capital of France?" }]
}'
# {"answer":"Paris","provider":"ollama","model":"llama3.1:8b","billed":false}

Herramientas

/api/chat no tiene herramientas y nunca las tendrá. La llamada a herramientas es su propia ruta, que llama directamente al registro de proveedores — no envuelve a /api/chat.

curl -X POST localhost:3000/api/agent-chat -H 'content-type: application/json' -d '{
  "provider": "anthropic",
  "model": "claude-haiku-4-5-20251001",
  "messages": [{ "role": "user", "content": "What is the refund window?" }],
  "tools": ["refund_policy"]
}'
# {"answer":"…","provider":"anthropic","model":"…","billed":true,
#  "trace":[{"name":"refund_policy","result":"…","isError":false,"ms":2}]}

trace es la razón por la que esto merece la pena: una respuesta que usó una herramienta puede demostrarlo.

Añade "stream": true para NDJSON — un objeto JSON por línea, {"type":"token"} … {"type":"done"}. Léele con streamAgentChat de nextjs-mcp-kit/client en lugar de parsearlo tú mismo.

Qué herramientas se ejecutan es enteramente decisión de quien llama: sin tools[] significa un turno simple. Nada se descarta silenciosamente nunca — un proveedor que no puede llamar a herramientas, o un modelo de Ollama sin esa capacidad, recibe un 503 con el motivo en lugar de una respuesta que ignoró silenciosamente lo que pediste.

Configuración de segmento de ruta

Cada ruta generada declara su propio runtime:

export { POST } from 'nextjs-mcp-kit/api/chat';

export const runtime = 'nodejs';
export const maxDuration = 120;

Eso no es plantilla que puedas eliminar. Next lee la configuración de segmento estáticamente desde el propio módulo de la ruta, así que un runtime reexportado se ignora silenciosamente y el manejador se ejecuta en el incorrecto.

Añadir un proveedor

La capa de proveedores es el único lugar que conoce los backends de modelos. Dos pasos:

1. Escribe un ChatProvider:

import type { ChatProvider } from 'nextjs-mcp-kit/types';

export const myProvider: ChatProvider = {
  id: 'mine',
  label: 'My backend',
  defaultModel: 'some-model',
  billed: false,
  dynamicModels: false,

  // Never throws. A missing key or a down daemon is a normal state.
  async isAvailable() {
    return process.env.MY_KEY
      ? { available: true }
      : { available: false, reason: 'MY_KEY is not set' };
  },

  async listModels() {
    return [{ id: 'some-model', label: 'Some model' }];
  },

  // `system` arrives separately: Anthropic takes it as a top-level field,
  // Ollama as a message role. That difference is absorbed here, per provider.
  async chat({ model, system, messages }) {
    return { text: '…', model };
  },
};

2. Añádelo al registro.

Nada más cambia. Ni la ruta, ni el reducer, ni el selector, ni una unión de tipos — ProviderId es string a propósito. /api/providers y ProviderModelPicker están impulsados por el registro, así que un nuevo proveedor aparece en ambos desplegables con cero ediciones en el cliente.

billed controla la insignia 💳/🖥️. Un turno de pago nunca debe ser una sorpresa.

Para que tu proveedor pueda llamar a herramientas, añade el opcional chatWithTools. Sigue siendo opcional para que un proveedor sin él siga siendo perfectamente utilizable — y se informa como incapaz de usar herramientas en lugar de responder silenciosamente sin las herramientas que se pidieron:

async chatWithTools({ model, system, messages, tools, run, onToken }) {
  // `tools` is neutral — translate it with your dialect:
  //   import { DIALECTS } from 'nextjs-mcp-kit/tools';
  //   const declared = DIALECTS.openai.toTools(tools);
  // Then loop: ask, ingestToolCalls(raw), await run(call), feed results back.
  return { text: '…', model, trace: [] };
}

La mayoría de los backends nuevos son compatibles con OpenAI, y DIALECTS.openai ya existe — así que un nuevo proveedor normalmente no añade ningún dialecto.

Cómo funcionan las herramientas por debajo

Una herramienta se almacena una vez, con una forma neutra. La ortografía de cada proveedor se deriva de ella:

import { deriveByProvider } from 'nextjs-mcp-kit/tools';

deriveByProvider(tools).anthropic; // [{ name, description, input_schema }]
deriveByProvider(tools).ollama;    // [{ type:'function', function:{ … } }]

Eso importa porque Anthropic y Ollama discrepan en cada paso — la clave del esquema, si las llamadas llevan un id, y cómo se devuelven los resultados. Dos listas mantenidas a mano divergirían la primera vez que se editara una.

Dos tipos, ambos invocables desde el primer día:

skill es la forma en que un documento o un cuerpo con forma de SKILL.md se convierte en una herramienta sin sistema de archivos. El texto es un campo de un registro.

El problema del id, y cómo se resuelve. Anthropic asigna a cada llamada de herramienta un id y empareja los resultados mediante tool_use_id; la API nativa de Ollama no envía ningún id y empareja por orden. Un único bucle que asuma cualquiera de los dos se rompe con el otro. Por eso no se hace ninguna suposición fuera de un único archivo: ingestToolCalls() conserva el id cuando lo hay, genera name#index cuando no lo hay y normaliza los argumentos que llegaron como cadena JSON. Tras la ingesta, los dos proveedores son indistinguibles, y cada uno sigue devolviendo resultados como exige su propia API.

Las piezas de React viven en sus propias subrutas para que importarlas no pueda arrastrar los built-ins de Node — o ANTHROPIC_API_KEY — a un bundle de cliente. Si se renderiza, no está en la raíz.

Las subrutas se resuelven mediante el mapa exports en package.json, que necesita "moduleResolution": "bundler" en tu tsconfig.json. create-next-app ya lo configura; con el ajuste heredado "node", todas las subrutas fallan al resolver con Cannot find module 'nextjs-mcp-kit/components'.

Estado

Un Context de valor dividido: { state, actions }, consumido mediante useContextState() / useContextActions(). Los componentes que solo despachan no se vuelven a renderizar cuando cambia un estado no relacionado.

'use client';
import { useContextState, useContextActions } from 'nextjs-mcp-kit/context';

function MyChat() {
  const { agent, instruction } = useContextState();
  const { sendChat, selectProvider } = useContextActions();
  // agent.chat, agent.provider, agent.model, agent.routing …
}

Dos slices, agent e instruction. Las acciones leen el estado actual a través de un ref en lugar de un closure, lo que mantiene estable la identidad de cada acción durante toda la vida del proveedor — sin ello, sendChat se reconstruiría en cada pulsación de tecla.

Presets vs. systemText

Son dos cosas distintas, y confundirlas sería un error:

• presets — la lista guardada y persistida.

• systemText — el texto editable que se envía realmente en el siguiente turno.

Seleccionar un preset siembra systemText. Editarlo después no muta el preset guardado. Un preset es un punto de partida, no una jaula. Guardar con un nombre existente edita ese preset (el id se deriva del nombre) en lugar de acumular casi duplicados.

Temas

Todos los colores provienen de propiedades personalizadas de CSS. Sobrescribe cualquiera de ellas después del import — esa es toda la historia del tema:

:root {
  --mcp-bubble-user: #dcfce7;
  --mcp-border: #cbd5e1;
}

Tanto el modo claro como el oscuro se definen mediante prefers-color-scheme.

Persistencia

Los presets de instrucciones y las herramientas se almacenan como JSON en NEXTJS_MCP_DATA_DIR (por defecto ./.data) — lo más pequeño que sobrevive a un reinicio. Añade .data/ a tu .gitignore.

.data/
  instructions.json
  tools.json

Es un almacén de archivos, así que en serverless es por instancia y efímero — el sistema de archivos del bundle es de solo lectura salvo /tmp, que se borra entre invocaciones. Si necesitas durabilidad, sustituye dos archivos: src/store/instructions.ts y src/store/tools.ts son los únicos sitios donde las rutas leen o escriben.

El cuerpo de una skill es un campo de un registro de herramienta, no un archivo en disco. Subir un documento no crea un SKILL.md en ningún sitio, y nada en este paquete escribe jamás en el árbol de fuentes de tu aplicación.

Conectar un cliente MCP

{
  "mcpServers": {
    "nextjs-mcp-kit-local": {
      "type": "http",
      "url": "http://localhost:3000/api/mcpserver/mcp"
    }
  }
}

Observa el sufijo /mcp — la ruta es un segmento dinámico [transport], así que apuntar un cliente solo a /api/mcpserver no conectará.

Este endpoint es una superficie pública, no una puerta privada. Despliega tu aplicación y cualquiera puede apuntar su propio cliente MCP a https://your-app.example.com/api/mcpserver/mcp con su propio modelo y su propia clave — no hay nada tuyo que puedan tomar. Ven todos los prompts y todas las herramientas que hayas añadido, y /mcp-dashboard muestra exactamente qué es eso.

Lo que deliberadamente no hace

• Sin herramientas en /chat. Esa ruta envía mensajes y nada más, a propósito. Las herramientas viven en /api/agent-chat y en las cuatro páginas anteriores.

• Sin streaming en /api/chat. Sus respuestas llegan completas y su forma no ha cambiado. /api/agent-chat transmite en streaming.

• Sin autenticación. Monta estas rutas detrás de la tuya. Ten en cuenta que /api/mcpserver/mcp es público por diseño — está pensado para que apunten a él.

• Sin subida de .docx ni .pdf. Solo .md y .txt, porque soportarlos añade cero dependencias a un paquete que instalas. Añadir un formato es una rama en src/server/extractText.ts.

• Sin base de datos. Las herramientas y los presets son archivos JSON. En serverless eso es por instancia y efímero — intercambia los dos archivos del store.

• Nada preconstruido "para más adelante". Sin registros de marcador de posición, sin abstracciones muertas.

Requisitos

Next.js ≥ 16 (App Router), React ≥ 18.3, Node ≥ 20.9. Probado con Next 16.2 y React 19.2.

Una nota

La arquitectura de nextjs-mcp-kit implementa un límite estricto que separa los componentes públicos del lado del cliente de la ejecución segura del lado del servidor. La capa de cliente basada en React coordina los estados interactivos y las interfaces de chat, pero opera completamente ciega a las variables de entorno sensibles o a las credenciales de terceros. La seguridad se mantiene porque todas las claves de API, las ejecuciones locales de herramientas y las llamadas directas a LLM residen exclusivamente detrás de los Route Handlers de Next.js en un runtime seguro de Node.js. La comunicación entre estos límites se estructura en torno a acciones HTTP POST estándar para eventos iniciados por el usuario y Server-Sent Events (SSE) para la transmisión de datos en tiempo real unidireccional. Esta configuración garantiza que los flujos de trabajo complejos de múltiples agentes sigan siendo muy receptivos mientras se adhieren a las estrictas directrices de seguridad empresarial modernas.

La arquitectura de nextjs-mcp-kit implementa un límite estricto que separa los componentes públicos del lado del cliente de la ejecución segura del lado del servidor. La capa de cliente basada en React coordina los estados interactivos y las interfaces de chat, pero opera completamente ciega a las variables de entorno sensibles o a las credenciales de terceros. La seguridad se mantiene porque todas las claves de API, las ejecuciones locales de herramientas y las llamadas directas a LLM residen exclusivamente detrás de los Route Handlers de Next.js en un runtime seguro de Node.js. La comunicación entre estos límites se estructura en torno a acciones HTTP POST estándar para eventos iniciados por el usuario y Server-Sent Events (SSE) para la transmisión de datos en tiempo real unidireccional. Esta configuración garantiza que los flujos de trabajo complejos de múltiples agentes sigan siendo muy receptivos mientras se adhieren a las estrictas directrices de seguridad empresarial modernas.

Lo interesante de este paquete es lo poco de tu tiempo que pide.

Todo lo que normalmente es el trabajo — la costura de proveedores, el bucle de llamada a herramientas, el desacuerdo entre los dos proveedores sobre cómo se declaran las herramientas y cómo vuelven los resultados, el streaming, el servidor MCP, la persistencia — está hecho. Instalado, no copiado. Sigue hecho cuando haces npm update, y nada de eso es código que tengas que leer, poseer o mantener.

Lo que queda para ti es la única parte que realmente fue tuya: decidir lo que tu chat debería saber. Eso es un nombre, una frase que describe cuándo usarlo, y la respuesta. Escrito en un formulario, en un navegador, en menos de un minuto. Diez de esos y tienes un chat que conoce tu aplicación mejor de lo que cualquier asistente de propósito general lo hará jamás — porque nadie más tiene tus horas de apertura, tu ventana de devoluciones o tus reglas de envío.

Así que la forma del trabajo es inusual: una tarde, y la mayor parte dedicada a pensar en lo que tus visitantes preguntan realmente, en lugar de en los esquemas de herramientas y las APIs de los proveedores. La demo es rápida de construir y desproporcionadamente buena para mostrar, porque lo que la gente encuentra impresionante — lo sabía sobre tu aplicación — viene de la parte que te llevó un minuto, no de la que llevó meses.

Dos cosas que merece la pena saber antes de empezar, para que nada aquí se sobrevenda. Este es un chat centrado por diseño: es muy bueno respondiendo a partir de lo que le diste, y no intenta ser un asistente de propósito general. Y no hay autenticación en ningún sitio de este paquete — /add-tool y /mcp-dashboard son tuyos, no de tus visitantes. Ponlos detrás de tu propia autenticación, o no los montes en la aplicación pública en absoluto.

Más allá de eso, ve y construye algo con ello. Fue escrito para ser extendido, no solo admirado: un nuevo proveedor es un archivo y una entrada de array, un nuevo tipo de herramienta es una rama, y el store son dos archivos que intercambiar por una base de datos real. Si haces algo con ello, de verdad me gustaría verlo.

Gracias ❤️

Este kit es una capa fina que se apoya en el trabajo considerable de otras personas.

Ollama ❤️ — por hacer que los modelos locales sean genuinamente fáciles. Sin cuenta, sin clave, sin factura: descarga un modelo y responde. Esa es toda la razón por la que nextjs-mcp-kit puede ser útil en el momento en que lo instalas, y por la que el proveedor por defecto es el local.

Claude y Anthropic ❤️ — por los modelos, y por el Model Context Protocol. MCP es la base sobre la que se construye la ruta /, y se entregó como una especificación abierta en lugar de mantenerse como un foso. Este paquete no existiría con esta forma sin esto.

Ambos proveedores son de primera clase aquí a propósito. Uno es local y gratuito, el otro está alojado y es excelente, y la interfaz de proveedor existe para que ninguno tenga que ganar.

License

MIT