Um Guia para Desenvolver Extensões MCP Personalizadas: Do Layout do Repositório Até ao Lançamento

As extensões MCP personalizadas transformam um assistente genérico num especialista que pode fazer trabalho nos seus sistemas—de forma segura, repetível e com guardrails.

O que “Extensão MCP” Realmente Significa em Repositórios MCP

Em repositórios MCP, uma “extensão” é normalmente uma de duas coisas:

1. Um servidor MCP autónomo que publica (ou mantém privado) capacidades—ferramentas, recursos e prompts—através do Model Context Protocol.
2. Um módulo/pacote do repositório que ajuda a construir, configurar ou implantar servidores MCP (por exemplo, uma biblioteca de handlers de autenticação partilhados, validação de esquemas ou templates de deployment).

A maioria das equipas refere-se ao primeiro: um servidor MCP personalizado que acrescenta capacidades específicas do domínio, como “consultar o inventário do armazém”, “abrir um ticket no Jira”, “gerar um relatório de conformidade” ou “resumir as chamadas de clientes da semana passada”.

O MCP é intencionalmente simples ao nível do protocolo, mas extensões reais envolvem design cuidadoso: âmbito, autenticação, saída previsível, tratamento de erros e documentação que torne a extensão utilizável por humanos e por modelos.

Comece com o Design da Capacidade (Antes de Escrever Código)

A forma mais rápida de construir uma extensão desordenada é começar por implementar endpoints. A forma mais rápida de construir uma extensão fiável é começar com design de capacidades.

Decida o que Está a Expor: Ferramentas vs Recursos vs Prompts

Servidores MCP podem expor três tipos principais de capacidade:

• Ferramentas: funções invocáveis que fazem alguma coisa. Exemplos: create_ticket, search_docs, run_sql_readonly.
• Recursos: dados estruturados que podem ser obtidos e referenciados. Exemplos: uma árvore de ficheiros, um artigo de base de conhecimento, um registo de cliente.
• Prompts: templates de prompt reutilizáveis que orientam o modelo de forma consistente para tarefas comuns.

Uma heurística prática:

• Se altera estado ou desencadeia uma ação: ferramenta.
• Se é principalmente “ler e citar”: recurso.
• Se é “repetir este workflow frequentemente”: prompt.

Reduza a Superfície de Exposição

Os mantenedores de extensões frequentemente sobrestimam quantas ferramentas precisam. Comece com menos ferramentas que sejam robustas e composáveis.

Padrão ruim:

• create_ticket_bug
• create_ticket_task
• create_ticket_incident

Padrão melhor:

• create_ticket com um campo type restrito, validado do lado do servidor.

O seu eu do futuro agradece quando precisar de adicionar logging, limites de quota ou verificações de permissão—uma vez, não três.

Escreva “Contratos de Ferramenta” a Sério

Antes da implementação, escreva um contrato de uma página por ferramenta:

• Nome: estável, lower_snake_case
• Propósito: uma frase
• Inputs: esquema com tipos e restrições
• Outputs: esquema com exemplos
• Modos de erro: falhas típicas e mensagens
• Segurança: scopes necessários, redacções, requisitos de auditoria
• Idempotência: o que acontece se a ferramenta for chamada duas vezes?

Trate estes contratos como parte do seu repositório. Em muitos repositórios MCP, estes documentos tornam‑se o seu melhor ativo de manutenção a longo prazo.

Escolha uma Arquitetura de Extensão que Não o Prenda Depois

Tipicamente irá implementar um servidor MCP como um pequeno serviço que comunica MCP sobre stdio ou HTTP (dependendo do seu stack e cliente). Independentemente do transporte, quer uma estrutura que suporte:

• Adicionar ferramentas sem espalhar ficheiros
• Autenticação e políticas centralizadas
• Validação partilhada e formatação de erros
• Saídas determinísticas
• Testes sem credenciais reais

Um Layout de Repositório Limpo para Extensões MCP

Um layout amplamente funcional:

