Skip to Content

Endpoint MCP

O IronFlock é um servidor MCP. O Claude, e qualquer outro cliente que fale o Model Context Protocol, pode listar os seus projetos, ler os seus dispositivos, apps e dados, e agir sobre eles com as ferramentas que o IronFlock oferece, dentro do que a sua chave de API permite. O endpoint faz parte do mesmo serviço de API que a API REST e usa as mesmas chaves de API.

Endereço e Autenticação

URL na nuvem IronFlockhttps://api.ironflock.com/mcp
URL em um appliancehttps://api. seguido do domínio do appliance, depois /mcp, assim que o appliance roda o serviço IronFlock API
TransporteStreamable HTTP
AutenticaçãoAuthorization: Bearer <your API key>

Crie a chave de API no Studio como descrito em Criando uma Chave de API. Toda requisição leva a chave. Uma requisição sem chave, ou com uma que não é válida (excluída, expirada ou de outro IronFlock), é respondida com HTTP 401. O servidor não oferece login pelo navegador (OAuth): a chave é a única forma de entrar.

O servidor não mantém sessões. Cada requisição é respondida por si só, então um cliente pode se conectar, desconectar e reconectar livremente. Ele responde a cada requisição com um corpo JSON e não tem stream de eventos para escutar.

Conectar o Claude

Você mesmo insere a chave, nas configurações do próprio Claude. Nunca a cole em um chat.

Claude Code

O Claude Code se conecta pelo plugin ironflock, que declara o servidor MCP do IronFlock. Ele funciona no terminal, nas extensões de IDE e na aba Code do app Claude para desktop.

  1. Adicione o marketplace e instale o plugin em uma sessão do Claude Code:

    /plugin marketplace add IronFlock/agent-skills /plugin install ironflock@ironflock
  2. A instalação abre um diálogo com duas configurações. IronFlock API address é https://api.ironflock.com para a nuvem, e https://api. seguido do domínio do appliance para um appliance, nos dois casos sem /mcp e sem barra no final. IronFlock API key é a chave do Studio. O Claude Code a guarda no armazenamento seguro de credenciais do sistema, não em um arquivo de configurações.

  3. Reinicie o Claude Code. /mcp passa então a listar o servidor plugin:ironflock:ironflock como conectado.

Altere as configurações depois com /plugin configure ironflock@ironflock e reinicie o Claude Code. Enquanto a chave não estiver definida, o servidor não inicia. Uma instalação a partir de um shell (claude plugin install) não abre o diálogo, então conclua-a com /plugin configure ironflock@ironflock em uma sessão. Desenvolva com o Claude Code descreve os plugins e as suas skills.

Claude na Web, no Desktop e no Celular, e Cowork

A conexão própria do plugin funciona apenas no Claude Code. No chat do app Claude e no Cowork, você adiciona o IronFlock uma vez como conector personalizado, com a chave como header de requisição. Headers de requisição em conectores personalizados são um beta disponível para um grupo limitado de organizações. Se o diálogo abaixo não tiver a seção Request headers, a sua organização ainda não o tem, e o IronFlock não pode ser conectado ali por enquanto: o Claude Code funciona.

  1. Abra Customize > Connectors, escolha Add e depois Add custom connector.
  2. Insira o nome IronFlock e a URL do servidor https://api.ironflock.com/mcp.
  3. Defina Authentication como No sign-in.
  4. Em Request headers, adicione o header Authorization com o valor Bearer seguido da sua chave: a palavra Bearer, um espaço, depois a chave. Sem Bearer , o IronFlock recusa a requisição.
  5. Escolha Add.

Nos planos Team e Enterprise, um owner adiciona o conector em Organization settings > Connectors, Add e depois Custom; os headers de requisição podem estar em Advanced. Todos que usam esse conector agem com a única chave que o owner inseriu, então dê a ela apenas as permissões e os projetos que todos eles podem usar.

Os headers de requisição de um conector não podem ser editados: para trocar a chave, remova o conector e adicione-o de novo. O conector se conecta a partir dos servidores da Anthropic, então o endereço precisa ser alcançável pela internet. Esse é o caso da nuvem. Um appliance que só a rede da sua empresa alcança normalmente não pode ser conectado ali, enquanto o Claude Code em um computador dessa rede pode.

Outros Clientes MCP

Qualquer cliente que suporte Streamable HTTP e um header de requisição se conecta com a URL e o header Authorization: Bearer <your API key>. Mantenha a chave fora de arquivos que você compartilha ou faz commit.

Verificar a Conexão

Peça ao Claude para listar os seus projetos IronFlock e depois os dispositivos de um deles. O Claude chama list_projects e list_devices, que apenas leem.

Ferramentas

O servidor oferece 33 ferramentas nestas áreas. A maioria delas trabalha em um projeto e recebe o seu swarm_key, que list_projects fornece. Uma ferramenta que altera ou exclui algo é marcada como tal, para que clientes como o Claude possam perguntar a você antes de chamá-la.

Projetos

