---
title: "Concepts: Classes, Profiles, Cards, and Capsules"
status: draft-0.1
normative: true
tokens: ~1900
anchors-stable: true
---

# 01 — Concepts

RFC 2119 keywords apply. Terms per [`GLOSSARY.md`](../GLOSSARY.md).

<a name="position"></a>
## 1. Position in the stack

Class Profiles layer on plain MCP. They define no transport or replacement tool protocol — MCP already provides those. This chapter targets MCP revision **`2026-07-28`**; alignment is recorded in [`decisions/0001`](../decisions/0001-mcp-2026-07-28-alignment.md). Everything rides existing mechanisms:

- Profile verbs are exposed as ordinary MCP **tools**.
- Class Profiles is an MCP **extension** identified as `org.classprofiles/profiles`, following MCP's `{vendor-prefix}/{extension-name}` grammar.
- A server advertises it in the `capabilities.extensions` map of its mandatory `server/discover` result. A consumer advertises support in `_meta["io.modelcontextprotocol/clientCapabilities"].extensions`. Negotiation is **per request**; there is no handshake.
- Capability disclosure uses ordinary MCP `tools/list`, whose result MUST NOT vary per connection and is cacheable under the `ttlMs` and `cacheScope` the server returns.
- The **Class Profiles card** is the extension's settings object (§6). The same content travels outside a live connection as a portable artifact.
- Conformance follows the ecosystem's fixture-suite culture.
- Risk metadata reuses MCP tool annotations rather than inventing a parallel vocabulary — and, because MCP requires clients to treat annotations as untrusted, Class Profiles supplies the fixtures that make them checkable ([03 §3](03-conformance.md#runner)).

A conformant server is, to a client that has never heard of this specification, just an MCP server with unusually predictable tools. That property is **zero-knowledge compatibility**; it MUST be preserved, and it is what makes unilateral adoption useful. It covers *invocation*: a naive client gets predictable tool shapes. It does not deliver the rest of the proposal's value — routing on semantic identity, surfaced degradation, and exact version selection all require the consumer behaviour in [03 §6](03-conformance.md#consumer).

This draft defines semantic contracts and their proof model. Installation discovery, account routing, and multi-server orchestration are outside this prototype.

<a name="class-profile"></a>
## 2. Class and profile

A **class** is a kind of capability: calendar, printer, notes, tracker. A **profile** is the versioned contract for a class, under one namespace (`org.classprofiles.calendar`).

A profile consists of:

1. One or more **Core baselines** — immutable, content-addressed contracts once published (§3).
2. **Facets** — optional, job-shaped, independently versioned modules (§4).
3. **Objects** — the shared data shapes verbs exchange, defined once per profile.
4. **Fixtures** — the executable definition of conformance ([03](03-conformance.md)).
5. The **Ten Jobs list** — the class's ten most common user jobs, which each baseline alone MUST complete.

<a name="baselines"></a>
## 3. Baselines

A **Core baseline** is the mandatory floor: the set of behaviors that make a member of the class useful on first contact, without the consumer knowing anything about which implementation it reached.

Membership is governed by two tests, and a candidate belongs in Core only if it passes both ([`decisions/0002`](../decisions/0002-the-plug-in-test.md)):

- **Sufficiency** — Core alone completes the class's Ten Jobs (§2). Nothing in the Ten Jobs list may require a facet.
- **Necessity, the plug-in test** — *a thing that cannot do this is not a member of this class.* If a real, reasonable implementation can lack the behavior and still obviously belong to the class, it is a facet, a vendor member, or nothing.

Hedged obligations (`where supported`, `wherever the backend permits`) are prohibited in Core. A hedge inside a Core requirement is evidence that the necessity test would fail; the behavior belongs in a facet with a `degrades_to` statement, where its absence is declared rather than tolerated.

Necessity is what earns the all-or-nothing conformance rule in [03 §4](03-conformance.md#ranking): a floor may demand everything only if everything it demands is essential.

Once published, a baseline is an immutable, content-addressed artifact:

```text
org.classprofiles.calendar/core@1   digest sha256:7f2a…
```

- A published baseline **means exactly one thing forever**. Corrections and additions mint a new baseline with a durable alias and migration note; they never mutate the old one.
- A conformance claim always names the exact baseline and its digest. An unqualified tier name is never silently reinterpreted as "latest."
- Published baselines are never deleted; they MAY be superseded.
- A draft baseline is amendable and MUST NOT be represented as immutable or conformant. Immutability engages only at publication.

The promise this buys is the project's whole reason for existing: *the exact published contract you integrated five years ago still exists and still means the same thing.*

Stability is not only a courtesy to integrators. **A meaning that never changes is a meaning that can be learned once.** A drifting vocabulary cannot be internalized by anything — a person, a written skill, or a model — because what was learned stops being true. Immutability is therefore a precondition for fluency (§9), not merely a compatibility guarantee, and it is why this is the strictest rule in the specification.

The consequence compounds over time. A published baseline can be learned by a consumer, written into a portable skill, and eventually known without being read at all. Every implementation of that exact baseline inherits the understanding, including implementations that did not exist when it was learned.

<a name="facets"></a>
## 4. Facets

A **facet** is a coherent job, not a menu of flags: `calendar/recurrence@1`, `calendar/rsvp@1`. Facets version independently of baselines and of each other; published facet versions are equally immutable.

- Implementations declare supported facets by exact ID and version in the card.
- Consumers reason about "supports `calendar/recurrence@1`" — a testable, composable claim. Fourteen loose independent properties are neither.
- Every facet carries a `degrades_to` story readable by an end user ([02 §8](02-descriptor.md#degrades-to)).
- The facet mechanism is specified in [06](06-facets.md). A profile gains a facet only by citing and declaring it; nothing is ambient. This draft demonstrates the mechanism through two unlike classes: Calendar's optional jobs, and Operator's surface facets, where the kind of thing being driven is a facet rather than a class of its own.

<a name="identity"></a>
## 5. Semantic identity vs. tool spelling

Two distinct things, never conflated:

| | Example | Role |
|---|---|---|
| **Semantic identity** | `org.classprofiles.calendar/create_event@1` | Canonical and frozen after publication. Bindings, policy, routing, fixtures, and receipts MUST key on this. |
| **Preferred spelling** | `calendar.create_event` | Presentation. The MCP tool name a server exposes by default. |
| **Actual tool name** | `google_calendar_create` | Whatever the server or host actually shows. |

Hosts demonstrably re-spell tool names — prefixing, replacing separators, sanitizing. A consumer that routes on spelling breaks the first time a host reformats it; a consumer that routes on semantic identity does not. Objects use `UpperCamel`; verb IDs use `lower_snake`; data IDs are **opaque strings** consumers MUST NOT parse.

<a name="card"></a>
## 6. The Class Profiles card

A profile-aware implementation declares what it implements in the settings object of the `org.classprofiles/profiles` extension, returned in the `capabilities.extensions` map of `server/discover`. The same block travels outside a live connection as a portable Class Profiles card. This illustrative block describes a published implementation; This draft contains no such Claim:

```json
"profiles": [
  {
    "baseline": "org.classprofiles.calendar/core@1",
    "digest": "sha256:7f2a…",
    "facets": ["calendar/recurrence@1"],
    "vendor": ["com.acme.cal/travel_buffer@1"],
    "via": "native"
  }
]
```

`via` is `native` or `projected` — **provenance, not grade** ([03 §4](03-conformance.md#ranking)). A `receipt` MAY be attached only after an implementation passes the named suite at the named digest ([03 §5](03-conformance.md#receipts)). Draft descriptors and undigested fixtures cannot support a passing receipt.

Because `server/discover` is mandatory, cacheable, and callable before any other request, a consumer can read the card, decide whether the server is worth engaging, and select an exact baseline **without invoking anything**. A consumer SHOULD honor the returned `ttlMs` and `cacheScope` rather than re-reading the card per turn.

One caution the protocol makes explicit: a server's advertised tool set MAY vary with the authorization presented on the request. A card is therefore valid for the authority under which it was read, and a consumer MUST NOT treat a cached card as an authority-independent description of the server.

<a name="projections"></a>
## 7. Projections and binding capsules

Existing servers join unmodified through **projection**: an adapter presenting profile verbs backed by an upstream's tools, such as an MCP server or W3C Thing Description. The adaptation is *compiled, not improvised* — a model may draft the mapping once; it is then reviewed, frozen, and behaviorally tested.

The frozen result is a **binding capsule** ([04](04-projection.md)): profile and facet digests, tool bindings, argument and result transformations, declared semantic loss, upstream surface digest, and conformance receipt — one portable, content-addressed artifact, executable publisher-side, host-side, gateway-side, or as a proxy. This dissolves the two-sided adoption problem: a host can make an existing server profile-compatible, and a publisher can later endorse or ship the same capsule.

<a name="consumers"></a>
## 8. Consumers

Consumers — agents, clients, and hosts — MUST adapt to declared baselines, facets, and `degrades_to` stories, and MUST NOT branch on vendor identity. Consumer behavior is itself conformance-tested ([03 §6](03-conformance.md#consumer)); "profile-compatible host" is an executable claim, not a marketing one.

The floor this buys: any agent that can operate one baseline-conformant calendar can operate all implementations of that exact baseline, including ones that do not exist yet.

<a name="agent-facing"></a>
## 9. Delightful disclosure

A profile serves agents, publishers, projections, and ordinary MCP clients. Each receives only what it needs. The card names the implementation-wide baseline, facets, and vendor members; the selected profile then exposes only the corresponding verb declarations. Absence narrows capability. Nothing repeats what the selected baseline already guarantees, and consumers branch on exact declarations rather than vendor identity or labels.

Once a profile is selected, the common path MUST NOT add a capability-diagnostic call between ordinary profile calls. MCP now supplies half of this for free: discovery is a separate, cacheable `server/discover` RPC, so nothing forces a diagnostic round trip into the working path. The obligation that remains is on the profile — it MUST NOT invent capability-probing verbs of its own, and MUST NOT require a consumer to call one before ordinary work.

The profile package contains full contracts for publishers and validators. Ordinary MCP `tools/list` contains only the preferred spelling, ≤100-character summary, minimal input schema, and non-default risk annotations ([02](02-descriptor.md)). Private result schemas and fixtures MUST NOT be emitted into model context merely because they exist.

Profiles MUST make the common path short:

- An omitted optional argument takes its profile-defined safe default; a consumer does not send ceremony.
- Discovery or observation, where present, returns the opaque identifier and exact semantic data needed for the next valid call.
- Default observations are bounded and decision-useful. A cursor is present only when more data exists.
- Consequential verbs return only the current state identifier and facts that change the next decision. Default success, empty collections, echoed requests, and repeated provenance are omitted.
- Expected ambiguity or staleness returns one structured blocker with only the bounded recovery data available when the profile defines such a blocker. Blockers reuse MCP's shapes and MUST NOT invent a parallel convention: a blocker that needs **caller input** to proceed is a multi round-trip result (`resultType: "input_required"`); a blocker that reports an **expected environmental condition** is a tool execution error carrying bounded recovery data ([05 §5](05-kernel.md#errors)).
- Native MCP content blocks carry media; profiles do not wrap images, audio, or resources in parallel payload conventions.

The mechanism is **fluency, not enforcement.** A profile is a language an agent learns once and then speaks to every implementation of it. This specification does not police callers; it removes the need to work anything out. A caller that knows the language does not form the wrong call, and a caller that does not know it pays the ordinary tax of unfamiliarity — reading prose, inferring shapes, discovering limits by failing. That tax is the incentive, and it is a gradient rather than a gate: an implementation is cheaper to call in proportion to how much of its surface is in a known language.

The delight test applies on every shore, and the shores are **not independent** — each one's benefit is produced by the one before it:

1. **A publisher's server is called correctly.** Not because wrong calls are blocked, but because a fluent agent does not compose them. The publisher also describes a class without schema surgery, and inherits a manual that already exists rather than competing for attention with a vendor-specific one.
2. **An agent spends less on inference.** Recognition replaces derivation. It knows the shape of the next call, what is absent, and whether a retry is safe, because it learned the class — not this server.
3. **A person gets a better outcome.** The agent's attention goes to the job rather than to translation, so the work is faster, cheaper, and wrong less often.

The chain matters more than any single link: because it runs publisher → agent → person, **one publisher adopting a profile produces benefit at all three shores without anyone else participating.** That is what zero-knowledge compatibility (§1) is for — a conformant server is easier to call correctly even by a client that has never heard of this specification.

This is fixture-tested ([03](03-conformance.md)).

<a name="non-goals"></a>
## 10. Non-goals

- **Not a registry, installation manager, or account router.** This draft defines capability meaning and proof, not how implementations are found or selected.
- **Not a fork or extension of MCP semantics.** Where MCP standardizes something shimmed here, the shim migrates to it.
- **Not an ontology.** A handful of verbs per class for real jobs, not a universal taxonomy of capability.
- **Not an enforcement regime.** Fixtures verify behavior; trust decisions such as pairing, consent, and RBAC belong to hosts and gateways at the boundary.