• src/
  • server/ (fiação MCP, registo, transporte)
  • tools/ (um ficheiro por ferramenta ou por domínio)
  • resources/ (handlers de recursos)
  • prompts/ (templates de prompt + metadata)
  • lib/ (auth, clients, validation, redaction, logging)
• tests/
  • unit/
  • integration/
  • fixtures/
• docs/
  • tools.md
  • resources.md
  • prompts.md
  • security.md
  • changelog.md
• examples/ (scripts mínimos que mostram uso local)
• mcp.json ou template de config (se o seu ecossistema o usar)

Esta estrutura mapeia limpo com a forma como capacidades MCP são consumidas: tools/resources/prompts são descobráveis, e a sua lógica de políticas e glue mantém‑se centralizada.

Torne o “Caminho Feliz” Aborrecido

Uma extensão deve comportar‑se de forma previsível mesmo quando o modelo está… criativo.

Aponte para:

• Validação estrita de inputs (rejeitar campos desconhecidos)
• Outputs normalizados (chaves estáveis, tipos estáveis)
• Forma de erro consistente (amigável para máquinas)
• Mensagens claras de “o que fazer a seguir” para falhas recuperáveis

Implementação de Ferramentas: Padrões Práticos que Funcionam

As ferramentas são onde a maioria das extensões MVP ganha o seu valor. Também é onde falham.

Defina Esquemas e Valide no Servidor

Mesmo que o cliente valide, o servidor deve validar de novo. Trate tudo como input não confiável.

Restrições comuns a impor:

• Limites de comprimento de string (nomes, títulos, descrições)
• Restrições de enum (priority: low/medium/high)
• Restrições regex (ticket keys, customer IDs)
• Tamanhos máximos de arrays (para evitar explosões de payload)
• Formatos de datas (ISO 8601 apenas, por sanidade)

Se o seu stack suporta JSON Schema ou um validador tipado, use‑o e falhe rápido.

Retorne Outputs que os Modelos Possam Reutilizar Confiavelmente

Os modelos funcionam melhor com:

• JSON plano sempre que possível
• IDs estáveis
• Campos de estado explícitos
• URLs quando relevantes
• Prosa mínima em campos destinados ao uso programático

Exemplo de formato de saída para uma ferramenta de ação:

• status: success | failed
• id: ID do objeto criado
• url: deep link
• summary: linha curta legível por humanos
• next_actions: array opcional de follow‑ups recomendados

Evite despejar respostas brutas da API a menos que também forneça uma vista normalizada.

Implemente um Envelope de Erro Padrão

Um envelope de erro consistente torna a sua extensão mais fácil de depurar e mais segura de automatizar. Um bom envelope inclui:

• error_code (estável, pesquisável)
• message (legível por humanos)
• details (estruturado, opcional)
• retryable (booleano)
• suggested_fix (sugestão curta)

Quando um modelo encontra um erro, pode decidir se tenta novamente, pede dados em falta ou pára.

Adicione Rate Limits e Timeouts Desde o Início

Mesmo extensões internas podem, acidentalmente, DDoS sistemas internos quando invocadas repetidamente. Ponha guardrails desde o primeiro dia:

• Timeouts por ferramenta (ex.: 10–30 segundos)
• Políticas de retry com backoff (cuidado com ferramentas não idempotentes)
• Rate limits do lado do servidor (por user/token)
• Circuit breakers para falhas em sistemas a jusante

Implementação de Recursos: Faça os Dados Referenciáveis, Não Só Recuperáveis

Os recursos são subvalorizados. Um bom design de recurso ajuda o modelo a citar e navegar informação sem transformar o seu servidor num “fornecedor gigante de texto”.

Prefira Recursos Pequenos e Linkáveis

Em vez de um recurso company_handbook, considere:

• handbook/index
• handbook/{section_id}
• handbook/search?q=...

Isto permite ao modelo puxar apenas o que precisa e reduz o desperdício de tokens.

Inclua Metadata para Rastreabilidade

As respostas de recursos devem incluir:

• Um identificador de recurso estável
• Timestamps de última atualização (se possível)
• Links de origem ou IDs canónicos
• Nível de acesso (public/internal/restricted)
• Trechos opcionais mais um caminho para buscar o conteúdo completo

