Projetando CLIs para agentes, não para humanos — Pedro Lopez, Airbyte

Ver no idioma original →

Autoria: AI Engineer · Assistir no YouTube

Vídeo de autoria do canal indicado, não da IANIA; todos os direitos pertencem ao criador. Transcrição, resumo e tradução gerados automaticamente; o conteúdo no idioma original é preservado na versão em idioma original.

Idioma original: inglês

Vídeo original: Designing CLIs for Agents, Not Humans — Pedro Lopez, Airbyte · Canal: AI Engineer · 17:35 · Assistir no YouTube

Tópicos: Agentes de IA, Dados, bancos de dados e embeddings, Ferramentas de desenvolvimento com IA

Resumo

Pedro Lopez apresenta como a Airbyte oferece acesso ao seu context store por meio de MCP e CLI, além de compartilhar aprendizados de implementação. Para MCP, recomenda manter poucas ferramentas, usar descoberta progressiva e considerar as diferenças de suporte entre clientes, especialmente para autenticação e elicitation. Para CLIs usadas por agentes, destaca entradas e saídas em JSON, comandos consistentes, skills para descoberta e autenticação não interativa. A escolha entre MCP e CLI depende do usuário e da tarefa: MCP facilita o uso e a prototipagem, enquanto CLI favorece tarefas longas e o uso de pipes.

Pontos-chave

• A Airbyte posiciona seu context store como uma camada de dados e ações para agentes, acessível por SDK, interface web, MCP e CLI.
• As interfaces MCP e CLI devem ser camadas finas sobre a plataforma e as APIs compartilhadas, em vez de reimplementar a plataforma.
• No MCP, manter pequeno o número de ferramentas e usar descoberta progressiva ajuda a limitar o contexto e melhorar o desempenho.
• A autenticação OAuth favorece a experiência de conexão no MCP, mas sessões longas exigem ciclos de vida próprios.
• O suporte a recursos da especificação MCP varia entre clientes; por isso, elicitation por URL pode não funcionar em todos eles.
• Para CLIs voltadas a agentes, JSON na entrada e na saída facilita construir consultas complexas e processar resultados com ferramentas como jq.
• Uma estrutura consistente de comandos e skills distribuídas com a CLI ajudam agentes a descobrir e usar os recursos corretamente.
• CLIs devem evitar prompts interativos e permitir configurar credenciais por flags, variáveis de ambiente ou arquivos de configuração.
• MCP é útil para usuários menos técnicos e protótipos rápidos; CLI é mais adequada a usuários técnicos, tarefas longas e fluxos com pipes.

Capítulos

Início	Capítulo	Resumo
00:01	Contexto e interfaces da Airbyte	Pedro apresenta a evolução da Airbyte e explica o context store e as interfaces disponíveis para acessá-lo.
03:53	MCP: uso e aprendizados	A demonstração do MCP dá lugar a recomendações sobre ferramentas, autenticação OAuth e limitações de elicitation entre clientes.
09:58	Projetando uma CLI para agentes	A apresentação aborda JSON, consistência dos comandos, skills e autenticação não interativa como escolhas importantes para CLIs usadas por agentes.
15:55	Quando escolher MCP ou CLI	Pedro compara as limitações e vantagens de cada interface e recomenda MCP para acesso simples e CLI para tarefas técnicas e longas.

Citações

Interfaces finas e unificadas para nossa plataforma, não reimplementações da plataforma. — 02:50

Projete essas CLIs pensando nos agentes. — 11:07

Se você vê agentes cometendo o mesmo erro repetidamente, considere tornar isso parte do seu contrato. — 13:18

Acho que ambas têm seu lugar. — 17:04

Conceitos e entidades

