Ir para conteúdo principal

Construindo Extensões de Desktop com MCPB

Atualizado hoje

Este guia ajudará você a criar um MCP Bundle (.mcpb) para criar uma extensão de desktop para uso interno, distribuição privada ou como base para envio ao Diretório de Conectores da Anthropic.

1. Introdução

O que é um MCPB?

Arquivos MCPB (.mcpb) são arquivos zip contendo um servidor MCP local e manifest.json. Eles permitem instalação com um clique no Claude Desktop, similar a extensões de navegador.

Características principais:

  • Executa localmente na máquina do usuário

  • Comunica via transporte stdio

  • Agrupa todas as dependências

  • Funciona offline

  • Não requer OAuth

Saiba mais:

Quando devo usar um servidor local (MCPB) versus um servidor remoto?

Escolha um servidor local (MCPB) para:

Sistemas Internos e Segurança

  • Acessar sistemas atrás do seu firewall (JIRA, Confluence, wikis internos, bancos de dados privados)

  • Autenticação contínua - Usa sessões SSO e de navegador existentes automaticamente, sem gerenciamento de tokens

  • Conformidade com confiança zero - Opera dentro dos limites da sua rede corporativa sem expor recursos internos publicamente

Recursos Locais

  • Acesso direto ao sistema de arquivos para edição de código e operações Git

  • Integração com ferramentas instaladas localmente (Docker, IDEs, bancos de dados)

  • Integração de hardware e controle de aplicativos de desktop

  • Operações sensíveis à privacidade que não devem sair da máquina do usuário

Implantação Empresarial

  • Instalação com um clique com runtime Node.js integrado (sem dependências para gerenciar)

  • Sem infraestrutura em nuvem, configurações de VPN ou regras de firewall necessárias

  • Controles em nível organizacional - Administradores podem fazer upload de extensões personalizadas e gerenciar acesso via listas de permissão

  • Controle completo sobre autenticação, autorização e logs de auditoria
    ​

Escolha um conector remoto para:

  • Serviços em nuvem e APIs públicas que requerem infraestrutura centralizada

  • Distribuição entre Claude na web, mobile e desktop

  • Serviços que precisam de atualizações centralizadas em todos os usuários

  • Fluxos OAuth que requerem gerenciamento de tokens no lado do servidor

  • Integrações voltadas ao público usadas por múltiplas organizações

Diferença principal: MCPBs executam na máquina do usuário via transporte stdio com acesso a recursos locais e internos. Conectores remotos executam em seus servidores via HTTPS e são acessados através da infraestrutura da Anthropic.

Uso no mundo real: Organizações estão construindo MCPBs como proxies seguros para servidores MCP internos, para acesso a documentação interna e para conectar ferramentas de desenvolvimento mantendo sua arquitetura de segurança.

Para orientação sobre conectores remotos: Veja FAQ do Parceiro MCP para documentação completa de conectores remotos.

2. Primeiros Passos

Qual linguagem de programação devo usar?

Node.js é fortemente recomendado porque:

  • Vem com Claude para macOS e Windows (zero atrito de instalação para usuários)

  • Usuários não precisam de instalação de runtime separada

  • Melhor compatibilidade e confiabilidade com Claude Desktop

  • Suporte extensivo do SDK MCP

Quais plataformas devo suportar?

Claude Desktop executa em:

  • macOS (darwin)

  • Windows (win32)

Especifique plataformas suportadas na seção de compatibilidade do seu manifest.json.

Melhor prática: Teste em ambas as plataformas mesmo se você desenvolver principalmente em uma.

Detalhes de compatibilidade de plataforma: Veja Especificação do Manifest MCPB - Compatibilidade para especificação de plataforma e requisitos de runtime.

Como crio meu primeiro MCPB?

Siga este processo de cinco etapas:

1. Instale MCPB CLI: npm install -g @anthropic-ai/mcpb

2. Crie seu servidor MCP (veja SDK MCP)

3. Execute mcpb init para criar manifest.json

4. Execute mcpb pack para agrupar

5. Instale e teste no Claude Desktop

