Pular para o conteúdo principal

Construa & Conecte o Seu Primeiro Servidor MCP

Avançado

Vamos expor uma ferramenta personalizada ao Claude construindo um pequeno servidor MCP e conectando-o. Vamos mantê-lo minimalista para que a conexão fique clara — depois você substitui pela sua lógica real.

O que vamos construir​

Um servidor stdio com uma ferramenta, word_count, que o Claude pode chamar. O mesmo padrão escala para "consultar meu banco de dados", "abrir um ticket", etc.

Passo 1 — O servidor​

server.py (Python; uma versão em TypeScript está em scaffolds de MCP):

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("text-tools")

@mcp.tool()
def word_count(text: str) -> int:
    """Count the words in a piece of text."""
    return len(text.split())

if __name__ == "__main__":
    mcp.run()  # stdio transport

Passo 2 — Declare-o​

Adicione ao .mcp.json na raiz do seu repositório:

{ "mcpServers": {
  "text-tools": { "command": "python", "args": ["server.py"] }
} }

Passo 3 — Conecte & teste​

Inicie o Claude Code no repositório. Pergunte: "Use o servidor text-tools para contar as palavras em: 'the quick brown fox'." O Claude deve chamar word_count e reportar 4. Se ele não conseguir ver a ferramenta, verifique se o servidor inicia corretamente por conta própria e se o caminho no .mcp.json está certo.

Passo 4 — Torne-o real​

Substitua word_count pela sua capacidade de verdade — uma consulta a banco de dados, uma chamada a uma API interna, uma operação de arquivo. Adicione validação de entrada e retorne erros como resultados.

Checklist de segurança​

:::warning Um servidor é código + acesso

  • Privilégio mínimo — apenas os dados/ações de que ele precisa (Protegendo Agentes).
  • Valide as entradas que o modelo envia.
  • Dados não confiáveis que ele retorna podem carregar injeção de prompt.
  • Revise qualquer servidor de terceiros antes de conectá-lo. :::

Próximos passos​