MCP for Dart

Un SDK de Dart para construir servidores y clientes MCP.

Documentación

MCP (Model Context Protocol) para Dart

mcp_dart es un SDK de Dart y Flutter de doble era para clientes, servidores y hosts de IA de MCP. Implementa la superficie de cable completa del núcleo cliente/servidor de la especificación MCP 2026-07-28 bloqueada, conserva el conjunto de funciones de MCP 2025-11-25 y negocia especificaciones anteriores basadas en inicialización compatibles.

Aquí, núcleo significa los requisitos normativos de cable asignados a los roles de cliente y servidor por la especificación final fijada. Excluye extensiones opcionales de MCP, comportamiento de UI del host, una implementación de servidor de autorización, resolución de referencias externas de JSON Schema y vocabularios personalizados de JSON Schema.

[!IMPORTANT] Esta versión es mcp_dart 2.4.2. La CLI estable versionada por separado sigue siendo mcp_dart_cli 0.2.1, que requiere mcp_dart ^2.4.2. El código fuente actual pasa cada requisito puntuado en los conjuntos oficiales de cliente y servidor alpha.11 de MCP 2025-11-25 y 2026-07-28, incluidos los 25 escenarios de autorización 2026 requeridos, más la interoperabilidad bidireccional publicada con TypeScript SDK 2.0.0 y Python SDK 2.1.1.

Objetivo de Nivel 1 del SDK

El proyecto está buscando MCP SDK Tier 1. El Nivel 1 aún no se reclama ni se asigna. La línea base técnica está en verde; los pasos restantes de auditoría oficial, gobernanza del repositorio y del Grupo de Trabajo del SDK se rastrean en la hoja de ruta y en el inventario de cobertura de 48 funciones.

El contrato público de mantenimiento está documentado en la guía de contribución, política de seguridad, política de dependencias y política de versionado.

Requisitos

Paquete	Dart SDK mínimo
`mcp_dart 2.4.2`	3.4
`mcp_dart_cli 0.2.1`	3.12

Los proyectos generados solo con SDK conservan el mínimo de Dart 3.4 del SDK. Los proyectos de CLI usan Dart 3.12 porque la CLI y su cadena de herramientas apuntan a esa versión.

Instala Dart desde dart.dev.

Instalación

Canal de producción

Usa el paquete estable más reciente para proyectos de producción:

dart pub add mcp_dart

Fijar la versión estable del SDK

Fija explícitamente la línea estable 2.4 cuando la resolución reproducible de dependencias sea importante:

dependencies:
  mcp_dart: ^2.4.2

Los fragmentos a continuación usan la línea estable actual del SDK. Las versiones de paquetes permanecen separadas de los perfiles de protocolo: McpProtocol.stable nombra la política de compatibilidad predeterminada del SDK.

El SDK y la CLI se versionan de forma independiente. La restricción ^2.4.2 de la CLI estable acepta versiones del SDK desde 2.4.2 hasta, sin incluir, 3.0.0.

Habilidades de agentes de IA

mcp_dart incluye habilidades de agente para construir servidores, construir clientes y servir o conectar a través de HTTP Streamable. Instálalas en el directorio de habilidades de tu agente de codificación desde la raíz de tu aplicación:

dart run skills@ get

Para integración directa del SDK, comienza con la guía de inicio. La CLI a continuación es opcional y proporciona comandos de andamiaje, inspección y conformidad.

Qué proporciona el SDK

Servidores, clientes e integraciones de host de MCP con APIs de Dart null-safe.
APIs de herramientas, recursos, indicaciones, finalización, elicitación, suscripciones, registro, raíces y muestreo con comportamiento seleccionado para la era de protocolo negociada. El registro de MCP 2026-07-28 se conserva por compatibilidad pero está obsoleto upstream.
Transportes Stdio, HTTP Streamable, flujo de IO y personalizados.
Hooks de descubrimiento/PKCE de cliente OAuth, callbacks de autenticación de servidor, protección contra rebinding de DNS y validación estricta de HTTP Streamable.
Una implementación experimental de la extensión Tasks, ayudantes de metadatos de MCP Apps y negociación genérica de extensiones. Las extensiones están separadas de la cobertura del protocolo central; Tasks no es una extensión oficial ni parte de la afirmación de conformidad central del SDK.
Conformidad automatizada de MCP 2025-11-25 y MCP 2026-07-28, interoperabilidad bidireccional publicada con TypeScript SDK 2.0.0, interoperabilidad bidireccional con Python SDK 2.1.1, pruebas de transporte en navegador real, una integración real de servicio Flutter Web en Chrome, pruebas de widgets deterministas y una compuerta independiente del conjunto de pruebas JSON Schema fijado.
mcp_dart 2.4.2 limita los mensajes entrantes de stdio y flujo de IO a 10 MiB de forma predeterminada, con límites configurables para mensajes más grandes. Consulta la guía de transporte antes de actualizar integraciones que intercambien marcos más grandes.
Acceso HTTP Streamable endurecido y diagnósticos de errores JSON-RPC, además del cliente heredado HTTP+SSE obsoleto y opcional con enrutamiento de mismo origen e interoperabilidad bidireccional contra pares oficiales de TypeScript SDK 1.30.0 y Python SDK 2.1.1.

MCP tiene tres roles: un host posee la experiencia del usuario, un cliente conecta ese host a un servidor, y un servidor expone herramientas, recursos e indicaciones. Un host puede gestionar múltiples clientes y servidores.

Perfiles de protocolo