A rastreabilidade importa para conformidade e para depurar “de onde veio essa resposta?”

Prompts: O Trabalhador Silencioso de Grandes Extensões

Prompts em MCP não são apenas “um texto útil”. São workflows repetíveis que entrega com a sua extensão para que o assistente se comporte de forma consistente.

Templates de prompt úteis incluem:

• “Draft a support reply in our tone”
• “Summarize a ticket for an engineer”
• “Generate release notes from merged PR titles”
• “Convert raw query results into an executive brief”

Um template de prompt forte tem:

• Um papel e objetivo claros
• Inputs obrigatórios
• Um formato de saída estruturado
• Guardrails (“Se faltarem dados, peça‑os”)
• Orientação de estilo que corresponda à sua organização

Prompts também reduzem a tentação de empacotar regras de negócio em nomes de ferramentas. Mantenha regras de negócio em ferramentas e políticas; mantenha orientação de workflow em prompts.

Segurança e Permissões: A Parte que Não se Pode Corrigir Mais Tarde

Se a sua extensão acede a sistemas reais, precisa de segurança real. “É interno” não é uma estratégia.

Escolha um Modelo de Auth: Delegado por Utilizador vs Delegado por Serviço

Duas abordagens comuns:

• User‑delegated: a extensão age em nome do utilizador e respeita as suas permissões. Melhor para ferramentas de produtividade que devem espelhar o acesso do utilizador.
• Service‑delegated: a extensão usa uma conta de serviço com permissões limitadas. Melhor para automação controlada e dashboards em modo read‑only.

User‑delegated tipicamente requer troca de tokens, gestão de sessões e auditoria cuidada. Service‑delegated requer scoping rigoroso e pode necessitar de ferramentas separadas para ações privilegiadas.

Escopo as Ferramentas por Risco

Nem todas as ferramentas são iguais. Pode agrupá‑las por risco e aplicar diferentes portões:

• Read‑only: search, list, retrieve
• Write: create, update
• Destructive: delete, purge, revoke
• Financial/legal: billing, contracts, compliance actions

Para ferramentas de maior risco, adicione requisitos extra:

• Campos de confirmação obrigatórios
• Fluxo de aprovação por duas pessoas (quando aplicável)
• Modo “dry run”
• Limites de taxa apertados
• Logs de auditoria detalhados

Redacione Dados Sensíveis em Ambas as Direções

Redacção não é só sobre logs de saída. Também é sobre respostas.

Se a API a jusante devolver segredos, dados pessoais ou tokens, a sua extensão deve:

• Remover campos sensíveis por defeito
• Fornecer uma representação “mascarada” segura
• Expor detalhe completo apenas com permissão explícita e propósito claro

Registe para Auditorias Sem Filtrar Dados

Uma política de logging prática:

• Registe nome da ferramenta, timestamp, identidade do utilizador, request ID
• Registe hashes ou contagens em vez de conteúdo bruto
• Armazene payloads brutos apenas em sinks de auditoria seguros, se necessário
• Adicione correlation IDs para chamadas a jusante

Isto dá‑lhe rastreabilidade sem transformar o seu sistema de logs numa responsabilidade.

Testar Extensões MCP Personalizadas Como um Profissional

A maioria dos bugs de extensão não são problemas de sintaxe. São problemas de integração e edge‑cases: campos em falta, respostas inesperadas a jusante, concorrência e desajustes de permissões.

Unit Tests: Validar Esquemas e Formas de Erro

Os testes unitários devem cobrir:

• Esquema rejeita campos desconhecidos
• Campos obrigatórios são impostos
• Restrições de enum
• Normalização de saída
• Consistência do envelope de erro

Integration Tests: Use Sandboxes e Fixtures

Para testes de integração:

• Use sandboxes de fornecedores (Jira sandbox, GitHub test org, Stripe test mode)
• Mock APIs a jusante quando sandboxes não estiverem disponíveis
• Grave fixtures para respostas comuns
• Teste timeouts e retries

Uma boa suíte de integração inclui testes de “ensaio de falha”:

• downstream 500
• downstream 429
• auth expirado
• permission denied
• dados parciais retornados

Contract Tests: Mantenha os Contratos de Ferramenta Honestamente

Lembra‑se desses contratos de ferramenta que escreveu? Transforme‑os em testes:

• Input de exemplo deve passar validação
• Output de exemplo deve corresponder ao esquema
• Cenários de erro conhecidos devem produzir error_codes conhecidos

Testes de contrato previnem mudanças silenciosas quando refatoriza.

Documentação que Ajuda Tanto Humanos quanto Modelos

Em repositórios MCP, a documentação não é decorativa. É como outros desenvolvedores e consumidores de ferramentas entendem o que construiu.

Documentação mínima para lançar:

• Quickstart: como correr localmente, env vars necessárias, como ligar um cliente
• Ferramentas referência: inputs/outputs, exemplos, códigos de erro
• Segurança: permissões, scopes, logging de auditoria
• Guia operacional: deployment, monitorização, resposta a incidentes
• Changelog: mudanças user‑facing e migrações

Escreva exemplos como se fossem copiados para produção—porque serão.

Versionamento e Compatibilidade Reversa: Evite Quebras Surpresa

Extensões MCP personalizadas evoluem. A forma mais fácil de perder confiança é mudar outputs sem aviso.

Use Versionamento Semântico com Disciplina

Uma política prática:

• PATCH: correções de bugs, sem mudanças de esquema
• MINOR: mudanças aditivas (novos campos opcionais, novas ferramentas)
• MAJOR: mudanças breaking de esquema, ferramentas renomeadas, campos removidos

Deprécie Antes de Remover

Se precisar remover uma ferramenta ou campo:

• Marque como deprecated na docs
• Mantenha a funcionar por uma janela definida (30–90 dias)
• Adicione avisos nas respostas se apropriado
• Forneça um caminho de migração (“use a ferramenta X com o campo Y em vez disso”)

Isto importa ainda mais quando outros repositórios dependem da sua extensão.

Distribuição e Packaging em Repositórios MCP

A forma de distribuir depende do seu ambiente:

• Servidor MCP open source publicado no GitHub
• Repositório privado na sua organização
• Pacote interno distribuído via um artifact registry
• Imagem de container deployada num cluster

Independentemente do método, trate os releases como produtos.

Checklist de Lançamento

Antes de taggear um release:

• Testes verdes (unit + integration)
• Contratos de ferramenta atualizados
• Docs atualizadas
• Changelog escrito
• Revisão de segurança para novas ferramentas
• Dashboards de monitorização atualizados (se necessário)

Se a sua extensão liga a sistemas críticos, faça um rollout faseado.

Observabilidade e Operações: Mantenha‑na a Correr Quando as Coisas Ficam Estranhas

O modelo não lhe dirá que a sua extensão está instável. Os utilizadores dirão—depois de lhes roubar tempo.

Métricas que Valem a Pena Capturar

Acompanhe pelo menos:

• Contagem de chamadas por ferramenta
• Latência p50/p95/p99
• Taxa de erro por ferramenta e por dependência a jusante
• Contagem de timeouts
• Triggers de rate limit
• Falhas de auth

Adicione dashboards que lhe permitam responder: “A extensão está avariada, ou o sistema a jusante está avariado?”

Tracing de Chamadas a Jusante

Se a sua extensão chama múltiplos serviços, tracing distribuído poupa horas. Mesmo correlation IDs leves ajudam a reconstruir um caminho de falha.

Degradação Segura

Quando uma dependência está em baixo, não devolva apenas erros crípticos. Forneça:

• Uma mensagem clara
• Se o retry poderá funcionar
• Uma alternativa sugerida (modo read‑only, dados em cache)
• Link para página de status se tiver uma

Isto faz a extensão parecer fiável mesmo sob pressão.

Um Checkpoint a Meio Projeto: A Auditoria de “Qualidade da Extensão”

A meio do desenvolvimento, pare e faça uma auditoria com estas perguntas:

• Cada ferramenta consegue ser descrita numa frase?
• Os nomes das ferramentas são consistentes e previsíveis?
• Os esquemas são estritos e validados?
• As saídas estão normalizadas e estáveis?
• Existem códigos de erro que mapeiam para ações?
• As permissões são impostas no servidor?
• Os dados sensíveis são redigidos?
• Temos pelo menos um teste de integração por ferramenta?
• Um novo desenvolvedor entenderia como adicionar uma ferramenta em uma hora?

Se responder “não” a várias, corrija a estrutura agora. Só vai ficar mais difícil depois.

Construir Extensões de Exemplo: Três Blueprints Práticos

Um guia torna‑se real quando consegue imaginar o que está a construir. Aqui estão três blueprints que se mapear bem a casos de uso comuns em repositórios MCP. Cada um pode ser implementado como um pequeno servidor com um punhado de ferramentas e recursos.

1. Internal Docs Navigator

   • Tools: search_docs, get_doc_section, list_collections
   • Resources: docs/{doc_id}, docs/{doc_id}/sections/{section_id}
   • Prompts: “Answer with citations from docs”
   • Key concerns: access control, content chunking, citations, freshness

2. Ticketing and Incident Assistant

   • Tools: create_ticket, update_ticket, link_ticket, summarize_ticket, assign_oncall
   • Resources: tickets/{key}, incidents/{id}
   • Prompts: “Triage and propose next steps”
   • Key concerns: idempotency for creation, role-based permissions, audit logs

3. **Data Warehouse Read-Only Query Server **

   • Tools: run_query_readonly, explain_query, list_tables, describe_table
   • Resources: schemas/{name}, tables/{name}
   • Prompts: “Write safe SQL and summarize results”
   • Key concerns: strict read-only enforcement, query timeouts, result limits, PII masking

Estes blueprints não se destinam a ser copiados linha por linha. Destinam‑se a mostrar como é “pequeno mas completo” em repositórios MCP.

Lidar com Idempotência, Concorrência e “Chamadas Duplas”

Sistemas de invocação de ferramentas podem desencadear chamadas repetidas para a mesma intenção—às vezes devido a retries, às vezes devido a re‑pedidos do utilizador, às vezes devido a reconexões de cliente.

Adicione Chaves de Idempotência para Operações de Escrita

Para ferramentas que criam ou mutam dados, aceite um idempotency_key opcional:

• Se for usado o mesmo key de novo, devolva o resultado original.
• Guarde registos de idempotência por um TTL razoável.
• Documente quanto tempo as chaves permanecem válidas.

Isto evita tickets duplicados, faturas duplicadas, convites de utilizador duplicados—falhas clássicas de extensão.

Proteja Contra Falhas Parciais

Se a sua ferramenta executa múltiplos passos:

• Prefira transações se a jusante as suportar.
• Caso contrário, desenhe passos de compensação (rollback) ou um fluxo de “resume”.
• Retorne IDs intermédios para que humanos possam investigar.

O objetivo não é ser perfeito; é ser recuperável.

Tornar as Extensões “Amigas do Modelo” sem Ficar Dependente do Modelo

É tentador adaptar tudo ao comportamento de um modelo. Resista. Construa extensões que sejam agnósticas ao cliente e agnósticas ao modelo.

Mantenha Nomes de Ferramentas e Campos Literais

Evite nomes criativos e campos sobrecarregados. Use termos que o seu negócio já usa:

• customer_id em vez de cid
• invoice_number em vez de inv
• priority com um enum conhecido

Nomenclatura literal melhora a correção e torna as suas docs pesquisáveis.

Coloque Regras de Negócio no Servidor, Não no Prompt

Prompts ajudam modelos a seguir regras, mas a aplicação pertence ao código:

• verificações de permissão
• aprovações obrigatórias
• transições permitidas
• constraints de política (ex.: “nunca consultar estas tabelas”)

Se uma regra importa, aplique‑a. Prompts são orientação, não segurança.

Um Fluxo Prático para Adicionar uma Nova Ferramenta

Quando um stakeholder pergunta “Podemos adicionar uma ferramenta que faz X?”, siga um fluxo repetível.

