Como criar um servidor MCP do zero e conectar a um agente de IA

Conectar um agente de inteligência artificial a fontes de dados externas não depende de integrações específicas para cada modelo. Ao construir um servidor MCP (Model Context Protocol), você estabelece um padrão universal de comunicação que funciona como uma porta USB. Escreva o código do conector uma vez. Depois disso, qualquer IA conseguirá descobrir e utilizar essas ferramentas por conta própria.

Para ver esse conceito operando na tela, escreveremos um servidor funcional do zero, integrado aos dados públicos do Google Trends no BigQuery. Com o apoio do Google Agent Development Kit (ADK), o agente lerá perguntas em português e decidirá qual consulta executar. O processo inteiro acontece no navegador, sem instalação local.

Você define os contornos da aplicação. A infraestrutura determina a segurança e os tetos de custo das operações, enquanto o modelo apenas consome os dados por meio de funções simples em Python. O desenvolvedor foca na regra de negócio, e o protocolo resolve a comunicação.

O que vamos construir: a arquitetura do servidor

Vamos expor ferramentas que consultam os dados públicos do Google Trends no BigQuery. O objetivo é criar um agente capaz de responder a perguntas em português sobre tendências de busca em tempo real, como “quais são os cinco termos mais buscados no Brasil agora?”.

Essa base de dados atende a um propósito específico neste projeto. Um modelo de linguagem não sabe quais são as buscas mais populares do dia, pois essa informação muda a cada hora. A ferramenta de consulta se torna a única fonte confiável para a resposta. É exatamente nesse cenário de dependência de dados externos e dinâmicos que o protocolo prova o seu valor prático.

Antes de escrever o código, entenda como as responsabilidades operam. A arquitetura de integração se divide em três papéis complementares:

A anatomia de um servidor MCP

O servidor que expõe essas consultas não exige um sistema complexo. Três linhas de código são suficientes para estruturá-lo e prepará-lo para se comunicar com um agente.

A classe FastMCP lida com o protocolo por baixo dos panos. Ela gerencia o handshake, a listagem de ferramentas disponíveis, a execução das funções e o enquadramento de todas as mensagens no padrão JSON-RPC. Sem a necessidade de configurar essa infraestrutura manualmente, o desenvolvedor se concentra em uma única tarefa: declarar as ferramentas.

 from google.cloud import bigquery from mcp.server.fastmcp import FastMCP mcp = FastMCP("analista-bigquery") 

Para transformar uma função Python em uma ferramenta MCP, basta adicionar o decorador @mcp.tool(). Esse comando traduz a lógica local para a linguagem do protocolo, criando um contrato claro entre o servidor e a inteligência artificial. 

Veja a nossa primeira ferramenta, que retorna os termos mais buscados em um país:

@mcp.tool() def termos_em_alta(pais: str = "BR", limite: int = 10) -> str:  """Retorna os termos mais buscados no Google em um país.  Use quando perguntarem o que está em alta, em tendência, ou o que as  pessoas estão buscando no momento em determinado país.  Args:  pais: Código ISO do país com duas letras, por exemplo 'BR', 'PT', 'US'.  limite: Quantidade de termos a retornar.  """  # ... a lógica da consulta vem aqui 

A docstring assume o papel de interface principal neste modelo. O agente de IA nunca lê a implementação interna da função. A decisão de usar — ou ignorar — uma ferramenta depende exclusivamente da clareza da descrição fornecida. 

Um texto bem estruturado explica não apenas o que a ferramenta faz, mas, principalmente, em quais situações específicas ela deve ser acionada. 

Segurança e custo desde a primeira linha

Permitir que uma inteligência artificial monte consultas para um banco de dados exige controles de risco definidos antes da execução. O próprio código do servidor atua como barreira, garantindo que o agente não tenha acesso irrestrito aos dados, mas apenas uma janela de visualização com formato e limites rigorosos.