• Airbyte (empresa): Empresa que oferece um context store e interfaces para conectar dados e ações a agentes.
• Pedro Lopez (pessoa): Engenheiro de software da Airbyte que apresenta as decisões de projeto para MCP e CLI.
• MCP (conceito): Interface que permite conectar agentes a ferramentas e consultar ou executar ações sobre dados.
• CLI (ferramenta): Interface de linha de comando projetada na apresentação para ser usada por agentes e usuários técnicos.
• context store (conceito): Índice otimizado para busca que reúne dados de diferentes serviços para consulta por agentes.
• OAuth (conceito): Mecanismo de autenticação usado para conectar clientes ao servidor MCP e autorizar o acesso.
• elicitation (conceito): Recurso do MCP para solicitar informações ao usuário, cujo suporte varia entre clientes.
• skills (conceito): Instruções distribuídas com a CLI que ajudam agentes a descobrir e usar seus comandos.
• jq (ferramenta): Ferramenta citada para selecionar e transformar partes de saídas JSON em pipes.

Tradução completa (pt-BR)

00:01 [música] Olá, pessoal. Meu nome é Pedro. Sou engenheiro de software na Airbyte. Hoje vamos falar sobre como criamos nosso MCP para agents e nossa CLI. Antes de entrar nos detalhes de tudo isso, queria dar um pouco de contexto sobre o que fazemos na Airbyte e como tudo isso se encaixa

00:33 no nosso produto. A Airbyte existe há algum tempo. Começamos como o padrão open source para movimentação de dados, conectando todas as ferramentas SaaS que você talvez use, como Zendesk, Stripe, GitHub etc., aos seus pipelines de análise de dados. Agora estamos usando essa mesma experiência e evoluímos para ser a camada de dados e ações para seus agents de IA. Fazemos isso oferecendo um produto para agents que tem

01:05 o que chamamos de loja de contexto, que se conecta a todas aquelas ferramentas que mencionei antes e fica entre seus agents para fornecer um índice otimizado para busca de todos os seus dados, que podem ser consultados com mais eficiência pelos seus agents. Assim, você pode obter informações sobre todos esses registros, contatos e outras coisas que talvez tenha em todas essas ferramentas e reuni-los de maneira fácil por meio da nossa loja de contexto. Nosso objetivo é tornar

01:40 os dados disponíveis e acionáveis em todos os lugares. Temos algumas interfaces diferentes pelas quais você pode acessar essa loja de contexto. Uma delas é nosso SDK, mais útil se você estiver criando seus próprios agents e ferramentas. Outra é nossa interface do usuário, uma maneira rápida de usar o produto pelo nosso aplicativo web. E, por fim, aquilo em que vamos nos concentrar nesta palestra: nosso MCP e nossa CLI, que são uma maneira fácil de disponibilizar isso em agents existentes, como ChatGPT e Claude. Então,

02:15 o que exatamente disponibilizamos por meio dessas interfaces? Três coisas principais. A primeira é a capacidade de gerenciar todos os recursos essenciais do nosso produto: organizações, workspaces e conectores. Todas essas interfaces devem permitir que você interaja com eles. A segunda, muito importante, é poder autenticar nesses serviços de terceiros que mencionei antes, de maneira segura e sem expor suas credenciais aos agents de IA. E a terceira é perguntar e agir. Queremos disponibilizar a capacidade de buscar

02:50 na loja de contexto, ler e escrever, e realizar ações em todos esses sistemas. Queremos que todas as nossas interfaces atendam a esses três recursos. A estrutura do MCP e da CLI é a de interfaces unificadas e leves para nossa plataforma, não reimplementações dela. Assim, a maior parte da camada superficial dessas interfaces é de apresentação: você executa um comando

03:22 e chama a plataforma para formatar os resultados de alguma maneira. Tudo fica sobre nossa plataforma e nossas APIs compartilhadas. Como fazemos deploy com frequência — nossa plataforma muda mais de dez vezes por dia —, queremos manter essas interfaces atualizadas. Uma parte importante disso também são as especificações de API open source, que servem como fonte da verdade sobre como se conectar às nossas APIs. Muitas dessas interfaces são criadas com base nessas