1. Clarifique o trabalho
   Qual é o objetivo real do utilizador? Qual sistema é a fonte da verdade?

2. Rascunhe o contrato da ferramenta
   Inputs/outputs, erros, scope de permissão.

3. Revise para segurança
   Pode apagar dados? Pode expor PII? Pode ser abusada?

4. Implemente com validação
   Esquema estrito, outputs normalizados, envelope de erro.

5. Adicione testes
   Unit tests para esquema e erros; integration tests para a chamada a jusante.

6. Documente e lance
   Atualize docs de ferramentas, exemplos e changelog. Tagueie um release.

Este fluxo é aborrecido—no bom sentido. Reduz o “conhecimento tribal” e faz o desenvolvimento de extensões escalar.

Erros Comuns em Extensões MCP Personalizadas (E Como Evitá‑los)

Erro: Expor uma Ferramenta “run_any_command”

Uma ferramenta que executa comandos arbitrários ou queries é um convite ao caos. Mesmo “SQL arbitrário” em read‑only pode vazar dados sensíveis se perder uma tabela ou view.

Correção:

• Forneça queries limitadas ou ferramentas de relatório predefinidas
• Aplique allowlists
• Adicione limites de linhas e mascaramento de colunas

Erro: Retornar Texto Ilimitado

Devolver blobs massivos prejudica desempenho e aumenta a probabilidade de o modelo perder detalhes importantes.

Correção:

• Retorne sumários mais uma forma de fetchar mais
• Pagine
• Faça chunking intencional de recursos

Erro: Mensagens de Erro Fracas

“Algo correu mal” não é aceitável quando um modelo está a orquestrar chamadas.

Correção:

• Padronize códigos de erro
• Inclua correções sugeridas
• Marque erros retryable claramente

Erro: Sem Plano Operacional

Se ninguém possui a monitorização e on‑call, a extensão degradará silenciosamente.

Correção:

• Adicione dashboards básicos
• Defina propriedade
• Documente passos de incidente

Publicar e Manter a Sua Extensão ao Longo do Tempo

Uma extensão MCP não está “pronta” quando funciona uma vez. A fase de manutenção é onde se constrói confiança.

Trate Mudanças de API a Jusante como Risco de Primeira Classe

Se integrar com vendors SaaS:

• Acompanhe os changelogs deles
• Trave versões de API quando possível
• Adicione testes de integração que corram regularmente
• Inclua notas de compatibilidade nas suas docs

Mantenha um Ciclo Rápido de Feedback com Utilizadores

Observe como as pessoas realmente usam a extensão:

• Quais ferramentas são mais usadas?
• Quais ferramentas geram mais erros?
• O que os utilizadores perguntam repetidamente que poderia tornar‑se um template de prompt?
• Onde as pessoas são forçadas a passos manuais?

Muitas vezes a melhor “nova funcionalidade” não é uma nova ferramenta—são melhores defaults, outputs mais claros ou um workflow mais seguro.

Estabeleça Guidelines de Contribuição no Seu Repositório MCP

Se múltiplas equipas vão adicionar ferramentas, precisa de padrões:

• Convenções de nomeação
• Estilo de esquema
• Formato do envelope de erro
• Requisitos de logging e redacção
• Requisitos de testes
• Checklist de revisão de segurança

Um curto CONTRIBUTING.md e um template de PR podem evitar semanas de limpeza depois.

Fechar o Ciclo: A Sua Extensão Deve Parecer Confiável

Uma ótima extensão MCP parece um colega de trabalho fiável: clara sobre o que consegue fazer, honesta sobre o que não consegue e consistente sob pressão. Construa pequeno, valide tudo, registe responsavelmente, documente sem descanso e versione como se outras pessoas dependessem de si—porque vão.

External Links

MCP developer guide | Visual Studio Code Extension API Build an MCP App - Model Context Protocol Build your MCP server – Apps SDK | OpenAI Developers Making your own MCP server in VS Code | Microsoft Learn Visual Studio Code + Model Context Protocol (MCP) Servers Getting …

External References

• Internal Docs Navigator
• and Incident Assistant
• Read Only Query Server