MCP for Dart

Um SDK Dart para construir servidores e clientes MCP.

Documentação

MCP (Model Context Protocol) para Dart

mcp_dart é um SDK Dart e Flutter de dupla era para clientes, servidores e hosts de IA do MCP. Ele implementa a superfície de comunicação central completa de cliente/servidor da especificação MCP 2026-07-28 fixada, mantém o conjunto de recursos do MCP 2025-11-25 e negocia especificações anteriores suportadas baseadas em inicialização.

Aqui, central significa os requisitos normativos de comunicação atribuídos aos papéis de cliente e servidor pela especificação final fixada. Isso exclui extensões opcionais do MCP, comportamento de UI do host, uma implementação de servidor de autorização, resolução de referências externas do JSON Schema e vocabulários personalizados do JSON Schema.

[!IMPORTANT] Esta versão é mcp_dart 2.4.2. A CLI estável com versão separada permanece mcp_dart_cli 0.2.1, que requer mcp_dart ^2.4.2. O código-fonte atual passa em todos os requisitos pontuados nos conjuntos oficiais de cliente e servidor do MCP 2025-11-25 e 2026-07-28 alpha.11, incluindo todos os 25 cenários de autorização de 2026 exigidos, além de interoperabilidade bidirecional publicada com TypeScript SDK 2.0.0 e Python SDK 2.1.1.

Meta do SDK Nível 1

O projeto está buscando MCP SDK Nível 1. O Nível 1 ainda não foi reivindicado ou atribuído. A linha de base técnica está verde; as etapas restantes de auditoria oficial, governança do repositório e do SDK Working Group estão acompanhadas no roteiro e no inventário de cobertura de 48 recursos.

O contrato público de manutenção está documentado no guia de contribuição, política de segurança, política de dependências e política de versionamento.

Requisitos

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

Projetos gerados apenas com o SDK mantêm o mínimo de Dart 3.4 do SDK. Projetos de CLI usam Dart 3.12 porque a CLI e sua cadeia de ferramentas têm como alvo essa versão.

Instale o Dart em dart.dev.

Instalação

Canal de produção

Use o pacote estável mais recente para projetos de produção:

dart pub add mcp_dart

Fixe a versão estável do SDK

Fixe explicitamente a linha estável 2.4 quando a resolução reproduzível de dependências for importante:

dependencies:
  mcp_dart: ^2.4.2

Os trechos abaixo usam a linha estável atual do SDK. As versões dos pacotes permanecem separadas dos perfis de protocolo: McpProtocol.stable nomeia a política de compatibilidade padrão do SDK.

O SDK e a CLI têm versões independentes. A restrição ^2.4.2 da CLI estável aceita versões do SDK de 2.4.2 até, mas não incluindo, 3.0.0.

Habilidades de agente de IA

mcp_dart inclui habilidades de agente para criar servidores, criar clientes e servir ou conectar via Streamable HTTP. Instale-as no diretório de habilidades do seu agente de codificação a partir da raiz do seu aplicativo:

dart run skills@ get

Para integração direta com o SDK, comece com o guia de introdução. A CLI abaixo é opcional e fornece comandos de scaffolding, inspeção e conformidade.

O que o SDK oferece

Servidores, clientes e integrações de host MCP com APIs Dart null-safe.
APIs centrais de ferramentas, recursos, prompts, conclusão, elicitação, assinaturas, registro, raízes e amostragem com comportamento selecionado para a era de protocolo negociada. O registro do MCP 2026-07-28 é mantido para compatibilidade, mas está obsoleto upstream.
Transports Stdio, Streamable HTTP, fluxo de IO e personalizados.
Hooks de descoberta/PKCE do cliente OAuth, callbacks de autenticação do servidor, proteção contra rebinding de DNS e validação estrita do Streamable HTTP.
Uma implementação experimental da extensão Tasks, auxiliares de metadados do MCP Apps e negociação genérica de extensões. As extensões são separadas da cobertura central do protocolo; Tasks não é uma extensão oficial nem parte da alegação de conformidade central do SDK.
Conformidade automatizada com MCP 2025-11-25 e MCP 2026-07-28, interoperabilidade bidirecional publicada com TypeScript SDK 2.0.0, interoperabilidade bidirecional com Python SDK 2.1.1, testes de transporte em navegador real, uma integração real de serviço Flutter Web no Chrome, testes de widget determinísticos e um portão independente fixado do JSON Schema Test Suite.
mcp_dart 2.4.2 limita mensagens recebidas de stdio e fluxo de IO a 10 MiB por padrão, com limites configuráveis para mensagens maiores. Consulte o guia de transportes antes de atualizar integrações que trocam quadros maiores.
Acesso endurecido ao Streamable HTTP e diagnósticos de erro JSON-RPC, além do cliente legado HTTP+SSE obsoleto e opcional com roteamento de mesma origem e interoperabilidade bidirecional contra pares oficiais TypeScript SDK 1.30.0 e Python SDK 2.1.1.

O MCP tem três papéis: um host é dono da experiência do usuário, um cliente conecta esse host a um servidor, e um servidor expõe ferramentas, recursos e prompts. Um host pode gerenciar vários clientes e servidores.

