# Designing CLIs for Agents, Not Humans — Pedro Lopez, Airbyte

## Executive summary

Airbyte built two distinct interfaces—the Multi-Client Platform (MCP) server and the Command Line Interface (CLI)—to allow AI agents to access its Context Store, a search-optimized index of data from various SaaS tools (e.g., Zendesk, Stripe). The MCP is designed for non-technical users, prioritizing ease of integration into existing agent platforms (like ChatGPT). Conversely, the CLI is built for technical users, offering a more powerful, structured interface optimized for complex, long-running tasks and leveraging Unix capabilities like pipes. Both interfaces are thin wrappers over Airbyte's core platform APIs, ensuring data consistency and scalability.

## Key takeaways

- Designing for Agents vs. Humans: CLIs must be designed with agents in mind, requiring JSON input/output and consistent Noun-Verb command structures. For agents, the structure must be dead obvious, and skills should ship with the tool to aid discovery.
- MCP Best Practices: When building an MCP, keep the tool count small by using progressive discovery of capabilities. Furthermore, OAuth is the required authentication method, and users expect long-lived sessions, unlike traditional web applications.
- CLI vs. MCP Use Cases: MCPs are ideal for non-technical users and quick prototyping/one-off reports. CLIs are better suited for technical users, complex workflows, and long-running tasks that benefit from Unix piping capabilities.

## Technical details

- Interface Architecture: Both the MCP and CLI are thin, unified interfaces built on top of a shared platform and APIs, rather than being reimplementations of the platform. The source of truth for connectivity is the OpenAPI specification.
- Core Capabilities Exposed: All interfaces must span three capabilities: 1) Managing core resources (organizations, workspaces, connectors); 2) Securely authenticating third-party services without exposing credentials to agents; and 3) Allowing agents to search, read, and write data (Ask and Act).
- CLI Design Principles: To optimize for agents, CLIs must enforce JSON in and JSON out. Consistency is critical: commands should follow a predictable Noun-Verb format (e.g., `workspace list`, `connectors create`). Skills must ship with the CLI to ensure agent discovery.
- Authentication and Session Management: For MCPs, OAuth is the recommended authentication flow due to the spec's focus and client adoption. Engineers must account for users expecting long-lived sessions, requiring specialized lifecycle management separate from the web app.

## Practical implications

- When designing agent interfaces, prioritize structured data formats (JSON) and predictable command syntax (Noun-Verb) over human-centric UI elements.
- For complex, multi-step workflows, consider the CLI approach to leverage Unix piping and redirection, which is superior to the MCP's limitations on process length.
- Always treat the OpenAPI specification as the primary source of truth for API interactions, especially when building thin interfaces for AI agents.

## Topics

AI Agents, CLI Design, Multi-Client Platform (MCP), Data Integration, OpenAPI, OAuth 2.0, Airbyte Context Store, Airbyte agent MCP docs, Airbyte Agent CLI

Source: https://www.youtube.com/watch?v=3wj6sgbi1YA