How to Shape a Single AI Backend for Different Audiences: OpenAPI, CLI, and Frontend

01 | Same capability, three faces

The backend API (OpenAPI contract) can be exposed in three distinct layers, each targeting a different audience and having its own design constraints:

OpenAPI – audience: third‑party integrators; shape: stable, complete, machine‑readable contract; constraints: contract‑first, versioned, backward compatible, no internal endpoints leaked.

CLI – audience: primarily AI agents (humans can also use it); shape: atomic commands organized by task/lifecycle; constraints: clear semantics, stable command surface, explicit non‑zero exit codes that force a "ask‑human" fallback, cross‑platform without environment assumptions.

Frontend product – audience: humans; shape: full UI with guidance, confirmation dialogs, visualisation; constraints: human‑centric interaction, fault‑tolerant, no need to remember commands.

The same backend endpoint appears differently in each layer. For example, the "role‑write" API is a detailed contract in OpenAPI, becomes an atomic command such as dev config consumers add or collaborators add in the CLI, and shows up as a form field on a "Permissions & Security" page in the frontend.

┌────────────────────────────────────────┐
                  │   A backend: backend‑api (OpenAPI contract)   │
                  │   Carries all capabilities of the Agent platform │
                  └────────────────────────────────────────┘
                                   │
            ┌──────────────────────┼───────────────────────┐
            ▼                      ▼                       ▼
   ┌─────────────────┐   ┌──────────────────┐   ┌──────────────────┐
   │   OpenAPI        │   │   CLI · a‑cli    │   │  Frontend · web‑repo  │
   │  for integrators│   │  for AI Agent   │   │  for humans        │
   │  /backend‑api/* │   │  a‑cli <verb>    │   │  Web console       │
   ├─────────────────┤   ├──────────────────┤   ├──────────────────┤
   │ Organization: resource path││ Organization: task/lifecycle││ Organization: full UI scene│
   │ Granularity: field‑level   ││ Granularity: atomic+composed││ Granularity: page+guidance│
   │ Contract‑first / versioned ││ Stable / testable / ask‑human││ Human‑centric / fault‑tolerant│
   └─────────────────┘   └──────────────────┘   └──────────────────┘
   Example:                 Example:                 Example:
   Role‑write API (low‑level) dev config             Frontend project
   Publish API             consumers add          Agent module
   Search API             organization search

02 | Most common mistake: mixing the three layers

Three typical pitfalls arise when the layers are conflated:

Using OpenAPI directly as a CLI surface leaks internal endpoints and uses naming that is not task‑oriented, causing AI mis‑invocation.

Using the CLI as a product UI forces users to construct complex JSON or remember path hierarchies, shifting interaction burden onto the user.

Using the frontend as an OpenAPI presents raw endpoints without guidance, making them unusable for humans.

03 | Why the CLI layer must be treated differently

In practice the CLI’s primary users are AI agents. Four non‑negotiable design constraints follow:

Atomicity, not monolith. AI needs small building blocks to compose novel workflows; a single "one‑stop‑shop" command caps the AI’s capability ceiling.

Command‑surface stability. AI scripts hard‑code command names; any rename breaks automation.

Errors must trigger "ask a human". Non‑zero exit codes and explicit options force the AI to defer ambiguous decisions to a person.

Cross‑platform, no environment assumptions. Assumptions such as a fixed directory or pre‑installed dependency cause failures across diverse OSes.

The CLI therefore acts as the AI’s deterministic "hands and feet": actions are explicit, feedback is clear, and judgment remains with the AI.

04 | MCP vs. CLI: opposite directions

MCP (Machine‑Callable Protocol) has two distinct roles:

Identity A – Exposure. A published agent is exposed as an MCP server so external LLMs or agents can call it as a function.

Identity B – Mounting. An external MCP service is registered as a reusable resource and attached to an agent, granting the agent capabilities such as database queries or script execution.

Key differences (derived from the original comparison table):

Coverage breadth. CLI covers creation, configuration, publishing, iteration, dialogue, resource management, and authorization – the widest surface. MCP exposure only lets an agent be used as a tool; MCP mounting only lets an agent acquire external tools.

Caller. CLI is driven by AI as an operator across the full lifecycle. MCP exposure is invoked by external AI as a consumer. MCP mounting is invoked by the agent itself as a caller.

Shape. CLI provides atomic commands with method descriptions; MCP uses a standard protocol (server or client) native to toolchains.

Main configurator. CLI is configured automatically by AI scripts; MCP exposure is toggled by the agent author; MCP mounting is configured via the frontend credential and authorization UI.

CLI can also manage MCP resources, e.g., resources mcp create or dev resources, but this management layer is separate from the actual MCP call flow.

05 | Choose the scenario first, then the shape

The methodology is: first identify the audience, then decide the appropriate layer.

Integrators receive a stable, versioned contract (OpenAPI).

AI operators receive the broadest set of atomic commands with stable names and explicit error handling (CLI).

Human users receive a full UI product with guidance and visual feedback (frontend).

Tool‑chain integration uses the MCP protocol in its two directions – exposure and mounting – each occupying a single connection point.

Keeping the layers separate avoids the common pitfalls of command‑path leakage, internal endpoint exposure, semantic mis‑routing, rename‑induced breakage, cross‑platform crashes, and conflating the command surface with the protocol surface.