O primeiro mecanismo de controle é o teto de custo por requisição. O BigQuery calcula o volume de dados que uma consulta precisa varrer antes de iniciá-la. Ao definir o parâmetro maximum_bytes_billed, qualquer operação que ultrapasse esse limite é barrada previamente. Esse bloqueio impede que uma pergunta mal formulada pelo usuário ou um pico de acessos simultâneos gere uma fatura inesperada.

MAX_BYTES = 1_000_000_000 # Teto de custo: a query é recusada se exceder. configuracao = bigquery.QueryJobConfig(  maximum_bytes_billed=MAX_BYTES,  query_parameters=parametros, ) 

A segunda camada de proteção aplica o princípio do menor privilégio (least privilege) usando consultas parametrizadas. Em vez de concatenar diretamente as escolhas do agente — como o código do país — na String SQL, o código injeta esses valores em query_parameters. 

As consultas mantêm uma estrutura fixa e imutável. A IA apenas preenche espaços predefinidos. Essa configuração neutraliza riscos de injeção de SQL, garantindo que um modelo interpretando linguagem natural não comprometa a integridade do banco. 

O servidor completo

O código final do servidor reúne a estrutura completa necessária em um único arquivo chamado servidor_analista.py. Enquanto duas funções mapeiam a estrutura do banco de dados, as outras duas executam buscas por tendências específicas. Essa divisão garante que o agente consiga inspecionar tabelas e consultar termos sem depender de SQL escrito manualmente.

from google.cloud import bigquery from mcp.server.fastmcp import FastMCP mcp = FastMCP("analista-bigquery") DATASET = "bigquery-public-data.google_trends" MAX_BYTES = 1_000_000_000 # Teto de custo por consulta. FILTRO_PARTICAO = "refresh_date = DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY)" def _executar(sql, parametros=None):  """Executa uma query com limite de bytes e formata o resultado."""  configuracao = bigquery.QueryJobConfig(  maximum_bytes_billed=MAX_BYTES,  query_parameters=parametros or [],  )  try:  resultado = bigquery.Client().query(sql, job_config=configuracao).result()  except Exception as erro:  return f"Erro ao consultar o BigQuery: {erro}"  linhas = [dict(linha) for linha in resultado]  if not linhas:  return "Nenhum resultado encontrado."  return "\n".join(str(linha) for linha in linhas) @mcp.tool() def listar_tabelas() -> str:  """Lista as tabelas disponíveis no dataset de tendências de busca.   Use quando o usuário perguntar o que existe ou o que é possível consultar.  """   try:  tabelas = bigquery.Client().list_tables(DATASET)  return "Tabelas disponíveis: " + ", ".join(t.table_id for t in tabelas)  except Exception as erro:  return f"Erro ao listar tabelas: {erro}" @mcp.tool() def termos_em_alta(pais: str = "BR", limite: int = 10) -> str:  """Retorna os termos mais buscados no Google em um país.  Use quando perguntarem o que está em alta, em tendência, ou o que as  pessoas estão buscando no momento em determinado país.  Args:  pais: Código ISO do país com duas letras, por exemplo 'BR', 'PT', 'US'.  limite: Quantidade de termos a retornar.  """  codigo = pais.upper().strip()  sql = f"""  SELECT DISTINCT term, rank  FROM `{DATASET}.international_top_terms`  WHERE {FILTRO_PARTICAO}  AND country_code = @pais  ORDER BY rank ASC  LIMIT @limite  """  parametros = [  bigquery.ScalarQueryParameter("pais", "STRING", codigo),  bigquery.ScalarQueryParameter("limite", "INT64", limite),  ]  return _executar(sql, parametros) @mcp.tool() def termos_em_ascensao(pais: str = "BR", limite: int = 10) -> str:  """Retorna os termos que mais CRESCERAM em buscas em um país.   Diferente de termos_em_alta (os mais buscados no total), esta mostra  o que está subindo mais rápido. Use quando perguntarem o que está  crescendo, bombando, viralizando ou em ascensão.  Args:  pais: Código ISO do país com duas letras, por exemplo 'BR', 'PT', 'US'.  limite: Quantidade de termos a retornar.  """  codigo = pais.upper().strip()  sql = f"""  SELECT DISTINCT term, rank  FROM `{DATASET}.international_top_rising_terms`  WHERE {FILTRO_PARTICAO}  AND country_code = @pais  ORDER BY rank ASC  LIMIT @limite  """  parametros = [  bigquery.ScalarQueryParameter("pais", "STRING", codigo),  bigquery.ScalarQueryParameter("limite", "INT64", limite),  ]  return _executar(sql, parametros) if __name__ == "__main__":  mcp.run() 