Perfis de protocolo

Perfil	Comportamento do protocolo
`McpProtocol.stable`	Perfil padrão de dupla era: prefere MCP 2026-07-28, depois recorre a especificações MCP baseadas em inicialização; sondas de descoberta somente com corpo são limitadas a 5 segundos
`McpProtocol.legacy`	Perfil da era de inicialização: negocia a especificação MCP 2025-11-25, MCP 2025-06-18, MCP 2025-03-26, MCP 2024-11-05 ou MCP 2024-10-07
`McpProtocol.require2026`	Exige MCP 2026-07-28 e rejeita inicialização legada

Use stableProtocolVersion ou defaultProtocolVersion para MCP 2026-07-28. previewProtocolVersion permanece como um alias obsoleto para aplicativos criados contra um pré-lançamento 2.3. latestInitializationProtocolVersion permanece 2025-11-25 quando o perfil padrão recorre ao ciclo de vida legado. Para compatibilidade, latestProtocolVersion e supportedProtocolVersions mantêm seus valores da era de inicialização do mcp_dart 2.2; use allSupportedProtocolVersions para a lista de dupla era.

Selecione um perfil somente quando precisar restringir a negociação:

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),
);

Consulte o guia de transição para MCP 2026-07-28 para regras de fallback e APIs específicas do MCP 2026-07-28, ou execute o exemplo estrito de MCP 2026-07-28. Aplicativos que estão atualizando da linha estável 2.2 também devem seguir o guia de migração de 2.2 para 2.3.

Início rápido com a CLI

Instale a CLI estável correspondente:

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

A CLI 0.2.1 cria um projeto com mcp_dart: ^2.4.2. O inspetor inicia o servidor stdio gerado por conta própria. Depois de sair do inspetor interativo, você pode executar uma única ferramenta diretamente:

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

Comandos úteis:

Comando	Finalidade
`create`	Criar um servidor Dart MCP usando o canal do SDK emparelhado com a CLI
`serve`	Executar um servidor gerado via stdio ou HTTP
`doctor`	Verificar a saúde e a conectividade do projeto
`inspect`	Usar interativamente os recursos de um servidor
`inspect-server`	Produzir um relatório estruturado para um servidor ativo
`inspect-client`	Executar um harness stdio que inspeciona um cliente conectado
`trace`	Fazer proxy e gravar uma sessão stdio real
`conformance`	Executar os fixtures de regressão de protocolo integrados do repositório

Consulte a documentação da CLI para opções de comando e escopo.

Documentação

Comece: introdução, guia do servidor, guia do cliente, referência rápida
Atualize: guia de migração de 2.2 para 2.3, livros de receitas de migração, guia de transição para MCP 2026-07-28
Construa: ferramentas, transports, exemplos, MCP Apps
Implante: segurança do Streamable HTTP, exemplos de OAuth, receitas Flutter
Verifique: matriz de interoperabilidade, cobertura do MCP 2025-11-25, cobertura do MCP 2026-07-28, runbook do dia 0

Exemplos de integração independentes podem declarar requisitos mais novos do Dart SDK; verifique o README de cada exemplo antes de executá-lo.

Autenticação

StreamableHttpClientTransport suporta OAuthClientProvider e descoberta opcional de código de autorização. Servidores podem usar authenticator ou authenticationHandler e publicar metadados de recursos protegidos.

Os exemplos de OAuth verificados armazenam tokens em arquivos de texto simples para aprendizado local. Aplicativos de produção devem usar armazenamento seguro da plataforma ou um serviço de credenciais criptografado. Consulte os exemplos de OAuth e autenticação do Streamable HTTP.

Não exponha servidores HTTP de exemplo diretamente a redes não confiáveis. Implantações de produção devem usar TLS, autenticar solicitações e configurar as proteções de Host e Origin documentadas.

Suporte de plataforma

Alvo	Stdio	Streamable HTTP	HTTP+SSE legado	Fluxo IO/personalizado
VM Dart / servidor desktop	Sim	Cliente e servidor	Cliente e servidor	Sim
Navegador / Flutter Web	Sem criação de processo	Cliente	Cliente	Sim
Flutter mobile	Somente auxiliares nativos gerenciados pelo aplicativo	Cliente remoto	Cliente remoto	Sim
Flutter desktop	Processos auxiliares locais	Cliente e servidor	Cliente e servidor	Sim

O HTTP+SSE legado está obsoleto sob o MCP SEP-2596 e é mantido somente para compatibilidade explícita. Use Streamable HTTP para novas integrações remotas.

Consulte receitas de host e cliente Flutter para orientação sobre ciclo de vida e armazenamento seguro.

Escolhendo um pacote Dart MCP

A equipe do Dart mantém dart_mcp em dart-lang/ai. Escolha-o quando preferir as APIs da equipe do Dart. Escolha mcp_dart quando precisar da superfície de transporte, segurança, compatibilidade, extensão e inspeção deste SDK. Verifique novamente as versões atuais de ambos os pacotes antes de uma decisão de produção.