03:53 especificações. Certo, vamos falar dessas interfaces. Vamos começar pelo MCP. O MCP é ótimo para usuários que talvez não tenham conhecimentos técnicos. No nosso caso, é excelente para quem quer conectar seus dados diretamente ao ChatGPT ou ao Claude com facilidade. E o legal é que eles vêm muito bem empacotados e são fáceis de instalar. Por exemplo, aqui está nossa página no aplicativo do ChatGPT, na loja oficial deles. Também

04:29 temos um aplicativo para o da Anthropic, cuja aprovação ainda está pendente. Se houver alguém da Anthropic por aí que queira nos aprovar… Mas, mesmo que você não esteja nesses marketplaces, a instalação é bem simples para o usuário final. Basta fornecer a URL do MCP hospedado e é possível se conectar rapidamente. Certo, vamos ver um exemplo. Este é nosso MCP em ação. Aqui, pergunto: quais conectores eu

05:01 tenho disponíveis? Ele responde: “Tenho quatro conectores configurados neste workspace”. Depois, posso fazer perguntas sobre meus dados, como: “Mostre cinco clientes pagantes com chamados de suporte no Zendesk”. Neste momento, ele está consultando todos os conectores que temos e buscando na loja de contexto as informações que pedi. Depois, combina essas informações do Zendesk e do Stripe para formular uma resposta. Certo, aí está. Ele cruzou os dados do Zendesk e do Stripe

05:33 e voltou com cinco pessoas que têm chamados de suporte em aberto. Legal. Vamos falar de algumas lições que aprendemos ao criar este MCP e de coisas que você talvez queira ter em mente se estiver fazendo algo parecido. Uma decisão que tomamos após algumas tentativas foi manter pequeno o número de ferramentas. Para a parte de execução do conector, quando você busca esses dados, expomos ou usamos apenas duas ferramentas principais. Uma delas descreve o

06:06 conector para obter o esquema de como consultar as informações; a segunda é a ferramenta de execução, que pode ler, escrever e excluir registros. No outro extremo, como nos conectamos a tantos conectores diferentes e cada um deles tem entidades e ações diferentes que podem ser realizadas, poderíamos ter exposto uma ferramenta de MCP para cada um. Mas descobrimos que é melhor manter o escopo restrito e usar a descoberta progressiva de todos os recursos disponíveis no conector. Além disso,

06:39 limitar bastante a quantidade de contexto incluída nas descrições dessas ferramentas ajuda muito no desempenho do servidor MCP. Segundo: OAuth é o caminho. Isso se refere à maneira de autenticar o próprio servidor MCP. Este é um exemplo da Anthropic: você clica em um botão para se conectar, e isso inicia nosso fluxo de OAuth. Você pode entrar na Airbyte, aceitar as permissões e então

07:10 tudo fica configurado com todos os conectores que você vinculou. Tecnicamente, é possível usar outros mecanismos de autenticação com MCP, mas você terá bastante dificuldade se usar autenticação Bearer ou algo do tipo, porque a especificação dá muita ênfase ao OAuth e todos os principais clientes, pelo menos, estão adotando OAuth como uma experiência melhor para instalar esse conector. Este é um exemplo do cadastro de conector personalizado da Anthropic, em que não há nenhuma maneira

07:47 de inserir um token Bearer ou algo parecido. Tudo usa OAuth por padrão. Isso é muito importante. E os usuários realmente esperam ter sessões duradouras por meio desses servidores MCP. Ao contrário de um aplicativo web, no qual talvez não seja um problema ter que entrar novamente algumas vezes, os usuários esperam usar MCPs mais como um aplicativo móvel, sem precisar pensar na autenticação. Ele simplesmente fica disponível sempre que quiserem usá-lo. Por isso, há algumas coisas a considerar

08:23 ao implementar OAuth: manter sessões longas offline, armazenadas separadamente do aplicativo web e com seu próprio ciclo de vida. Legal. Elicitation, por outro lado, não é o caminho. Vou explicar o que é elicitation, mas uma parte importante do servidor MCP que mencionei é que você precisa poder conectar suas ferramentas e fornecer credenciais de maneira segura. Para fazer isso, basicamente, quando você pergunta: “Como faço para me conectar”