A eficiência dessa implementação depende de dois ajustes nas instruções SQL. O uso de SELECT DISTINCT impede a repetição do mesmo termo, algo comum na base do Google Trends, que replica palavras por região e semana. Otimizar consultas reduz custos. Além disso, o filtro na coluna de particionamento refresh_date restringe a varredura às métricas do dia anterior. Essa escolha reduz o volume processado de vários gigabytes para poucos megabytes, seguindo a recomendação para esse conjunto de dados.

A instrução final mcp.run() ativa o servidor no transporte stdio. Essa chamada inicia a escuta ativa de mensagens JSON-RPC, transformando o script em um serviço pronto para receber e responder comandos do cliente.

Como testar o protocolo MCP antes de integrar o agente de IA

Você deve validar o servidor MCP isoladamente criando um cliente mínimo em Python antes de conectar qualquer modelo de linguagem. Esse teste confirma que o handshake, a descoberta de ferramentas e a execução de comandos funcionam via mensagens JSON-RPC sem depender da IA.

from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client import sys async def testar_protocolo():  parametros = StdioServerParameters(  command=sys.executable, args=["servidor_analista.py"]  ) async with stdio_client(parametros) as (leitura, escrita):  async with ClientSession(leitura, escrita) as sessao:  # 1. O handshake  info = await sessao.initialize()  print(f"Servidor: {info.serverInfo.name}")  # 2. A descoberta de ferramentas  ferramentas = (await sessao.list_tools()).tools  for ferramenta in ferramentas:  print(f" - {ferramenta.name}")  # 3. A execução de uma ferramenta  retorno = await sessao.call_tool("listar_tabelas", {})  print(retorno.content[0].text)  await testar_protocolo() 

O script de teste valida a comunicação completa em três etapas ordenadas:

1. Execute o método initialize para realizar o handshake, etapa em que cliente e servidor negociam a versão do protocolo e trocam capacidades.
2. Chame a função list_tools para realizar a descoberta dinâmica e listar todas as ferramentas expostas pelo servidor.
3. Invoque o comando call_tool informando a ferramenta desejada (como “listar_tabelas“) para receber os dados formatados.

Perceba o ponto principal desta etapa: nenhum modelo de linguagem participa deste teste. Trata-se da troca direta de dados padronizados entre dois programas. O protocolo opera independentemente. A Inteligência Artificial entra na arquitetura posteriormente, atuando como um cliente que consome o servidor pronto.

Como conectar o agente de IA ao servidor usando o Google ADK

Para integrar a inteligência artificial às suas ferramentas, o Google Agent Development Kit (ADK) automatiza o processo fornecendo um cliente MCP embutido. O componente McpToolset assume as obrigações que estruturamos manualmente na etapa de testes. Ele executa o handshake, a descoberta de recursos e o acionamento dos comandos sem intervenção manual.

