O Model Context Protocol (MCP) permite conectar ferramentas e serviços externos por meio de um protocolo padronizado, o que possibilita integrar APIs e serviços diretamente aos seus workflows. Com o MCP, você amplia o que o Seeyu Agent Studio faz adicionando integrações próprias que funcionam junto com seus agentes e workflows.
O que é MCP?
O MCP é um padrão aberto que permite a assistentes de IA se conectarem com segurança a fontes de dados e ferramentas externas. Ele oferece uma forma padronizada de:
- Conectar a bancos de dados, APIs e sistemas de arquivos
- Acessar dados em tempo real de serviços externos
- Executar ferramentas e scripts próprios
- Manter acesso seguro e controlado a recursos externos
Adicionando um servidor MCP como ferramenta
Servidores MCP oferecem coleções de ferramentas que seus agentes podem usar.
Para adicionar um:
- Vá em Settings → MCP Tools
- Clique em Add para abrir o modal de configuração
- Informe um Server Name e uma Server URL
- Adicione os Headers necessários (por exemplo, chaves de API)
- Clique em Add MCP para salvar
Você também pode configurar servidores MCP direto pela barra de ferramentas de um block Agent, para uma configuração rápida.
Opções de configuração do servidor
| Campo | Descrição |
|---|---|
| Name | Nome de exibição do servidor |
| URL | O endpoint do servidor MCP |
| Transport | Atualmente suporta streamable-http |
| Headers | Pares chave-valor para autenticação ou headers próprios |
| Timeout | Tempo limite de conexão em milissegundos (padrão: 30.000) |
Variáveis de ambiente na configuração
URLs de servidor e headers suportam substituição de variáveis de ambiente com a sintaxe {{VAR_NAME}}. Isso mantém valores sensíveis, como chaves de API, fora da configuração do servidor.
URL: https://api.example.com/mcp
Authorization: Bearer {{MCP_API_TOKEN}}Quando você digita {{ nos campos de URL ou header, aparece um dropdown com as variáveis de ambiente disponíveis no workspace.
Quando um secret salvo é substituído com sucesso desse jeito, as ocorrências exatas do valor são mascaradas nos traces armazenados de chamadas de ferramentas MCP. A URL ou o valor real do header continua chegando ao servidor MCP sem alteração. Veja Proteção do log de execução para o escopo exato e as limitações.
Testes e validação
Clique em Test Connection antes de salvar para verificar se o servidor está acessível e descobrir as ferramentas disponíveis. A resposta do teste mostra quantas ferramentas foram encontradas e a versão do protocolo.
Depois de salvar, cada servidor exibe as ferramentas disponíveis com nomes de parâmetros, tipos e indicação de obrigatoriedade. Se as ferramentas de um servidor mudarem (por exemplo, após uma atualização do servidor), clique em Refresh para buscar os schemas mais recentes. Isso atualiza automaticamente todos os blocks Agent que usam essas ferramentas.
Selos de validação de ferramentas aparecem nos servidores com problemas — por exemplo, se uma ferramenta foi removida do servidor mas continua referenciada em um workflow. Clique no selo para ver quais workflows são afetados.
Lista de domínios permitidos
Instalações com auto-hospedagem podem restringir quais domínios de servidor MCP são permitidos definindo a variável de ambiente ALLOWED_MCP_DOMAINS (lista separada por vírgulas). Quando ela está definida, só é possível adicionar servidores em domínios aprovados. Quando não está definida, todos os domínios são permitidos.
Atualizar ferramentas
Para atualizar automaticamente uma ferramenta MCP que já está em uso por um agente, vá em Settings → MCP Tools, abra os detalhes do servidor e clique em Refresh. Isso busca os schemas mais recentes das ferramentas e atualiza automaticamente, com as novas definições de parâmetros, todos os blocks Agent que as usam.
Usando ferramentas MCP em agentes
Depois que os servidores MCP estão configurados, as ferramentas deles ficam disponíveis nos seus blocks Agent:
- Abra um block Agent
- Na seção Tools, clique em Add tool…
- Em MCP Servers, clique em um servidor para ver as ferramentas dele
- Selecione ferramentas individuais ou escolha Use all N tools para adicionar todas as ferramentas daquele servidor
- O agente já pode acessar essas ferramentas durante a execução
Se você ainda não configurou um servidor, clique em Add MCP Server no topo do dropdown para abrir o modal de configuração sem sair do block.
Block MCP Tool independente
Para um controle mais granular, use o block MCP Tool dedicado para executar ferramentas MCP específicas:
O block MCP Tool permite:
- Executar diretamente qualquer ferramenta MCP configurada
- Passar parâmetros específicos para a ferramenta
- Usar a saída da ferramenta nos passos seguintes do workflow
- Encadear várias ferramentas MCP
Quando usar MCP Tool e quando usar Agent
| Agent com ferramentas MCP | Block MCP Tool | |
|---|---|---|
| Execução | A IA decide quais ferramentas chamar | Determinística — executa a ferramenta que você escolher |
| Parâmetros | A IA escolhe em tempo de execução | Você define explicitamente |
| Melhor para | Fluxos dinâmicos e conversacionais | Passos estruturados e repetíveis |
| Raciocínio | Lida com lógica complexa de vários passos | Uma ferramenta, uma chamada |
Permissões necessárias
Os recursos de MCP exigem permissões específicas de workspace:
| Ação | Permissão necessária |
|---|---|
| Criar ou atualizar servidores MCP | Write ou Admin |
| Excluir servidores MCP | Admin |
| Usar ferramentas MCP em agentes | Write ou Admin |
| Ver as ferramentas MCP disponíveis | Read, Write ou Admin |
| Executar blocks MCP Tool | Read, Write ou Admin |
Casos de uso comuns
Integração com bancos de dados
Conecte a bancos de dados para consultar, inserir ou atualizar dados dentro dos seus workflows.
Integrações com APIs
Acesse APIs externas e serviços web que não têm integração nativa no Seeyu Agent Studio.
Acesso a sistemas de arquivos
Leia, escreva e manipule arquivos em sistemas de arquivos locais ou remotos.
Lógica de negócio própria
Execute scripts ou ferramentas específicos das necessidades da sua organização.
Acesso a dados em tempo real
Busque dados ao vivo de sistemas externos durante a execução do workflow.
Considerações de segurança
- Servidores MCP executam com as permissões de quem os configurou
- Sempre verifique a origem de um servidor MCP antes de instalá-lo
- Use variáveis de ambiente para dados sensíveis de configuração
- Revise o que um servidor MCP é capaz de fazer antes de dar acesso a ele aos agentes
Solução de problemas
O servidor MCP não aparece
- Verifique se a configuração do servidor está correta
- Confirme que você tem as permissões necessárias
- Garanta que o servidor MCP está em execução e acessível
Falhas na execução de ferramentas
- Verifique se os parâmetros da ferramenta estão formatados corretamente
- Consulte os logs do servidor MCP em busca de mensagens de erro
- Garanta que a autenticação necessária está configurada
Erros de permissão
- Confirme seu nível de permissão no workspace
- Verifique se o servidor MCP exige autenticação adicional
- Confirme que o servidor está configurado corretamente para o seu workspace