08:53 para o HubSpot? Geramos um link que você acessa, e um widget aparece, permitindo selecionar quais entidades quer conectar e redirecionar para o HubSpot para passar pelo fluxo de OAuth. Tecnicamente, a especificação do MCP tem algo que permite exibir esse tipo de URL e processar essas informações, chamado elicitation. É uma forma de solicitar informações ao usuário. Durante muito tempo, isso

09:27 só tinha o modo de formulário de elicitation, que não é aplicável a dados sensíveis, como credenciais de uma API. Mais recentemente, o modo de URL de elicitation passou a existir e é muito parecido com o que estamos fazendo. Mas o problema é o suporte entre os clientes MCP. Esse é um tema importante ao trabalhar com MCP: embora exista uma especificação, os recursos compatíveis variam bastante de um cliente para outro.

09:58 Então, este é um exemplo do Claude Desktop, que simplesmente me diz: “Ei, não tenho suporte ao modo de URL de elicitation. Não consigo fazer isso.” Por isso, tivemos que voltar a fazer do nosso jeito, sem usar a especificação para esse tipo de coisa. Certo, vamos falar um pouco sobre a CLI. Se os MCPs são fáceis para esses usuários não técnicos, a CLI é uma espécie de contraparte mais técnica — talvez mais poderosa em alguns aspectos, como veremos. Este é o mesmo exemplo que vimos antes, mas desta vez

10:30 com o MCP — ou melhor, com a CLI —, em que perguntamos quais conectores estão disponíveis. Desta vez, ela carrega uma skill que explica como funciona a CLI e, depois, usa a própria CLI para consultar informações. Recebemos a lista de conectores. Em seguida, pedimos: “Mostre cinco clientes pagantes que tenham chamados de suporte no Zendesk.” O mesmo de antes. Desta vez, ela consegue usar a CLI para consultar o armazenamento de contexto, agregar esses dados e, por fim, deve retornar um resultado. Certo. Então, temos aqueles mesmos

11:07 cinco usuários. No que diz respeito ao design da CLI, acho importante ter em mente que ela deve ser projetada pensando nos agents. Algumas coisas que podem ser úteis para os usuários ao criar uma CLI podem se tornar obstáculos para os agents. Vamos falar um pouco mais sobre isso. A primeira decisão de design que tomamos foi aceitar JSON como entrada e retornar JSON como saída. Para os humanos, é muito conveniente especificar

11:41 um monte de flags para trabalhar com CLIs. Mas, quando se trata dessas entradas mais complexas que precisam ser construídas para fazer consultas, os agents são muito bons em trabalhar com JSON. Eles conseguem construí-las de uma forma muito mais direta e com menos tentativa e erro do que usando essas flags. E, na saída, o JSON também facilita lidar com respostas mais longas

12:14 e aproveitar um dos principais recursos das CLIs: você tem esse sistema Unix com pipes, que permitem redirecionar a saída para diferentes programas. Por exemplo, você pode usar o jq para selecionar certos itens da saída e reduzi-la. Então, o JSON realmente libera muitos desses recursos. Segundo: a consistência é fundamental. Deve ser muito óbvio para os agents como fazer algo em todos

12:47 os recursos que você está expondo. Se você estruturou sua CLI com um substantivo seguido de um verbo — neste exemplo, “connectors list” e “connectors create” —, garanta que, ao implementar comandos da CLI para workspaces, eles sigam o mesmo formato. “workspace list” é outro comando que temos. É muito importante que os agents saibam a forma correta de fazer as coisas e consigam

13:18 descobrir como fazer as coisas da forma certa sem precisar ler um monte de documentação. Outro ponto interessante: se você perceber que os agents cometem o mesmo erro repetidamente, chamando o comando errado várias vezes, considere tornar esse padrão parte do seu contrato. Deixe muito fácil para os agents encontrarem a forma certa de usar as coisas, porque isso geralmente significa que algo não está tão claro quanto deveria estar no contrato da sua API, na sua CLI, se os agents continuam cometendo o mesmo tipo de erro.