FerramentaPermissãoO que faz
list_projectsdevices:readLista os projetos em que a chave pode trabalhar

Dispositivos

FerramentaPermissãoO que faz
list_devicesdevices:readLista os dispositivos de um projeto, os apps instalados em cada um, se eles rodam e se o dispositivo está online
create_devicedevices:writeCria um dispositivo no projeto e responde a sua chave e o seu nome
delete_devicedevices:writeExclui permanentemente um dispositivo do projeto

Apps em um Projeto

FerramentaPermissãoO que faz
list_project_appsapps:readLista os apps instalados no projeto e em quantos dispositivos cada um roda
check_app_statusapps:readMostra se um app roda nos seus dispositivos e se os seus dados chegam
install_appapps:writeInstala um app da store no projeto e, opcionalmente, em dispositivos
set_app_stateapps:writeInicia ou para um app instalado em dispositivos
update_appapps:writeAtualiza um app instalado para a sua release mais nova
uninstall_appapps:writeRemove um app de dispositivos, ou do projeto inteiro

App Store e Custos

FerramentaPermissãoO que faz
search_appsapps:readPesquisa a app store por capacidade e retorna os apps correspondentes com os seus preços
get_app_detailsapps:readLê a descrição, o README e o preço de um a três apps da store
get_install_quoteapps:readConsulta quanto custaria instalar um app e o que o impediria
estimate_project_costapps:readEstima o custo anual da configuração de um projeto; nada é comprado
sync_app_to_storeapps:writeSomente em um appliance: copia um app da store da nuvem IronFlock para a store própria do appliance

Dados

FerramentaPermissãoO que faz
get_schemadata:readDescreve o banco de dados do projeto: as suas tabelas, views e colunas
execute_sqldata:readExecuta uma consulta SELECT somente leitura no banco de dados do projeto
list_dashboardsdata:readLista os dashboards do projeto
list_app_filesdata:readLista e pesquisa os arquivos que um app guarda no projeto
read_app_filedata:readLê um arquivo que um app guarda: texto, uma imagem ou outro arquivo
save_transformdata:writeCria ou substitui uma transformação personalizada que mantém um valor derivado ao vivo para boards
delete_transformdata:writeExclui permanentemente uma transformação personalizada

Alarmes

FerramentaPermissãoO que faz
list_alarmsalarms:readLista os alarmes do projeto com o seu estado, gatilhos e destinatários
create_alarmalarms:writeCria um alarme que observa a tabela de dados de um app
update_alarmalarms:writeAltera o gatilho ou os destinatários de um alarme, ou o pausa e o retoma
delete_alarmalarms:writeExclui permanentemente um alarme e o seu histórico

Logs e Log de Auditoria

FerramentaPermissãoO que faz
get_app_logslogs:readLê a saída de log do próprio app nos dispositivos em que ele roda
get_device_logslogs:readLê o que o próprio dispositivo tem feito: apps, downloads, disco, rede, atualizações do agente
query_audit_loglogs:readExecuta uma consulta somente leitura no log de auditoria: quem alterou o projeto, os seus dispositivos, grupos e apps, e quando
get_appliance_healthdevices:readSomente em um appliance: verifica o estado dos serviços de plataforma do próprio appliance, disco, memória, licença e atualizações
get_appliance_logslogs:readSomente em um appliance: lê o log de uma parte da plataforma do appliance

Ferramentas dos Apps

Os apps trazem ferramentas próprias com os seus agentes de IA: funções do app que rodam em um dispositivo, como ler o estado de uma máquina ou alterar uma configuração. Duas ferramentas chegam até elas.

FerramentaPermissãoO que faz
list_app_toolsapptools:callLista as ferramentas de um app instalado, com os seus argumentos e as instruções dos agentes do app
call_app_toolapptools:callExecuta uma delas em um dispositivo do projeto

call_app_tool roda em um dispositivo, e uma ferramenta de um app pode alterar coisas ali. O dispositivo precisa ser um dos dispositivos do projeto que o dono da chave pode ver, e o dono precisa do direito de usar os dados do app, como ao operar o app a partir do seu board. O app recebe exatamente os argumentos fornecidos e nada mais. Apenas as ferramentas da release instalada são listadas, não as da versão de desenvolvimento de um app. Os textos de uma ferramenta são escritos pelo desenvolvedor do app e são cortados em um comprimento fixo.

Permissões

Cada ferramenta precisa da única permissão mostrada nas tabelas acima. O servidor oferece a um cliente apenas as ferramentas que a chave pode usar, e recusa qualquer outra ferramenta como se ela não existisse. Seja o que for que a chave permita, uma ferramenta nunca faz mais do que o dono da chave pode fazer no IronFlock. releases:publish não tem ferramenta: ela serve para as operações REST que fazem o build de releases. Veja Permissões para todas elas, e Criando uma Chave de API para saber como escolhê-las no Studio.