Perfil	Comportamiento del protocolo
`McpProtocol.stable`	Perfil predeterminado de doble era: prefiere MCP 2026-07-28, luego retrocede a especificaciones MCP basadas en inicialización; las sondas de descubrimiento solo de cuerpo están limitadas a 5 segundos
`McpProtocol.legacy`	Perfil de era de inicialización: negocia la especificación MCP 2025-11-25, MCP 2025-06-18, MCP 2025-03-26, MCP 2024-11-05 o MCP 2024-10-07
`McpProtocol.require2026`	Requiere MCP 2026-07-28 y rechaza la inicialización heredada

Usa stableProtocolVersion o defaultProtocolVersion para MCP 2026-07-28. previewProtocolVersion permanece como un alias obsoleto para aplicaciones construidas contra una versión preliminar 2.3. latestInitializationProtocolVersion permanece 2025-11-25 cuando el perfil predeterminado retrocede al ciclo de vida heredado. Por compatibilidad, latestProtocolVersion y supportedProtocolVersions conservan sus valores de la era de inicialización de mcp_dart 2.2; usa allSupportedProtocolVersions para la lista de doble era.

Selecciona un perfil solo cuando necesites restringir la negociación:

final legacyClient = McpClient(
  const Implementation(name: 'my-client', version: '1.0.0'),
  options: const McpClientOptions(protocol: McpProtocol.legacy),
);

final strict2026Server = McpServer(
  const Implementation(name: 'my-server', version: '1.0.0'),
  options: const McpServerOptions(protocol: McpProtocol.require2026),
);

Consulta la guía de transición a MCP 2026-07-28 para reglas de retroceso y APIs específicas de MCP 2026-07-28, o ejecuta el ejemplo estricto de MCP 2026-07-28. Las aplicaciones que actualicen desde la línea estable 2.2 también deben seguir la guía de migración de 2.2 a 2.3.

Inicio rápido con la CLI

Instala la CLI estable correspondiente:

dart pub global activate mcp_dart_cli 0.2.1
mcp_dart create my_server
cd my_server
mcp_dart inspect

La CLI 0.2.1 crea un proyecto con mcp_dart: ^2.4.2. El inspector inicia el servidor stdio generado por sí mismo. Después de salir del inspector interactivo, puedes ejecutar una sola herramienta directamente:

mcp_dart inspect --tool add --json-args '{"a": 1, "b": 2}'

Comandos útiles:

Comando	Propósito
`create`	Crear un servidor MCP de Dart usando el canal del SDK emparejado con la CLI
`serve`	Ejecutar un servidor generado sobre stdio o HTTP
`doctor`	Verificar la salud y conectividad del proyecto
`inspect`	Usar interactivamente las capacidades de un servidor
`inspect-server`	Producir un informe estructurado para un servidor en vivo
`inspect-client`	Ejecutar un arnés stdio que inspecciona un cliente conectado
`trace`	Proxy y grabación de una sesión stdio real
`conformance`	Ejecutar los fixtures de regresión de protocolo integrados del repositorio

Consulta la documentación de la CLI para opciones de comandos y alcance.

Documentación

Comenzar: inicio, guía de servidor, guía de cliente, referencia rápida
Actualizar: guía de migración de 2.2 a 2.3, libros de recetas de migración, guía de transición a MCP 2026-07-28
Construir: herramientas, transportes, ejemplos, MCP Apps
Desplegar: seguridad de HTTP Streamable, ejemplos de OAuth, recetas de Flutter
Verificar: matriz de interoperabilidad, cobertura de MCP 2025-11-25, cobertura de MCP 2026-07-28, runbook del día 0

Los ejemplos de integración independientes pueden declarar requisitos más nuevos de Dart SDK; consulta el README de cada ejemplo antes de ejecutarlo.

Autenticación

StreamableHttpClientTransport admite OAuthClientProvider y descubrimiento opcional de código de autorización. Los servidores pueden usar authenticator o authenticationHandler y publicar metadatos de recursos protegidos.

Los ejemplos de OAuth incluidos almacenan tokens en archivos de texto plano para el aprendizaje local. Las aplicaciones de producción deben usar almacenamiento seguro de plataforma o un servicio de credenciales cifrado. Consulta los ejemplos de OAuth y autenticación de HTTP Streamable.

No expongas los servidores HTTP de ejemplo directamente a redes no confiables. Los despliegues de producción deben usar TLS, autenticar solicitudes y configurar las protecciones de Host y Origin documentadas.

Soporte de plataformas

Objetivo	Stdio	HTTP Streamable	HTTP+SSE heredado	Flujo IO/personalizado
VM de Dart / servidor de escritorio	Sí	Cliente y servidor	Cliente y servidor	Sí
Navegador / Flutter Web	Sin generación de procesos	Cliente	Cliente	Sí
Flutter móvil	Solo ayudantes nativos gestionados por la app	Cliente remoto	Cliente remoto	Sí
Flutter de escritorio	Procesos auxiliares locales	Cliente y servidor	Cliente y servidor	Sí

HTTP+SSE heredado está obsoleto bajo MCP SEP-2596 y se conserva solo para compatibilidad explícita. Usa HTTP Streamable para nuevas integraciones remotas.

Consulta recetas de host y cliente de Flutter para orientación sobre ciclo de vida y almacenamiento seguro.

Elegir un paquete MCP de Dart

El equipo de Dart mantiene dart_mcp en dart-lang/ai. Elígelo cuando prefieras las APIs del equipo de Dart. Elige mcp_dart cuando necesites la superficie de transporte, seguridad, compatibilidad, extensión e inspección de este SDK. Vuelve a verificar las versiones actuales de ambos paquetes antes de una decisión de producción.