13:50 Terceiro: as skills vêm junto com a ferramenta de CLI. As skills são indispensáveis ao trabalhar com CLIs, porque, se uma CLI estiver instalada, como um agent vai saber que ela existe? Isso ajuda muito a descobrir quais ferramentas estão disponíveis. As skills também ajudam a usar a ferramenta de forma eficaz. Temos uma skill que é exibida e cuja descrição pode aparecer sempre que você perguntar algo sobre

14:22 conectores. Ela sabe que deve apresentar essa CLI e invocá-la. A forma como você estrutura a skill também é algo que precisa ser pensado. Você não quer colocar informação demais na skill e sobrecarregar o contexto. As skills podem ser divididas em referências: você pode ter uma skill principal que aponta para outros arquivos em um diretório de skill, os quais podem detalhar os diferentes comandos. Isso realmente ajuda a reduzir a quantidade de contexto

14:53 que você carrega e aproveita a capacidade de descoberta progressiva desses agents. Legal. Outro ponto interessante sobre autenticação: ela foi interessante no lado do MCP, e também é interessante de outras formas para CLIs, porque não podemos presumir que haverá um humano disponível para interagir com esses prompts. Quando agents invocam CLIs, elas não podem simplesmente ficar esperando que você digite um prompt na CLI. Você precisa

15:24 expor as informações por meio de flags ou, no caso das credenciais, de variáveis de ambiente e arquivos de configuração, para que tudo possa ser configurado fora de banda e você não precise esperar por isso ao invocar a CLI. E eu diria que, além da autenticação, isso é algo geral: muitas CLIs feitas para humanos recebem um comando e ficam esperando, pedindo informações. Isso não permite que os agents as usem adequadamente.

15:55 Eles simplesmente acabam ficando presos. Legal. Então, entre CLI e MCPs, qual é melhor? Bem, cada um tem suas próprias vantagens e desvantagens. Com o MCP, a especificação não é implementada de maneira uniforme. Além disso, esses provedores decidem implementar várias limitações que não estão na especificação. Por exemplo, o Claude tem um limite de 2 kilobytes para as descrições de servidores e chamadas de ferramentas. Há também um limite para a duração das ferramentas. Então, é mais difícil executar processos de longa duração por meio do

16:30 MCP. E há outros tipos de limitações que eles introduziram. Já na CLI, uma das vantagens do MCP é que você pode ter um servidor MCP hospedado que está sempre atualizado. Não é bem assim com a CLI: é preciso pensar mais em controle de versões. É mais difícil manter os pacotes atualizados com todos esses novos recursos. Embora os limites possam ser restritivos no lado do MCP, não ter nenhum desses limites na CLI, entre as ferramentas e as chamadas da CLI, pode fazer

17:04 as coisas darem errado e levar a loops contínuos que fazem o agent ficar girando em círculos. Então, acho que cada um tem seu lugar. Os MCPs são ótimos para usuários não técnicos, para prototipar coisas rapidamente, criar relatórios pontuais e até aproveitar o ecossistema MCP para fazer as coisas conversarem entre si. Já a CLI é melhor para usuários mais técnicos, tarefas de maior duração e talvez saídas muito longas que você precisa

17:35 Aproveitar esses recursos que o Unix e os pipes oferecem, permitindo redirecionar a saída para um arquivo. Você pode usar tail ou head nessa saída. É aí que a CLI realmente começa a brilhar. Certo, era basicamente isso que eu tinha. Temos um estande ali da Airbyte que você deveria visitar — e venha trabalhar conosco. Obrigado.

Transcrição original

[00:01] [music] Hello everybody. Uh my name is Pedro. I’m a software engineer at Airbet. And today we’re going to be talking about how we built our agent MCP and our CLI. Um, and before we go into the nitty-gritty of all of that, um, I wanted to give a bit of context on what we do at Airbet and how all of this kind

