infra-api
Manage AICP's API surfaces — LocalAI's OpenAI-compatible REST API (proxied at `localhost:8090/v1/*`), AICP's MCP tool surface (~64 tools, 21 deprecated per audit), AICP CLI commands (~100 flags), agen
SKILL.md.claude/skills/infra-api/SKILL.md
GitHubinfra-api
Manage AICP's API surface design + lifecycle. AICP exposes 4 distinct API surfaces:
- LocalAI REST API — OpenAI-compatible
/v1/chat/completions,/v1/embeddings,/v1/audio/*, etc., onlocalhost:8090. AICP proxies but doesn't define this contract — LocalAI does. - MCP tool surface — currently 64 tools (21 deprecated per audit), accessed via stdio transport. Per the MCP audit, the surface is being trimmed to inference + KB + fleet (47 KEEP) with operational ones moving to CLI.
- AICP CLI — ~100 flags (per
aicp --help), the operator-facing command surface that follows the Gateway Output Contract per the contract-adoption decision. - Agent server REST API — activated by
aicp --agent <port>, exposes task submission/status for fleet coordination.
Trigger phrases (when to load this skill)
Load when the conversation matches any of:
- Direct verb: "design a new API endpoint", "version the API", "deprecate API X", "OpenAPI schema", "contract change for fleet integration"
- MCP tool design: adding/modifying an MCP tool — engage this skill alongside the MCP-vs-CLI decision criteria
- CLI flag design: adding a new top-level CLI flag — engage with Gateway Output Contract awareness
- Fleet RPC design: planning agent-to-agent or controller-agent
protocols (load
infra-networkingfor transport too)
Do NOT load when:
- The concern is RUNTIME state of the API (load
aicp-ops-runtime) - The concern is MCP MIGRATION specifically (the audit decision is the source of truth — load it directly)
- The concern is HOW to invoke a CLI flag (load the relevant ops skill —
aicp-ops-*)
Operations
Operation 1 — Design a new MCP tool (and decide if it should be CLI instead)
When: a new capability needs to be exposed.
Process:
- Apply the
cli-tools-beat-mcp-for-token-efficiencylesson criteria:- Cross-conversation discoverability needed? → MCP
- External service bridge? → MCP
- Project-internal operational? → CLI+Skills (preferred)
- High-frequency inference? → MCP (Category A in audit)
- If CLI: extend
aicp/cli/main.py, follow Gateway Output Contract (NEXT lines). Author companion SKILL.md. - If MCP: add to
aicp/mcp/server.pywith@mcp.tool()decorator, minimal docstring (concise schema reduces consumer overhead) - Document the decision (especially if this is a borderline case) in
wiki/decisions/00_inbox/<tool-name>-mcp-or-cli.md
Quality bar: NEW MCP tools default to "should be CLI" unless they clearly meet MCP-win criteria. Per the audit, AICP has too many MCP tools already — adding more without rigor compounds the problem.
Operation 2 — Version an API surface
When: backward-incompatible change is unavoidable.
Process:
- Choose versioning style:
- URL path:
/v1/...→/v2/...(LocalAI-style; visible) - Header:
Accept-Version: 2(less visible; harder for operators) - Tool name:
aicp_chat→aicp_chat_v2(MCP-style; clear)
- URL path:
- Implement v2 alongside v1; mark v1 deprecated with warning
- Per
config-migrationsskill, give a deprecation window (1-2 releases) - Document: CHANGELOG + decision page
Quality bar: v1/v2 cohabitate during deprecation; cutting v1 same release as v2 is a hard break that breaks consumers without warning.
Operation 3 — Deprecate an API endpoint or tool
When: removing something from the public surface.
Process:
- Mark deprecated: docstring
[DEPRECATED]prefix + return-payloadwarning:field (per the MCP audit pattern — see deprecated MCP tools inaicp/mcp/server.py) - Wait 1-2 release cycles for consumers to migrate
- Remove the registration; runtime returns 404 or NoSuchTool
- Document the timeline in CHANGELOG
Quality bar: NEVER skip the deprecation period. Removing without warning breaks consumers silently.
Operation 4 — Generate or audit an OpenAPI schema
When: documenting AICP's REST surface for external consumers.
Process:
- AICP itself doesn't have a REST API beyond LocalAI's (which has OpenAPI from upstream) and the agent server (which is small)
- For the agent server: the REST surface is in
aicp/agent/server.py; generate OpenAPI via FastAPI's built-in/openapi.jsonendpoint - For the LocalAI proxied surface: refer to LocalAI's own OpenAPI spec
at
localhost:8090/swagger/index.html(when LocalAI runs) - For the MCP tool surface: MCP doesn't use OpenAPI — the tool list is
the schema (visible via the MCP client's
tools/listrequest)
Quality bar: don't claim AICP has an OpenAPI surface it doesn't have (only the agent server does). Setting expectations correctly avoids operator confusion.
Gotchas
Detection: agent adds a new MCP tool without applying CLI-vs-MCP criteria. Rule: every new MCP tool gets evaluated against the
cli-tools-beat-mcplesson criteria first. Default is CLI. Reasoning: per the audit, AICP already has 64 MCP tools; adding more without justification compounds the schema overhead per consumer.Detection: agent versions via header instead of URL path. Rule: prefer URL path versioning (
/v1/) — visible, debuggable, cacheable. Reasoning: header versioning is invisible in logs, breaks naive caching, and produces hard-to-debug version mismatches.Detection: agent removes a deprecated tool same release as deprecation. Rule: deprecation needs 1-2 release cycles before removal. Reasoning: consumers need a window to migrate; same-release removal is a hard break.
Detection: agent claims AICP has an OpenAPI spec for the MCP surface. Rule: MCP doesn't use OpenAPI — the tool list IS the schema. Reasoning: misnaming the contract type leads to confusion; OpenAPI applies to REST, not MCP stdio.
Detection: agent designs a fleet RPC without considering the audit's MCP-as-bridge guidance. Rule: fleet agent-to-agent protocols are exactly the case MCP serves well (cross-conversation discoverability + external bridge). Don't reinvent in CLI. Reasoning: the audit categorizes fleet/P2P tools as Category C KEEP MCP for this reason.
Reference exemplars
aicp/mcp/server.py— MCP tool definitions; deprecated tools show the warning-payload patternaicp/cli/main.py— CLI flag dispatcher;_print_next()helper for Gateway Output Contractaicp/agent/server.py— agent REST API (the only AICP-defined REST surface)wiki/decisions/00_inbox/aicp-mcp-tool-surface-audit-2026-04-19.md— the audit decision (MCP-vs-CLI categorization criteria)wiki/decisions/00_inbox/aicp-cli-mcp-outputs-adopt-gateway-output-contract.md— the contract for CLI/MCP outputs~/devops-solutions-research-wiki/wiki/lessons/03_validated/tools-architecture/cli-tools-beat-mcp-for-token-efficiency.md— the underlying lesson
Domain context
AICP's API surface is intentionally bifurcated: LocalAI's REST for inference (proxied), MCP for cross-conversation tools, CLI for operator/skill-driven workflows. The active migration is reducing MCP surface (per audit) while maintaining LocalAI proxy + adding CLI flags for migrated capabilities. Future fleet API design lives in this skill's scope.
Related skills
| Skill | When to use |
|---|---|
infra-networking |
When the concern is transport (port, MCP stdio, etc.) |
infra-security |
When the concern is auth/access for the API surface |
config-migrations |
When the API change includes config schema migration |
architecture-propose |
When proposing a major NEW API surface |
aicp-ops-runtime |
When diagnosing live API behavior |