from google.adk.agents import Agent from google.adk.tools.mcp_tool.mcp_toolset import McpToolset from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams from mcp import StdioServerParameters import sys # O McpToolset é o CLIENTE MCP, embutido no ADK. toolset = McpToolset(  connection_params=StdioConnectionParams(  server_params=StdioServerParameters(  command=sys.executable,  args=["servidor_analista.py"],  )  ) ) analista = Agent(  name="analista_dados",  model="gemini-2.0-flash",  instruction=(  "Você é um analista de dados objetivo e didático. "  "Responda sempre em português do Brasil. "  "Use as ferramentas para consultar tendências de busca e "  "interprete os números, não devolva apenas dados crus."  ),  tools=[toolset], ) 

Nenhuma linha do servidor original precisou de alteração para essa nova fase. O exato arquivo que conversou com um script isolado agora alimenta as decisões autônomas do modelo Gemini. É assim que a arquitetura resolve o problema de múltiplas conexões na prática. Você desenvolve o acesso ao banco de dados uma única vez. A partir daí, qualquer aplicação compatível com o protocolo consome a estrutura pronta.

Como o modelo escolhe e executa as ferramentas sozinho

A inteligência da arquitetura se revela quando o modelo converte uma pergunta em linguagem natural em uma execução direta de código. Ninguém precisa escrever SQL ou apontar qual função acionar. O agente lê a intenção do usuário, avalia as descrições disponíveis no servidor e toma a decisão correta.

Para visualizar esse processo, o ADK utiliza um orquestrador chamado Runner. Ao interceptar os eventos desse fluxo contínuo, você consegue enxergar exatamente o que acontece nos bastidores de cada chamada:

async for evento in runner.run_async(  user_id=USUARIO, session_id=sessao, new_message=conteudo ):  for parte in evento.content.parts:  if parte.function_call:  print(f"[MCP] chamou: {parte.function_call.name}"  f"({dict(parte.function_call.args)})")  if parte.function_response:  print(f"[MCP] retornou: {parte.function_response.response}") 

Esse laço de repetição captura e imprime os argumentos de cada função ativada pelo sistema. Por exemplo, se você digitar a pergunta “quais são os 5 termos mais buscados no Brasil agora?”, o retorno na tela comprova o mapeamento autônomo:

VOCÊ: Quais são os 5 termos mais buscados no Brasil agora?  [MCP] chamou: termos_em_alta({'pais': 'BR', 'limite': 5})  [MCP] retornou: {'term': 'seleção brasileira', 'rank': 1} ...  ANALISTA: Os cinco termos mais buscados no Brasil neste momento são... 

A inteligência artificial compreende que a palavra “Brasil” equivale ao código de país “BR” e que “cinco termos” define o limite matemático da operação. Com esses dados preenchidos, ela executa a ferramenta termos_em_alta sem intervenção humana.

A prova definitiva de que a descrição funciona como a verdadeira interface do sistema ocorre quando existem duas opções parecidas. Considere o cenário com as funções termos_em_alta (volume total) e termos_em_ascensao (crescimento rápido). 

Ao receber o comando “o que está crescendo mais rápido no Brasil?”, o agente escolhe a segunda alternativa em vez da primeira. Ele toma essa decisão lendo e interpretando os textos de orientação redigidos nas docstrings do servidor.

De dados públicos a integrações internas 

Substituir o acesso ao Google Trends por um ambiente corporativo encerra a teoria e inicia a aplicação real. Você testou o comportamento dinâmico do agente de IA com dados públicos, garantindo tetos de custo e proteção básica. O restante da estrutura de código não muda.

A partir daqui, mapeie as suas próprias fontes de dados para estruturar um servidor interno. Converta as tabelas do seu repositório de documentos, o histórico de chamados no sistema de suporte ou os painéis de vendas em ferramentas MCP. Escreva descrições precisas em cada docstring para instruir a inteligência artificial, defina restrições rígidas de consulta, e veja as equipes consultarem registros da empresa com as próprias palavras.

Como a SantoDigital resolve a aplicação prática da inteligência artificial