[00:33] of fits into, uh, our product. So, Airbite’s been around for a while. Um, we started as the open- source uh, standard for data movement. Um, connecting all of your SAS tools that you might be using like Zenesk, Stripe, uh, GitHub, etc. to um, your data analytics pipelines. And now we’re using that same expertise and have evolved to being the data and action layer for your AI agents. Um, and we do that by offering a or agent product um that has

[01:05] what we call the context store which connects to all of those tools that that I mentioned before and sits in between your agents um to provide a search optimized index of all of your data um that is able to be more efficiently queried by your agents. So, you’re able to gather information about all of these um records and and and contacts and stuff that you might have in these all all these tools and join them together in an easy way uh through our contact store. And so, our goal is that we want to make

[01:40] data available and actionable everywhere. And so, we have a couple different interfaces by which you can access this context store. Um, one is our SDK, which is more usable if you are uh building your own agents and your tools. Um, our UI, which is, um, just a quick way that you can use it through our web app. Uh, and then what we’re going to be focusing on in this talk, which is our MCP and our CLI, which is um, a way to easily make that um, available within existing uh, agents like Chad GBT um, and and Claude. So

[02:15] what exactly are we exposing through these interfaces? Um three main things. One is the ability to manage all of the the core resources of our product to our organizations workspaces and connectors. Um and so all these interfaces should let you uh interact with that. Second um super important is be able to authenticate those thirdparty services that I mentioned about earlier um and do so in a way that’s secure and doesn’t expose your credentials uh to to the AI agents. And third um ask and act. So we want to expose the ability to search

[02:50] across the context store uh be able to read and write uh take action on all those systems. Um, and so we want all of our interfaces to be able to span across these uh three capabilities. Um, so the MCP and the CLI, the way the way that we’ve structured things is that they are thin unified interfaces into our platform, not reimplementations of the platform. So most of the surface layer of these uh interfaces are presentational where you take a command

[03:22] uh and you call the platform and format the results in some way. Uh and everything kind of sits on top of our shared platform and APIs. Um and because we want to we deploy a lot, you know, our our platform changes like over 10 times a day, we want to keep these things up to date as we go. And so a big part of this as well is open a open API uh specs as a source of truth for how to connect to to our APIs. And a lot of those interfaces um are built on top of

[03:53] uh those specs. Okay, so let’s go into these interfaces. Let’s start with let’s start with the the MCP. And so MCPs are really great for users that might not be technical. Um, and in our case, it’s great for those users that just want to plug their data straight into Chat DBT or Claude in an easy way. Um, and the cool thing is they’re they’re very nicely packaged. They’re very uh easy to install. For example, here’s our um listing on the Chad GBT app. uh listing the official uh store that they have. Um and we also

[04:29] have a application for the the anthropic one uh which we’re still pending on if there’s anybody from Enthropic out there that wants to approve us. Um but even if you’re not on these marketplaces, um they are pretty trivial to install uh for a an end user. You just give it the hosted MCP URL and you’re able to um connect pretty quickly. Okay, so let’s look at uh an example. This is our MCP in action. Here I’m asking, you know, which connectors do I

[05:01] have available? Um, and it goes through, hey, I have four connectors set up in this workspace. And then I can ask it some questions about my data like show five paying customers with Zenes support tickets. Um, and so this right now is looking through all the connectors that we have, searching the context store for that information that I that I asked it about. Um, and then combining that information across Zenesk and Stripe, um, so that it can come up with an answer for me. Okay. And there we go. So it cross referenced Zenesk and Stripe

[05:33] and then came back with, you know, five of those people that um, have open support tickets. Cool. So let’s go into kind of some lessons learned while building this uh MCP and things that you might want to keep in mind if you’re doing uh something similar. So one thing that we decided to do um after trial and error is to keep the tool count small. So um we for the execution part of the connector where you’re pulling that data, we only expose or really deal with two main tools. one is to describe the

