CLI design for AI agents means JSON in and JSON out, consistent noun-verb commands, skills shipped with the binary, and no interactive prompts. Pedro Lopez of Airbyte shared these lessons at the AI Engineer World's Fair 2026 after building both an agent CLI and an MCP server over the same platform.
What Airbyte exposes to agents, and through which interfaces
Airbyte now exposes its data platform to AI agents through two interfaces: an MCP server for hosted assistants like ChatGPT and Claude a command-line tool for coding agents. Software engineer Pedro Lopez described both at the AI Engineer World's Fair 2026 in San Francisco. Both are thin interfaces over one platform, generated largely from OpenAI specifications, and both expose the same three capabilities: managing organizations, workspaces, and connectors; authenticating third-party services without exposing credentials to the model; and searching and acting on data in what Airbyte calls the Context Store.
The Context Store is Airbyte's search-optimized index over SaaS tools such as Zendesk, Stripe, and HubSpot. It joins records across those systems so an agent can ask questions like "show five paying customers with Zendesk support tickets" and get one answer that combines billing and support data. Airbyte reports that its underlying platform deploys more than 10 times a day, which is why both interfaces stay thin and lean on the platform API rather than reimplementing logic.
The demo in the talk returned the same five customers whether the agent used the MCP server inside a hosted assistant or the CLI inside a coding agent. The interfaces differ in who they serve, not in what they can reach.
Why the Airbyte MCP server keeps its tool count small
The Airbyte MCP server exposes only two tools for connector data execution: one to describe a connector and get its query schema, and one to execute reads, writes, and deletes. Lopez said the team tried broader designs and found that a small surface performs better.
The alternative was one MCP tool per connector entity and action. Because Airbyte connects to many SaaS products, that approach would flood the model's context with tool descriptions. Instead the server uses progressive discovery: the agent first describes a connector, learns its schema, and only then constructs an execution call. Lopez's practical advice is to keep tool descriptions short and let the agent discover capabilities step by step rather than loading everything up front.
This matters because MCP clients impose their own constraints beyond the MCP specification. Lopez cited a 2 KB limit on server and tool descriptions in Claude an example of a provider-imposed cap, and noted that limits on how long a tool may run make long-running operations difficult through MCP.
OAuth and long-lived sessions in real MCP clients
Lopez's second lesson is that OAuth is the practical authentication path for hosted MCP servers. A user clicks a connect button, the provider spins up an OAuth flow, the user signs in to Airbyte and grants privileges, and every linked connector becomes available. Although the MCP specification technically permits other mechanisms, the major clients are built around OAuth. Lopez said Anthropic custom connector registration offers no bearer-token option at all, so bearer-based auth has no realistic path in those clients.
Sessions also behave differently from the web. Users expect an MCP connection to work like a mobile app, always signed in, rather than like a website that asks them to log in repeatedly. Airbyte therefore stores offline long-lived tokens for MCP separately from web-app sessions, with their own refresh lifecycle. Lopez framed this as an implementation requirement the spec does not solve for you.
Why URL elicitation was not ready for credential flows
Elicitation, the MCP feature that lets a server request input from the user, looks like the right tool for collecting connection credentials. Airbyte's connection flow generates a link where the user picks which entities to sync and completes an OAuth redirect to the source tool, exactly the pattern URL-mode elicitation describes.
The problem is uneven client support. Form-mode elicitation is unsuitable for sensitive data such as API credentials, and URL-mode support varies across clients. Lopez showed Claude Desktop rejecting URL-mode elicitation outright. Airbyte fell back to its own link-generation flow rather than depending on the spec. His general warning applies to anyone building on MCP today: spec features exist on paper, but the subset each client actually implements differs enough that you must test every feature you rely on.
Four rules of CLI design for AI agents
Lopez distilled Airbyte's CLI work into a short set of rules for CLI design for AI agents, each fixing a failure mode he observed with human-oriented CLIs.
Return JSON, accept JSON
Flag-heavy command lines force an agent to guess argument shapes. JSON input lets the model construct complex queries directly, and JSON output pairs naturally with Unix pipes: the agent can route output through jq to select and trim fields before reading it. Lopez called this combination the key that unlocks long responses.
Keep the command grammar consistent
A noun-verb structure such as connectors list, connectors create, workspace list lets an agent infer the correct command without reading documentation. Lopez added a sharper rule: if agents repeatedly call the wrong command, treat that mistake as a signal and change the contract so the wrong path stops existing.
Ship a skill with the CLI
If a CLI is installed on a machine, an agent has no way to know it exists unless something advertises it. Airbyte ships a skill whose description surfaces whenever the user asks about connectors, prompting the agent to invoke the CLI. The skill keeps a small main file and pushes detail into reference files, which preserves progressive discovery instead of loading everything into context.
Never wait on an interactive prompt
Authentication is the sharpest case, but the rule is general: an agent invoking a CLI cannot type into a prompt. Credentials go through environment variables and config files, everything else through flags, all configured out of band. A human-oriented CLI that pauses for input will simply stall an agent mid-task.
MCP or CLI: which interface fits which job
Lopez's closing position is that the two interfaces serve different users and workloads rather than one replacing the other. The comparison below reflects the trade-offs he named in the talk.
| Dimension | MCP server | CLI |
|---|---|---|
| Best user | Non-technical users prototyping in hosted assistants | Technical users and coding agents |
| Install path | Hosted URL or app marketplace listing | Package install plus versioning |
| Updates | Always current on the server | Requires client-side upgrades |
| Client limits | Description caps and runtime limits | None, but no guardrails against loops |
| Long-running work | Hard under tool time limits | Strong, with output redirection and tail/head |
| Ecosystem fit | Agents talk to agents via MCP listings | Unix pipes, jq, files, cron-style automation |
His guidance: choose MCP for quick prototypes, one-off reports, and non-technical users inside ChatGPT or Claude. Choose the CLI for longer tasks, very large outputs, and anything that benefits from redirection, filtering, and scripted composition. The missing guardrails on the CLI cut both ways; without the limits MCP imposes, an agent can also spin in loops, so the calling agent's own discipline carries more weight.
FAQ
- Why keep MCP tool counts small? Each tool description consumes context, and large surfaces confuse the model about which tool to call. Airbyte exposes two execution tools per connector and uses progressive discovery so the agent learns each connector's schema before acting.
- Can MCP clients authenticate with bearer tokens instead of OAuth? Lopez reported that the main clients default to OAuth and that at least one provider's custom connector registration offers no bearer-token option, so bearer auth is impractical for hosted MCP servers today.
- Why does an agent-facing CLI need JSON output? JSON is precise for the model to construct and easy to filter with jq through Unix pipes, which lets agents handle long responses without loading everything into context.
- What are skills in this context? Skills are description files shipped alongside a tool that tell an installed agent the tool exists, when to use it, and how its commands work, with deeper detail split into reference files to save context.
- Is the MCP specification uniformly implemented? No. Lopez showed a client rejecting URL-mode elicitation and cited provider-imposed description and runtime limits, so teams must verify each feature per client.
Turn your own conference talks into referenceable writing
A talk like Lopez's spreads through a room once; a written version keeps answering questions for months. If you have knowledge sitting in YouTube videos, whether a conference presentation, a technical walkthrough, or a recorded lesson, you can turn that recording into a structured article with Skala Blog. Paste the YouTube URL, get a transcription, and generate an article you can edit and publish.
Fork this article
Start a new branch from the same video, shaped your way. You keep the credit; the original keeps the attribution.
A fork in another language is filed as a translation of this article, so the two pages point at each other. You can unlink it later from the editor.
0/240
You are creating
- Format
- For
- Language
- Source
- Your angle
You will be asked to sign in before it is generated.
Buy credits