Para orientação de implementação detalhada:

  • Repositório MCPB - Guia completo de primeiros passos, uso de CLI e especificações

  • Exemplos MCPB - Implementações de referência funcionais incluindo "Hello World"

  • SDK MCP - Implementação do protocolo principal

Para orientação abrangente sobre desenvolvimento, testes e melhores práticas, veja a seção "Para Desenvolvedores de Bundle" do README do MCPB.

Importante: Antes de distribuir seu MCPB, revise a orientação de testes e melhores práticas no README do MCPB para garantir qualidade.

3. Configuração

O que é manifest.json?

O arquivo manifest.json é metadados obrigatórios que descrevem seu MCPB - o que faz, como executar, quais ferramentas fornece e qual configuração precisa.

Para as informações mais atualizadas, consulte a Especificação MCPB oficial.

Como adiciono um ícone?

Ícones são opcionais mas recomendados para aparência profissional.

Abordagem básica: Inclua arquivo icon.png no diretório raiz do seu bundle e referencie-o em manifest.json.

Requisitos:

  • Nome do arquivo: icon.png (ou caminho personalizado)

  • Tamanho: 512×512px recomendado (mínimo 256×256px)

  • Formato: PNG com suporte a transparência

  • Localização: Raiz do bundle ou caminho especificado

Opções avançadas: Múltiplas variantes de ícone para diferentes tamanhos e temas (suporte a modo claro/escuro).

Detalhes de implementação: Veja Especificação do Manifest MCPB - Ícones para:

  • Configuração do campo de ícone

  • Sintaxe de múltiplas variantes de ícone

  • Especificações de tamanho e tema

  • Melhores práticas e requisitos

Como os usuários configuram meu MCPB?

Defina a seção user_config em manifest.json. Claude Desktop cria automaticamente uma UI de configurações onde os usuários podem configurar sua extensão.

Veja Especificação do Manifest MCPB - Configuração do Usuário para a implementação completa:

  • Schema completo e exemplos

  • Todos os tipos e propriedades de configuração

  • Restrições de validação

  • Tratamento de dados sensíveis

  • Padrões de seleção múltipla

Como os usuários instalam meu MCPB?

Existem três métodos de instalação diferentes:

  1. Duplo clique - Baixe arquivo .mcpb e duplo clique para abrir

  2. Arrastar e soltar - Arraste arquivo .mcpb para a janela do Claude Desktop

  3. Menu de arquivo - Desenvolvedor → Extensões → Instalar Extensão → selecione arquivo .mcpb

Todos os métodos abrem UI de instalação onde os usuários podem:

  • Revisar detalhes da extensão e permissões

  • Configurar configurações obrigatórias

  • Conceder permissões necessárias

  • Completar instalação

Escopo de instalação: Instalação por usuário - cada usuário deve instalar separadamente em seu próprio sistema.

Experiência do usuário e controles de administrador: Para informações detalhadas sobre a experiência de instalação do usuário final e controles de administrador empresarial (incluindo gerenciamento de organização Team/Enterprise e configuração de política), veja:

4. Recursos

Documentação Oficial

Framework MCPB:

Protocolo MCP:

Claude Desktop:

Obtendo Ajuda

Canais de suporte:

Recursos da comunidade:

  • Verifique discussões do repositório para Q&A da comunidade

  • Acompanhe notas de versão para as atualizações mais recentes

  • Revise exemplos para padrões de implementação

Pronto para Distribuição Pública?

Se você construiu um MCPB funcionando e quer enviá-lo ao Diretório da Anthropic para distribuição mais ampla e descoberta, veja nosso guia complementar: Enviando para o Diretório da Anthropic.

O guia do diretório cobre requisitos adicionais incluindo:

  • Anotações de ferramenta obrigatórias para todas as ferramentas

  • Requisitos de política de privacidade

  • Mínimo de três exemplos funcionais

  • Credenciais de teste (se aplicável)

  • Processo de envio completo e cronograma de revisão

Artigos relacionados
Começando com Servidores MCP Locais no Claude Desktop
Construindo Conectores Personalizados via Servidores MCP Remotos
Ativando e usando a lista de permissões de extensão de desktop
Implantação de servidores MCP de nível empresarial com extensões de desktop
Guia de Envio de Servidor MCP Local
Isto respondeu à sua pergunta?