[06:06] connector to get the schema of how do you query that information and two is the execute that’s able to read write and delete records. Um the opposite end of the spectrum here would be since we connect to so many different um connectors and each of these has different entities different actions you can take. We could have exposed, you know, an MCP tool for each one of these. Um, but instead what we found is really keeping it narrow, using progressive discovery of all of the capabilities um that the connector has available. Um,

[06:39] and really limiting the amount of context that you shove into the those tool descriptions um really helps with the the performance of the of the MCP server. Two, Olaf is the way. So this this refers to how you authenticate the MCP server itself. Um so this is an example for like anthropic. You click a button uh to connect and that spins up our ooth flow. So you can sign in to air bite um accept the the privileges and then

[07:10] you’re all set up with all the connectors that you’ve uh linked up. Um, and technically you can use other authentication mechanisms through MCP, but you’re really going to have a hard time um if you do like beer off or or anything like that because the spec is really heavy on ooth and all of the clients, the the main ones at least um are really leaning towards the the OAF as a better UX for uh installing that connector. So that’s an example for uh the the enthropic um custom connector um registration where they have no no way

[07:47] of you to put like a bearer token or anything. It’s just all defaulting to to OOTH. So that’s is is very important. And two, users actually expect um to have long lived sessions uh through these MCP servers. Um unlike a web app where you might be okay with having to sign in again um a couple times, uh users expect to use MCPs more like a mobile app where they don’t really have to think about authenticating. It’s just available uh whenever they want to use it. And so that has its own little um you know uh things to keep in mind as

[08:23] you’re implementing ooth is keeping offline long sessions um that are stored separately from the web app and have its own set of uh of life cycles. Cool. Elicitation though is not the way. So I’ll get into what elicitation is but a big part of um the MCP server that I mentioned is you need to be able to connect your tools. you need to be able to give credentials in a way that’s safe. Um, and to do that, uh, basically when you ask, you know, how do I connect

[08:53] to to HubSpot? Um, we generate a link that you go to which you can pops up this widget and you’re able to select, you know, which uh entities you want to connect and redirect to to HubSpot to go through the that OOTH flow. Um, now technically MCP has something in the spec that allows you to surface those kinds of URLs um and and process those inputs um called elicitation. It’s a way that you can request information from the user. For the longest time um it was

[09:27] only form mode elicitation which is not um applicable for sensitive um sensitive uh data like credentials for an API. But more recently um this URL mode elicitation became a thing um that is very similar to what we’re doing. But the problem is uh support across the MCP clients. So that’s a big theme uh when working with MCP is that even though there is a spec features that is are supported across the clients kind of vary quite a bit. Um

[09:58] so this is an example from cloud desktop where you know it just is telling me hey I don’t support URL mode elicitation. I can’t do that. And so we had to go back to doing our own thing um and not using the spec for that for that kind of thing. Okay, let’s talk about the CLI a bit. So if MCPS are easy for these non-technical users, um CLI are kind of the more technical counterpart might call it the kind of more powerful in some ways that we’ll get into. And this is the the same example we saw earlier, but this time

[10:30] with the the MCP or sorry, with the CLI where we’re asking, you know, which connectors do I have available? It’s this time loading a skill that tells it about the CLI. Um, and then, you know, using the CLI itself to query things. We got back the connectors. Then we asked, you know, show five paying customers that have Zenes support tickets. Same as last time. um it’s able to this time use the CLI to query that query the context store aggregate that data and then eventually it should come back with a result now okay um so there’s those same

[11:07] five um five users so um on the design side for CLI I think one important thing to keep in mind is to design those CLIs with agents in mind um some of the things that might be helpful for users when you’re making a CLI are going to be like blockers for agents. Um, and we’ll get into that a little bit more. Um, the first design decision here that we made was take JSON in and return JSON out. So uh for humans it’s very nice to specify

[11:41] um a bunch of flags uh to work with CLIs but when it comes to these more complicated um inputs that uh you have to build to to make these queries and agents are really good at working with JSON. um they’re able to construct this uh in a much more um direct and and less of a guessy way um than using those flags. And so on the output, JSON also makes it easy to deal with longer

