MCP

Guia de introdução ao MCP Starter Kit: faça a ponte segura entre sua API de backend e agentes de IA

O MCP Starter Kit é ideal para desenvolvedores com uma API de backend já existente que queiram montar rapidamente um servidor MCP seguro chamável por Claude ou ChatGPT, mas exige condições de hospedagem com TLS e o preenchimento manual do .env e a implementação das ferramentas.

Official source · GitHub - fdhhhdjd/MCP-STARTER-KIT: Build a secure, production-ready MCP server for any project

Install

npm install && npm run build

MCP Starter Kit é um scaffold independente de projeto para montar um servidor MCP (Model Context Protocol) seguro e pronto para produção em qualquer projeto: cada ferramenta mapeia para um endpoint de backend, a autenticação usa API key + scopes, e conecta agentes de IA (Claude Desktop/Web, ChatGPT ou agentes próprios) à sua API de backend. Se você só quer experimentar ferramentas prontas, ele não é adequado: exige que você tenha uma API de backend, possa hospedar o serviço e aceite o fluxo de build e deploy.

Para quem é

  • Desenvolvedores que querem que sua API de backend seja chamada com segurança por agentes como Claude e ChatGPT.
  • Equipes que precisam de uma ferramenta por endpoint, com permissões controladas por API key + scopes; somente leitura por padrão, a menos que um scope de escrita seja adicionado explicitamente.
  • Cenários que precisam tanto de acesso online (Streamable HTTP, multi-cliente) quanto de Claude Desktop (stdio), ou de duas opções de autenticação: OAuth 2.0 stateless (PKCE S256) ou API key via header.
  • Não é adequado para: usuários sem API de backend, sem condições de hospedagem com TLS, ou que não queiram fazer nenhuma alteração de código e configuração. A documentação oficial não detalha custos de hospedagem nem requisitos do ambiente de execução; essas incógnitas devem ser verificadas por você.

Primeira tentativa em 3 minutos

Recomenda-se começar construindo e conectando o próprio scaffold (a chamada real a endpoints acontece depois que você configurar as ferramentas):

  1. Pré-requisitos: Node/npm instalados; um domínio com TLS disponível (o serviço deve ficar atrás de TLS, no caminho /mcp).
  2. Siga o caminho de templates do README: entre em templates/, renomeie gitignore para .gitignore, substitua __PROJECT__ pelo nome do seu projeto, preencha o .env e adicione suas ferramentas em src/server.ts.
  3. Execute o comando de build oficial:
npm install && npm run build
  1. Hospede atrás de TLS (caminho /mcp), depois conecte a partir do Claude Desktop usando o mcp-remote e faça uma verificação (a inicialização da conexão é uma ação de baixo risco; a key é validada no backend durante o initialize):
npx -y mcp-remote https://<domain>/mcp --header "Authorization: Bearer <key>"

Sinal de sucesso: o cliente conclui o initialize e a validação da key no backend passa (a documentação oficial afirma que isso bloqueia requisições não autenticadas já na inicialização). No Claude Web, use um conector personalizado com URL /mcp e header x-api-key. Observação: <domain> e <key> nos comandos acima são valores reais que você deve substituir; preencher as chaves no .env é uma escrita de estado local, não uma operação somente leitura.

Casos de uso

  1. Chamar endpoints somente leitura do seu backend pelo Claude Desktop: após concluir o build e a hospedagem com TLS pelo caminho principal acima, conecte ao /mcp no Claude Desktop via mcp-remote com uma Bearer key. Como o padrão é somente leitura, as chamadas não disparam operações de escrita no backend a menos que você adicione um scope de escrita explicitamente — esse é o comportamento declarado oficialmente, mas não significa risco zero; a chave ainda é validada no backend e passa pelo mcp-remote.
  2. Conectar o mesmo serviço pelo conector personalizado do Claude Web: no Claude Web, configure um conector personalizado com a URL /mcp e o header x-api-key. É possível confirmar até o estabelecimento da conexão; o formato de saída de uma ferramenta específica depende de como você a implementar em src/server.ts — as evidências oficiais não trazem exemplos concretos de ferramentas, então não é possível prever mais.

Limites de uso

  • Natureza de leitura/escrita: o template é somente leitura por padrão; a capacidade de escrita exige adicionar um scope explicitamente. Operações de escrita são escritas remotas — confirme os efeitos colaterais antes de executar.
  • Credenciais: autenticação por API key (ou, opcionalmente, OAuth 2.0 stateless com PKCE S256); o .env precisa ser preenchido e constitui estado sensível local.
  • Logs: os logs de auditoria vão para o stderr, com o stdout reservado para JSON-RPC; atenção à diferença de canais ao depurar.
  • Limites dos mecanismos de segurança: a key é validada no initialize para bloquear usos não autenticados; o padrão somente leitura e a validação no initialize significam que não há execução de escrita e que a chave é verificada — não que não haja acesso à rede ou que não existam outros limites de privacidade.
  • Informações não confirmadas: as evidências oficiais não cobrem o formato detalhado dos arquivos de configuração de cada cliente, os requisitos das plataformas de hospedagem, nem exemplos concretos de implementação de endpoints/ferramentas; consulte o repositório e confirme antes do primeiro uso.