Uma chave restrita a projetos vê apenas esses projetos. A uma chave restrita a um app são oferecidas apenas as ferramentas que agem para um app, portanto não list_projects. A nenhuma das duas são oferecidas as ferramentas que vão além de um projeto: query_audit_log, cuja consulta pode citar ativos de qualquer projeto que o dono pode ler, as duas ferramentas de appliance, que não pertencem a nenhum projeto, e sync_app_to_store, que altera a store do appliance para todos.

Algumas ferramentas têm regras extras:

  • install_app recebe a resposta de get_install_quote que foi mostrada a você, e não instala nada quando o preço ou qualquer outra coisa dessa cotação mudou desde então. Instalar um app pago custa dinheiro.
  • set_app_state e update_app alteram no máximo 10 dispositivos em uma chamada.
  • create_device responde a chave e o nome do novo dispositivo, e nunca o seu arquivo de configuração, que contém as credenciais do dispositivo. Baixe o arquivo no Studio, nas configurações do dispositivo, em Manutenção > Arquivo de Configuração do Dispositivo > Baixar arquivo de configuração, ou configure o dispositivo na máquina com ironflock agent install --project <project> --name <name>, que cria o dispositivo e mantém o arquivo na máquina (Login e gerenciamento de dispositivos).
  • Um projeto salva uma transformação personalizada de cada vez. Um segundo save_transform enquanto o primeiro roda é recusado.
  • Uma conta pode executar query_audit_log uma vez de cada vez e seis vezes por minuto, porque o banco de dados por trás dele é compartilhado.
  • Uma alteração que não termina dentro do tempo da sua chamada ainda pode ser feita. O resultado diz isso, e a ferramenta não a repete.

Resultados

Um resultado é JSON, como conteúdo estruturado e como o mesmo JSON em um bloco de texto. Uma lista longa é cortada para caber em 50.000 caracteres, e o seu membro cut diz quantas entradas ficaram de fora e como continuar a leitura. Imagens (PNG, JPEG, GIF e WebP) vêm como imagens, e outros arquivos, como um PDF, como recursos incorporados com o seu tipo de mídia.

Quando uma ferramenta não consegue fazer o que foi pedido, o seu resultado é marcado como erro e diz o porquê em uma frase, por exemplo que um projeto não existe ou que a plataforma não respondeu a tempo.

Limites

Estes são os padrões, por chave de API:

Limite
Requisições120 por minuto, em rajadas de até 30
Requisições abertas ao mesmo tempo8
Corpo da requisição1.114.112 bytes: 1 MiB de argumentos e a mensagem em volta deles
Uma chamada de ferramenta90 segundos
Uma consulta ao banco de dados30 segundos; execute_sql responde 100 linhas, a menos que você peça mais, no máximo 1.000
Um resultado50.000 caracteres; o resultado de call_app_tool é cortado em 45.000

Erros

RespostaSignificadoO que fazer
401A chave está ausente, digitada errada ou cortada, excluída, expirada, ou é de outro IronFlock. Em um conector, pode estar faltando Bearer Crie uma nova chave no Studio do IronFlock a que você se conecta e insira-a de novo
404 em /mcp/mcp aparece duas vezes no endereço, ou a instância ainda não oferece o endpoint, como um appliance que não roda o serviço IronFlock APICorrija o endereço; caso contrário, use a nuvem
405GET e DELETE em /mcp: o servidor não tem stream de eventos nem sessão para encerrarUse POST
413O corpo da requisição é grande demaisEnvie menos em uma chamada
429A chave fez requisições demais, ou tem requisições demais abertas ao mesmo tempo. O header Retry-After diz quantos segundos esperarEspere esse tempo e continue com menos chamadas ao mesmo tempo
503A plataforma não está disponível no momento, ou o serviço está sendo encerradoTente de novo em um minuto
504A plataforma não respondeu a tempoTente de novo em um minuto

Uma ferramenta que não consegue fazer o que foi pedido não responde com um erro HTTP: o seu resultado é marcado como erro e explica em uma frase o que deu errado.

Mantenha Sua Chave Segura

  • Nunca cole uma chave em um chat. Se você fez isso, ela faz parte dessa conversa: exclua a chave no Studio, crie uma nova e insira-a nas configurações.
  • O Studio mostra uma nova chave apenas uma vez, quando você a cria. Guarde-a imediatamente nas configurações do cliente.
  • Use uma chave para cada lugar que a usa, para poder excluir uma sem quebrar as outras, e exclua as chaves que você não usa mais. Uma chave vale por um ano.
  • Dê a uma chave apenas as permissões e os projetos de que o Claude precisa: uma chave que pode fazer Tudo em Todos os meus projetos deixa o Claude fazer tudo o que você pode fazer no IronFlock. Ferramentas que alteram ou excluem algo são marcadas como tal, para que clientes como o Claude possam perguntar a você antes. Leia o que o Claude está prestes a alterar antes de concordar.
  • Um conector compartilhado por uma organização age com uma chave para todos os seus usuários. Use a chave de uma conta que possa ver apenas o que todos eles podem ver.
Last updated on