[12:14] responses um be able to leverage one of the key capabilities of CLIs, which is hey, you have these this Unix system with pipes that you can redirect the output to different um programs. So you can use jq for example to select certain certain things from the output and trim that and so JSON really unlocks a lot of that um capability. Two consistency is very much key here. So it should be dead obvious for agents to know how to do something across all

[12:47] of the resources that you’re exposing. If you have structured your CLI in a way that it’s it’s structured where there’s a noun and then a verb for this example you know connectors list connectors create make sure that when you’re implementing a workspace um CLI uh commands they also follow that same format. So workspace list is another one that that we have. And so it’s very um critical that agents know the right way to do things and it’s easy for them to

[13:18] know the right way to do things without having to read a bunch of documentation. And another interesting fact here is, you know, if you see agents making the same mistake over and over, um calling the wrong command a bunch of times, consider making that your contract. Make it dead simple for agents to stumble across the the right way to to use things. um because that usually means that something is not quite as obvious as it should be in your AP in your CLI contract if agents keep making the same kind of mistakes.

[13:50] Three, skills are skills ship with uh the CLI tool. So skills are a must uh when you’re doing CLIs because how else if you have a CLI installed is an agent going to know that that CLI even exists in the first place. So it helps a lot with discovery of uh your tools that are available. Um and they also help with uh using that tool effectively. So uh we have a skill that gets surfaced. It has a a description that is able to come up whenever you ask anything about

[14:22] connectors. It knows to bring up that CLI and invoke it. Um and then the way that you structure the skill is also something to um think through. you know, you don’t want to put too much into the skill uh that you’re going to bog down the context. Um, skills have this uh ability to be separated out into references um where you can have a main skill that points to other files in a in a skill directory um that can expand information about the the different commands. And that really uh helps cut down the the amount of uh of context

[14:53] that you’re loading in and um leverages the progressive discovery um ability of uh of these agents. Cool. And then another interesting fact uh for off side, off was interesting on the MCP side. It is interesting in other ways for CLIs because we can’t assume that a human is going to be present to able to interact with those prompts. Um when CLIs are being invoked by agents, it can’t sit there and wait for you to type um a prompt into the CLI. you have

[15:24] to expose things either through flags um or in the case of credentials environment variables and config files um so that things can be set up out of band and you don’t have to wait for that uh whenever you’re invoking the CLI um and I would say aside from off um that’s a general thing a lot of CLIs that are built for humans you type a command and it’ll wait there ask you for prompts uh and that is not um you know able to be used properly ly by these agents. Um

[15:55] they’ll just kind of get get stuck there. Um cool. So CLI and MCPs, which one is better? Well, they both have kind of their own trade-offs. You know, with the MCP, the spec is not uniformly implemented across the board. Um there’s a bunch of limits that these providers decide to implement aside from the spec as well. For example, like Claude has a 2 kilobyte limit on server and tool call uh descriptions. There’s a limit of how long the tools can run. So it’s harder to do more longunning processes through

[16:30] MCP. Um and uh you know there’s there’s other kind of kind of limits that they’ve introduced there. And then on the CLI, the cool things about MCP like you know you can have a hosted MCP server that just is always updated. That’s not quite the case with the CLI. you have to think more about versioning. It’s harder to keep packages up to date uh with all these new features. Um and there’s no while the limits can be well limiting on the MCP side, not having any of those on the CLI across the tools uh across the the calls of the CLI can make

[17:04] things go wrong and continually go through loops that um you know make the agent spin. And so really I think both have their place. I think MCPs are great for those non-technical users, be able to quickly prototype things, build one-off reports, um, and even leverage that MCP ecosystem to have things uh, talk to each other. And then the CLI is better for those more technical users, more longer running tasks, maybe outputs that are super long and you need to

[17:35] leverage those um features that Unix and and the pipes give you where you can redirect output to a file. You can do a tail, do a head on that output. Um that’s where really the the CLI um starts to to shine. All right, that is basically all that I had. Um, we have a booth over there at Airbite um that you should check out and come work with us. Thanks.