# AI interfaces

> How inspect.software measures machine-readable interfaces — API schemas, MCP servers, and runnable examples. Part of the AI Readiness badge.


**AI interfaces** measures whether a project exposes machine-readable
interfaces: formal API schemas, a Model Context Protocol server, or runnable
examples. Where they exist, an AI agent can consume the software through a
contract instead of reverse-engineering behavior from source.

- **Category:** [AI Readiness](/wiki/ai-readiness) (15% within category)
- **Weight in overall index:** 0% — part of the independent AI Readiness badge
- **Metric key:** `ai_interfaces`
- **`null`** when the repository exposes none of the signals — absence is treated as not-applicable, never as a penalty

## How the value is computed

| Component | Weight | Evidence |
| --------- | ------ | -------- |
| API schema | 40 | OpenAPI/Swagger, GraphQL SDL, protobuf, or AsyncAPI files |
| MCP server | 20 | a Model Context Protocol server dependency or `mcp.json` configuration |
| Runnable examples | 40 | `examples/`, `recipes/`, or `samples/` directories, or notebooks |

## The null rule, explained

A plain utility library legitimately has no API schema, no MCP surface, and
possibly no examples directory — and it would be wrong to mark it down for
its nature. The metric therefore only produces a value when at least one
signal is present; otherwise it is `null` and the
[AI Readiness](/wiki/ai-readiness) category renormalizes onto its other
metrics, following the methodology-wide missing-data rule
(see [the health index](/wiki/health-index)).

## Why these three signals

- **API schemas** are contracts a model can read exactly — endpoints, types,
  and errors without inference.
- **An MCP server** is the strongest possible statement of agent readiness:
  the project ships a first-class interface for AI tooling.
- **Runnable examples** are executable documentation. For an agent, a
  working example is a verified starting point rather than prose to
  interpret — and examples double as a de-facto test of the public API.

## Improving the value

- Publish the API schema the project already implies: generate OpenAPI from
  the framework, commit the `.proto` or GraphQL SDL files.
- Maintain an `examples/` directory with small, runnable programs kept
  current in CI.
- Where the project naturally serves tooling, consider shipping an MCP
  server.

Related: [AI agent context](/wiki/ai-agent-context) ·
[AI Readiness](/wiki/ai-readiness)