# Designing CLIs for Agents, Not Humans Pedro Lopez, Airbyte | AI Engineer | 18:20 Source: https://www.youtube.com/watch?v=3wj6sgbi1YA Channel: AI Engineer (https://www.youtube.com/@aiDotEngineer). Summarised by AIE Talks. Page: https://aietalks.com/talks/designing-clis-for-agents-not-humans Published: 2026-10-09 Tags: agent-skills, agents, developer-experience, mcp, tool-use ## TL;DR - Airbyte keeps its MCP interface small by exposing connector description and execution tools, then using progressive discovery for the rest of the connector capabilities. - MCP clients work best with OAuth and long-lived sessions, while URL elicitation remains difficult because support differs between clients. - Agent-focused CLIs should accept JSON, return JSON, use consistent noun-verb commands, ship skills for discovery, and avoid interactive prompts. ## Summary Pedro Lopez explains how Airbyte exposes its Context Store to AI agents through an MCP server and a CLI. The Context Store connects services such as Zendesk, Stripe, and HubSpot, then provides a search-optimized index that agents can query and use for actions. Both interfaces are thin layers over Airbyte's shared platform and OpenAPI specifications. For MCP, Airbyte keeps the execution surface small, uses progressive discovery, relies on OAuth, and maintains separate long-lived sessions. URL elicitation is less practical because MCP clients do not support it consistently. The CLI targets more technical users and agents. It takes JSON input, returns JSON output, follows consistent noun-verb commands, includes skills that explain how to use it, and avoids prompts that would block unattended execution. Lopez recommends MCP for quick use by less technical users and the wider MCP ecosystem. He recommends a CLI for longer tasks, large outputs, and Unix pipes. ## Key ideas ### Airbyte's Context Store joins company data for agent queries [00:33](https://www.youtube.com/watch?v=3wj6sgbi1YA&t=33s) Airbyte began as an open-source standard for moving data from SaaS tools such as Zendesk, Stripe, and GitHub into analytics pipelines. Pedro Lopez says it now provides a data and action layer for agents through the Context Store. The store connects those services and keeps a search-optimized index of their data. Agents can gather records and contacts from different systems and join them together. Airbyte exposes the Context Store through an SDK, a web UI, an MCP server, and a CLI. The talk focuses on the last two interfaces, which make the data available inside agents such as ChatGPT and Claude. ### The MCP and CLI are thin interfaces over one changing platform [02:12](https://www.youtube.com/watch?v=3wj6sgbi1YA&t=132s) Airbyte's interfaces expose three broad capabilities: managing organizations, workspaces, and connectors; authenticating third-party services without exposing credentials to agents; and searching, reading, writing, and taking action across the connected systems. Lopez says the MCP server and CLI are thin, unified interfaces rather than separate implementations of the platform. They accept commands, call the shared platform, and format results. Since the platform changes more than 10 times a day, Airbyte uses OpenAPI specifications as a source of truth for connecting the interfaces to its APIs. ### A small MCP tool surface works better with progressive discovery [05:43](https://www.youtube.com/watch?v=3wj6sgbi1YA&t=343s) Airbyte exposes two main execution tools for connectors: one describes a connector and returns the schema for querying it, while the other executes reads, writes, and deletes. Lopez contrasts this with exposing a separate MCP tool for every connector entity and action. Airbyte instead keeps the tool surface narrow and discovers connector capabilities progressively. It also limits the amount of context placed in tool descriptions. His experience was that this improved the MCP server's performance, especially because Airbyte connects to many systems with different entities and actions. ### MCP authentication needs OAuth and sessions that outlast a browser visit [06:52](https://www.youtube.com/watch?v=3wj6sgbi1YA&t=412s) Lopez says OAuth is the practical authentication choice for an MCP server. Users can click to connect, sign in to Airbyte, approve privileges, and use their linked connectors. Other mechanisms are technically possible, but the MCP specification and major clients lean heavily toward OAuth. Some clients provide no way to enter a bearer token when registering a custom connector. He also says users expect MCP to behave more like a mobile app than a web app. They do not want to authenticate every few uses, so implementations need offline, long-lived sessions with their own lifecycle, separate from the web application's sessions. ### URL elicitation is difficult because MCP clients implement it unevenly [08:31](https://www.youtube.com/watch?v=3wj6sgbi1YA&t=511s) Airbyte needs a safe way for users to connect services such as HubSpot. Its current flow generates a link where users choose entities and complete the provider's OAuth flow. MCP includes elicitation for requesting information from users. Earlier form-mode elicitation was unsuitable for sensitive credentials, while URL-mode elicitation is closer to Airbyte's flow. The problem is inconsistent client support. Lopez shows that Claude Desktop does not support URL-mode elicitation, so Airbyte had to use its own approach instead of relying on the specification feature. He treats uneven client support as a recurring MCP implementation issue. ### Agent-focused CLIs should use JSON at both boundaries [11:11](https://www.youtube.com/watch?v=3wj6sgbi1YA&t=671s) Lopez designed Airbyte's CLI for agents rather than assuming a human will type every option. Human-oriented CLIs often use many flags, but agents can construct complex JSON inputs more directly and with less guesswork. JSON output also supports long responses and Unix pipelines. An agent or user can pipe the result into tools such as jq, select particular fields, and trim the output. The same CLI can query the Context Store and combine data from connectors, as in the example that finds paying customers with Zendesk support tickets. ### Consistent noun-verb commands reduce repeated agent mistakes [12:36](https://www.youtube.com/watch?v=3wj6sgbi1YA&t=756s) The CLI should make the same operation look the same across every resource. Lopez gives the pattern "connectors list" and "connectors create", then says workspace commands should follow the same structure, such as "workspace list". Agents should not need to read extensive documentation to discover the command shape. If agents repeatedly call the wrong command, he recommends considering that mistaken usage when defining the contract. Repeated errors indicate that the intended command is not obvious enough. A consistent structure gives agents a predictable way to find and call operations. ### Skills and non-interactive authentication make a CLI discoverable and usable [13:51](https://www.youtube.com/watch?v=3wj6sgbi1YA&t=831s) Airbyte ships skills with the CLI so an agent can discover that the tool exists and learn when to invoke it. A skill can describe the CLI and point to other files for details about individual commands. Splitting information into references keeps the main skill from loading too much context at once and supports progressive discovery. Authentication and other setup also have to work without a person at the terminal. Credentials can come through flags, environment variables, or config files. Interactive prompts can leave an agent waiting indefinitely, so agent-invoked CLIs must support out-of-band configuration. ### MCP and CLI fit different kinds of agent work [16:01](https://www.youtube.com/watch?v=3wj6sgbi1YA&t=961s) Lopez describes trade-offs on both sides. MCP clients do not implement the specification uniformly and may impose limits, such as Claude's stated two-kilobyte limit on server and tool-call descriptions. MCP also makes long-running processes harder. A CLI requires more attention to package versioning and updates, but it does not impose the same cross-tool limits. Its freedom can also let an agent loop or run indefinitely. Lopez recommends MCP for less technical users, quick prototypes, one-off reports, and connecting to the wider MCP ecosystem. He recommends a CLI for technical users, longer-running tasks, very long outputs, and Unix operations such as redirecting output to a file, using tail, or using head. ## Notable quotes - "The MCP and the CLI, the way that we've structured things is that they are thin unified interfaces into our platform, not reimplementations of the platform." (02:12) - "One thing that we decided to do after trial and error is to keep the tool count small." (05:43) - "Users actually expect to have long lived sessions through these MCP servers." (07:56) - "The first design decision here that we made was take JSON in and return JSON out." (11:31) - "Skills are a must 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." (13:51) ## Tools & references mentioned - Airbyte - Airbyte Context Store - MCP - OpenAPI - Zendesk - Stripe - GitHub - HubSpot - ChatGPT - Claude - Claude Desktop - OAuth - Unix - jq ## Who should watch - You are exposing a SaaS product or data platform to agents and need to choose between MCP and a CLI. - Your MCP integration has too many tools, complicated authentication, or client compatibility problems. - You are building a CLI that agents will run unattended and need predictable inputs, outputs, discovery, and authentication. ## Related talks - [Building Agent Interfaces: Lessons from Chrome DevTools (MCP) for Agents](https://aietalks.com/talks/building-agent-interfaces-lessons-from-chrome-devtools-mcp-for-agents) (Michael Hablich, Google, 22:38) - [Your MCP Server is Bad (and you should feel bad)](https://aietalks.com/talks/your-mcp-server-is-bad-and-you-should-feel-bad) (Jeremiah Lowin, Prefect, 54:33) - [Just do it. (let your tools think for themselves)](https://aietalks.com/talks/just-do-it-let-your-tools-think-for-themselves) (Robert Chandler, Wordware, 06:50) - [The Future of MCP](https://aietalks.com/talks/the-future-of-mcp) (David Soria Parra, Anthropic, 18:46) - [The Rise of the Agentic Economy on the Shoulders of MCP](https://aietalks.com/talks/the-rise-of-the-agentic-economy-on-the-shoulders-of-mcp) (Jan Curn, Apify, 18:08)