A SantoDigital constrói e gerencia o ambiente de inteligência artificial da sua empresa garantindo que nenhuma informação interna vaze para a internet. O time avalia o cenário do negócio e entrega a solução operando perfeitamente. 

Isso significa treinar colaboradores para o uso de assistentes diários ou estruturar painéis de análise de dados sob medida. A sua equipe foca no que traz receita. O planejamento e a configuração da nuvem ficam com os especialistas.

Veja o que você pode delegar hoje para acelerar a sua operação:

1. Crie assistentes internos seguros: a equipe configura ferramentas de consulta conectadas apenas à sua base de dados, mantendo o controle total dos acessos dentro da infraestrutura do Google.
2. Integre aplicações na rotina de escritório: profissionais capacitam seus funcionários para extrair o máximo do Gemini na geração de resumos e fluxos, garantindo a adoção real da tecnologia pelos usuários finais.
3. Desenvolva interfaces do zero: um esquadrão técnico assume o projeto da concepção à entrega, conectando regras de negócio e bancos de dados em sistemas acessados diretamente pelo navegador.
4. Terceirize o monitoramento contínuo: consultores analisam o desempenho das automações diariamente, atuando ativamente na correção de problemas e na otimização do ambiente para evitar cobranças indevidas.

O passo inicial descarta qualquer complexidade técnica. Reúna as tarefas mais manuais da sua empresa e apresente aos consultores. Eles desenham a rota exata para transformar o seu gargalo operacional em uma estrutura rápida e rentável.

Perguntas frequentes sobre servidores MCP e agentes de IA

Referências

MODEL CONTEXT PROTOCOL. Documentação oficial do Model Context Protocol. [S. l.], 2025. Disponível em: https://modelcontextprotocol.io. Acesso em: 16 set. 2026.

MODEL CONTEXT PROTOCOL. Guia de construção de servidores MCP. [S. l.], 2025. Disponível em: https://modelcontextprotocol.io/docs/develop/build-server. Acesso em: 16 set. 2026.

MODEL CONTEXT PROTOCOL. SDK do MCP para Python. [S. l.]: GitHub, 2025. Disponível em: https://github.com/modelcontextprotocol/python-sdk. Acesso em: 16 set. 2026.

MODEL CONTEXT PROTOCOL. MCP Inspector: ferramenta oficial de testes. [S. l.], 2025. Disponível em: https://modelcontextprotocol.io/docs/tools/inspector. Acesso em: 16 set. 2026.

GOOGLE. Google Agent Development Kit (ADK). [S. l.]: GitHub, 2025. Disponível em: https://google.github.io/adk-docs. Acesso em: 16 set. 2026.

GOOGLE. Integração de MCP no ADK. [S. l.]: GitHub, 2025. Disponível em: https://google.github.io/adk-docs/tools/mcp-tools. Acesso em: 16 set. 2026.

GOOGLE. Servidores MCP oficiais do Google. [S. l.]: GitHub, 2025. Disponível em: https://github.com/google/mcp. Acesso em: 16 set. 2026.

GOOGLE. Dataset público Google Trends no BigQuery. [S. l.]: Google Cloud Marketplace, 2025. Disponível em: console.cloud.google.com/marketplace/product/bigquery-public-datasets/google-search-trends. Acesso em: 16 set. 2026.

Crédito da imagem: Magnific

Pedro Campos

Engenheiro de Machine Learning

Ver todos artigos

Engenheiro de Machine Learning na SantoDigital, Pedro Campos atua no time de Inovação em ML desenvolvendo soluções personalizadas em nuvem para clientes de diversos segmentos. Com sólida experiência em Python, TensorFlow e Vertex AI, une conhecimento técnico em Machine Learning e IA Generativa a uma base robusta em Ciência de Dados e Cloud Computing. É 2x Google Cloud Certified (Digital Leader e Associate Cloud Engineer), credenciais que reforçam sua expertise em ambientes de computação em nuvem e sua busca constante por excelência técnica.