The Anatomy of a Capability — and the Protocol Shift

A capability has four orthogonal parts: Manifest, Surface, Kernel, Guardrails. The protocol underneath is shifting — and REST is fading.

Watch the episodeHire the AI Agent | SaaC, the End of SaaSThe Software Lens on YouTube →

"A capability is a publishable, monetizable unit of software — not an endpoint, not an app."

The four parts

A capability has exactly four structural parts. They are orthogonal; each is load-bearing; changing one requires re-examining the others. The diagram shows them as a 2×2 grid. They are:

• Manifest — who I am · what I promise · how to call me
• Surface — how callers reach me
• Kernel — what I actually do
• Guardrails — what I refuse to do

The rest of this article walks each part with reference to Nexcubator's retention.analyze capability — an internal-facing capability used by the HR agent to produce retention-risk analyses for specific employees or teams.

Manifest

The manifest is the capability's declaration of identity. It is a machine-readable document — typically JSON or YAML — that describes:

• Identity. id, version, owner, classification.
• Description. A semantic, agent-readable explanation of what the capability does. Not "a function that returns a score"; more like "assesses retention risk for an employee based on their tenure, recent manager changes, team health signals, and market-comp deltas, producing a score 0-100 and a recommended-action list."
• Schemas. Input and output JSON schemas, with examples.
• Cost model. Per-invocation price, per-user budget, per-capability monthly cap.
• SLA. P50 latency, P99 latency, availability commitment.
• Quotas and rate limits.
• Region and compliance scope. Which regions the capability may execute in; which data-residency classes it honours.
• Example invocations. Three to five end-to-end examples of call and response, with brief narration. Agents reason about these examples at discovery time.
• Owner contact. On-call team, escalation path, documentation root.

A good manifest is 2–4 pages of YAML. A bad manifest — one agents cannot reason against — is an OpenAPI spec with no semantic description. The difference is felt immediately in how well agents compose the capability.

The manifest is not a new invention; it is the convergence of several lineages. WSDL carried the contract in SOAP's era. OpenAPI carried it for REST. Kubernetes CRDs carried it for declarative infrastructure. Each of these was shaped for its caller: WSDL for tool-generated clients, OpenAPI for human-integrated clients, CRDs for operators. The capability manifest is shaped for reasoning callers, which adds three things its predecessors lacked — a semantic description dense enough to support tool-choice reasoning, explicit economic terms (cost per invocation, budget caps), and runtime negotiation (region, scope, SLA tier). The discipline to keep manifests short and complete is the manifest author's core craft.

Nexcubator's retention.analyze manifest (abbreviated):

Listing 1 — retention.analyze capability manifest (YAML).

id: nexcubator.retention.analyze
version: 2.3.1
owner: team-hr
classification: internal
description: |
  Assesses retention risk for an employee based on their tenure, recent manager
  changes, team health signals, and market-comp deltas. Returns a risk score
  (0-100), three top contributing factors, and three recommended actions
  calibrated to the employee's role and tenure.
surfaces:
  mcp:
    endpoint: mcp.nexcubator.io
    tool_name: retention.analyze
    session_context: persistent
  rest:
    endpoint: https://api.nexcubator.io/v2/capabilities/retention.analyze
    openapi: /specs/retention.analyze.v2.yaml
  async:
    bus: eventbridge
    trigger_events: [hr.signal.manager-changed, hr.signal.comp-delta]
kernel:
  provider: bedrock-agents
  model: claude-sonnet-4.6
  model_version_pin: "2026-02-14"
  temperature: 0.2
  max_tokens: 2048
  memory_strategy: stateless_with_tier2_retrieval
  sub_capabilities:
    - hrm.get_employee_profile
    - hrm.get_team_health
    - hrm.check_consent
schemas:
  input:
    type: object
    properties:
      employee_id: { type: string }
      scope:       { enum: [individual, team] }
    required: [employee_id]
  output:
    type: object
    properties:
      risk_score:           { type: integer, minimum: 0, maximum: 100 }
      confidence:           { enum: [low, med, high] }
      factors:              { type: array, items: { type: string } }
      recommended_actions:  { type: array, items: { type: string } }
      referenced_learnings: { type: array, items: { type: string } }
cost:
  per_invocation_usd: 0.18
  per_caller_daily_cap_usd: 10.00
  monthly_cap_usd: 2500.00
cost_model:
  billed_on: successful_invocation
  retries_billable: false
  guardrail_rejections_billable: false
guardrails:
  pii:
    strategy: redact_on_output
    redacted_fields: [employee_name, direct_email, phone]
  groundedness:
    min_evidence_items: 3
    low_evidence_action: downgrade_confidence
  denied_topics: [protected_class_membership, medical_inference]
  budget:
    enforce: true
    on_exceed: reject_with_error
sla:
  p50_ms: 850
  p99_ms: 2200
  availability: "99.9%"
  error_budget_monthly_seconds: 262
region:
  allowed: [eu-west-1, us-east-1]
  data_residency: follows_employee_record
region_policy:
  cross_region_calls: deny
  eu_employee_us_caller: redact_and_downgrade
examples:
  - input:  { employee_id: "E-10482", scope: "individual" }
    output: { risk_score: 62, confidence: "medium", factors: [...], ... }
owner_contact:
  team: team-hr
  escalation: hr-oncall-pagerduty
  docs: https://docs.nexcubator/caps/retention.analyze

Read top to bottom, the manifest tells a complete story. Identity — who owns it, what version it is, whether it is internal or external. Surfaces — three ways in, all honouring the same semantics. Kernel — the reasoning core, with a pinned model version so that behaviour is reproducible; a temperature low enough to favour consistency; a sub-capability list the agent may compose. Schemas — input/output contracts, strongly enough described that a caller agent can construct valid payloads without trial and error. Cost and cost model — not just the unit price, but the rules for what counts as billable, which is where most pricing disputes originate. Guardrails — declarative, not imperative, enforced at the boundary. SLA — with an explicit error budget so the team knows how much downtime is allowed before an incident review fires. Region and region policy — both what is allowed and what to do in edge cases. Examples and owner contact — the human-reasonable seams, for debugging and for escalation.

Every field earns its place. A manifest with fewer fields fails to carry the contract; a manifest with more fields drifts into configuration sprawl. The pattern-literate team treats the manifest like a database schema — additions are reviewed, deletions are migrated, renames are never silent. The manifest is the contract the capability makes with the world, and it is versioned with the seriousness of a contract.

A practical editorial note about manifest authorship. The description field is the single most load-bearing piece of prose in the entire capability, because it is what an agent reads at tool-choice time. Three disciplines help. First, describe behaviour, not implementation — an agent choosing between retention.analyze and retention.snapshot needs to know what each returns and when to prefer one, not which model family either of them uses internally. Second, show an example of when to call it and when not to — the shortest way to teach an agent the edges of a capability's competence is to list both. Third, keep it under three hundred words — a description that runs longer bleeds tokens on every tool-choice step and, empirically, does not improve selection accuracy beyond diminishing returns. Treat the description as microcopy for a reasoning system; the craft is closer to writing a good error message than writing a marketing page.

Surface

The surface is how callers actually reach the capability. A capability typically has multiple surfaces, each honouring the same manifest:

• MCP server. The primary agent-facing surface. Exposes the capability as an MCP tool; handles discovery, invocation, and result routing.
• HTTPS / gRPC endpoint. The service-facing surface. For callers that integrate at the service level rather than the agent level.
• Event-bus handlers. For asynchronous invocation — a signal arrives, the capability is triggered without a request/response round-trip.
• Webhook registry. For third-party systems that push into the capability (e.g., GitHub webhooks firing on PR events).

Every surface implements the same manifest-defined semantics. The surface does not add or remove functionality; it only changes how the capability is reached. This orthogonality is what makes capabilities composable across different caller contexts.

When a surface drifts — when, for example, the REST surface starts accepting a field the MCP surface does not, because a customer requested a quick extension — the capability is no longer orthogonal. It has become three capabilities sharing a name, which is the single worst place a SaaC platform can arrive. The discipline that prevents this is to treat the manifest as the source of truth for every surface; surfaces implement the manifest, they do not extend it. Extensions go into the manifest first, ship through all surfaces, and only then do callers see them.

For retention.analyze, the surfaces are:

• MCP: mcp.nexcubator.io exposes retention.analyze as a tool.
• HTTPS: https://api.nexcubator.io/v2/capabilities/retention.analyze — OpenAPI-described.
• Event-bus: subscribes to hr.signal.manager-changed events and auto-triggers analysis.

Kernel

The kernel is what the capability actually does. It is the reasoning-and-execution core: the agent (if any), the code, the tools it composes, the memory strategy it uses.

For agent-based capabilities like retention.analyze, the kernel is a Bedrock Agent with:

• Model. Claude Sonnet 4.6 (swappable).
• Instruction set (system message). The Nexcubator HR retention agent's detailed instructions — conservative reasoning, factor-listing, recommendation-producing.
• Memory strategy. Stateless per-call; retrieves from the three-tier Knowledge Store for context.
• Sub-capabilities. hrm.get_employee_profile, hrm.get_team_health, hrm.check_consent, plus retrieval tools.
• Side effects. Emits a retention.assessed signal on completion, for the OKL write-back.

For non-agent capabilities — many crm.* and finance.* tools are pure-code — the kernel is simply the code. The pattern is the same: inputs via the manifest, outputs via the manifest, side effects explicit.

The kernel's model version pin deserves particular discipline. It is tempting to let the kernel float to "the latest model" — vendors release improved models frequently and the upgrade usually looks free. It is not free. A silently upgraded kernel can change behaviour in ways that invalidate evaluation results, break calibration on confidence scores, and shift cost curves without the finance team knowing. The pattern-literate team treats model upgrades the way database teams treat engine upgrades: staged, shadow-tested against the evaluation harness, promoted on passing metrics, rolled back on regression. A kernel is a dependency; its version is part of the manifest; the capability's behaviour is a function of that pinned dependency as much as of the code that surrounds it.

Guardrails

Guardrails are what the capability refuses to do. They are enforced at the capability boundary, not inside the kernel, so a bug in the kernel cannot bypass them.

For retention.analyze, the guardrails include:

• PII redaction. Input and output are scanned; employee names are redacted in outputs (role/tenure references retained). If the caller is a cross-regional caller, additional redaction applies.
• Denied topics. The capability refuses to produce outputs that characterize protected-class membership, even as an input factor.
• Ground-truth checks. The Auditor-equivalent at capability level: if the risk score is above 80 but the evidence is thin, the capability emits a warning rather than a confident verdict.
• Cost caps. Per-caller and per-capability budgets are enforced. Calls that would exceed budget are rejected with a machine-readable error.
• Regional and compliance scopes. The capability refuses to process employees whose data-residency class forbids analysis in the current execution region.

Guardrails are declarative, versioned, and audited. Every triggered guardrail is logged; monthly evaluation runs verify the guardrails are still effective against current threat models.

The cultural point to stress is that guardrails are not the kernel's responsibility. A kernel that is also responsible for its own restraint is one refactor away from self-exception. By pushing guardrails to the capability boundary — enforced by infrastructure the kernel cannot see, let alone modify — the architecture gains a property that is easy to underestimate until an incident review needs it: the post-mortem can separate kernel failure from guardrail failure. If the kernel produced a bad answer and the guardrails caught it, the system worked as designed. If the kernel produced a bad answer and a guardrail let it through, the guardrail is the bug. This separation is the same design principle that made CPU protection rings, filesystem permissions, and network firewalls durable: the restraint lives outside the thing being restrained.

The four parts, in synthesis

The Manifest declares identity; the Surface exposes access; the Kernel performs the work; the Guardrails enforce limits. These four are orthogonal because changing any one does not inherently require changing another — the kernel can be replaced (e.g., model swap) without touching the manifest; a new surface can be added (e.g., a gRPC endpoint) without touching the kernel.

They are load-bearing because removing any one produces a broken or unsafe capability. A manifest without a kernel is a brochure. A kernel without a surface is un-callable. A capability without guardrails is a liability. A capability without a manifest is invisible to agents.

The four-part structure also gives the organization a clean division of labour. Manifest changes are owned by the capability product manager, because they carry external commitments — SLA, cost, scope. Surface changes are owned by the platform team, because they are about how callers reach the capability without changing what it does. Kernel changes are owned by the capability's engineering team, because they are where the reasoning and execution live. Guardrail changes are owned by the security and compliance function in partnership with the capability team, because they are about what the organization refuses to do. When these ownership boundaries are respected, the capability can evolve on four independent axes without producing coordination deadlock. When they are blurred, every change requires everyone's agreement, and the capability stops evolving.

Versioning

Capabilities version independently from their consumers. The manifest's version field follows SemVer:

• Patch version (2.3.1 → 2.3.2): bug fixes, latency improvements, guardrail tightening that does not break honest callers. Backward-compatible.
• Minor version (2.3.1 → 2.4.0): new optional input fields, new output fields. Backward-compatible.
• Major version (2.3.1 → 3.0.0): breaking schema change, kernel replacement with different semantics, guardrail change that rejects previously-accepted calls. Not backward-compatible; old callers continue on the old version for a grace period (typically 6 months).

Nexcubator's MCP server exposes multiple major versions simultaneously; minor and patch are resolved to the latest.

Version coexistence is enforced at the surface layer: a caller binds to a major version at connection time, and all subsequent calls inside that session resolve against that major. This prevents a subtle failure mode in which a long-running agent session silently crosses a major boundary mid-reasoning — the same bug that plagues library consumers in language ecosystems without deterministic lockfiles. The manifest is, in effect, a lockfile for organizational competence, and the capability platform is its resolver.

With the four-part anatomy named, the next question is what protocol carries a capability over the wire. The anatomy answers what a capability is; the second half of this article answers how it speaks. REST won the SaaS era; MCP fits the agentic one.

REST — the vernacular that won

REST — Representational State Transfer, formalized by Roy Fielding's 2000 dissertation — won the service-era protocol war for one reason: it was simple enough to be adopted without a committee. XML-RPC was adequate; SOAP was over-engineered; gRPC was not yet widely deployable across public networks; GraphQL was still a decade away. REST, with JSON payloads and HTTP verbs, was the right level of ceremony for a network of human-integrated services.

REST's assumptions match the SaaS-era caller exactly. The caller is a human developer who reads the docs, integrates once, and operates for three years. The verbs — GET, POST, PUT, DELETE — correspond to intents a human programmer expresses cleanly in code. The surface is stable and browsable.

It is worth remembering, because protocol debates tend to forget it, that REST won in large part by being teachable. A developer encountering REST for the first time could explain it back to a colleague in five minutes. The mental model fit the HTTP the developer already knew. Curl was the debugger. A browser was the browser. Protocols that lose the teachability race do not recover it later, no matter how strong their typed-contract story. The challenge for any successor protocol is not only to beat REST on capability but to approach REST on teachability. MCP's early adoption curve is promising partly because its JSON-RPC underpinning and its manifest-first discovery model can be explained in a single diagram.

Why REST fades in the agentic era

Every assumption REST depended on erodes under agentic callers.

Erosion 1 — Discoverability. REST APIs are discovered through documentation, which is human-readable, not agent-reasonable. OpenAPI narrows the gap but does not close it; the semantic hints agents need live around the schema, not inside it.

Erosion 2 — Composition. Each REST call is independent; the agent has to maintain its own multi-call state. Context is re-built each call; tokens burn. A protocol shaped for agent-level composition can fuse multi-step workflows into single sessions.

Erosion 3 — Typing. REST's JSON payloads are not strongly typed at the protocol level. The agent reasons its way to payload structure; mis-types cost retries. Protocols with stronger schema enforcement at handshake time reduce the retry tax.

Erosion 4 — Streaming and async. REST's request/response is a limited fit for streaming outputs (which agents produce) and long-running operations (which agents initiate). Workarounds exist — long polling, SSE, webhook callbacks — but are ad hoc.

REST will not disappear. It is deeply entrenched, and for many use cases it remains adequate. But it will become one protocol among several rather than the protocol. The next decade is polyglot.

A side-by-side on where each protocol earns its keep helps place the shift:

The table should not be read as REST losing on every row. It is losing on rows that matter for agent callers and holding its ground on rows that matter for human-integrated callers. Both cohorts persist; the protocol split follows the caller split.

gRPC — the contract-first survivor

gRPC, introduced by Google, is REST's structurally-stronger cousin: Protocol-Buffer-typed schemas, HTTP/2 transport, bidirectional streaming, and first-class contract generation. Its adoption has been steady but niche — mostly internal service-to-service within platform teams that can tolerate its tooling requirements.

In the agentic era, gRPC's strengths — typed contracts, streaming, lower overhead — become more valuable. Agent-to-service composition benefits from stronger typing. gRPC will grow its share of the surface, particularly for platform-internal agentic traffic where tooling homogeneity is manageable.

The cost of gRPC remains real. It requires a contract-first workflow, a Protocol-Buffer toolchain, and a client-generation discipline that many teams find heavier than the REST-and-OpenAPI default. Its browser story, historically awkward, has improved with gRPC-Web but is still not the no-friction default that fetch-plus-JSON provides. These tradeoffs explain why gRPC is unlikely to replace REST at the edge of the public internet, even as it earns a larger share of the platform-internal traffic. The architect's job is not to pick a single winner but to match protocol to role.

JSON-RPC — the simple specialist

JSON-RPC is a minimal request/response protocol over JSON — simpler than REST, more uniform than REST, lacking REST's noun-and-verb ceremony. It is the protocol MCP is built on top of. For agent-to-tool invocation, JSON-RPC is the right baseline: call a method by name, pass typed arguments, receive a typed result.

MCP — the standard for agent-tool invocation

MCP (Model Context Protocol) is not one more protocol competing with REST. It is a protocol specifically designed for the interaction between agents and tools. Its structural properties:

• Manifest-first discovery. MCP servers advertise their tools with rich, semantic manifests. Agents read the manifests at connection time; tool-calling is guided by structured metadata.
• JSON-RPC transport. Simple, uniform, implementable in any language.
• Caller-agnostic. Any MCP-aware agent from any vendor can invoke any MCP server.
• Scoped capabilities. Each connection authenticates into a scope; tools can be advertised conditionally per caller.
• Session-level context. An MCP session can maintain context across tool invocations, which matches how agents reason.

The question for an architecture team in 2026 is not "REST or MCP?" — it is "which surfaces of which capabilities should be exposed via MCP, and which should remain REST-or-gRPC?"

It is also worth being explicit about what MCP is not. MCP is not a kernel — it does not execute reasoning on your behalf; the agent does that. MCP is not a guardrail — guardrails live at the capability boundary, not the transport layer. MCP is not a billing system — billing lives in the manifest and the platform's metering. MCP is not a replacement for your service mesh, your API gateway, or your observability stack; it rides on top of them. Treating MCP as the answer to all three layers is the fastest way to build a brittle architecture. It is a specialist: a protocol for agent-to-tool interaction, and nothing more.

The SOA → MCP mapping

For teams familiar with SOA vocabulary, the mapping is straightforward:

The concepts port; the mechanics change. SOA architects who internalize this mapping re-gain their bearings quickly.

What ports less cleanly is the operating discipline. SOA's lineage — especially its ESB-era — over-indexed on centralization: one bus, one registry, one orchestration engine, one team owning the integration surface. The agentic era inherits the vocabulary but inverts the shape. Agent orchestration is distributed: any agent can be an orchestrator, and composition is a runtime reasoning act rather than a designed flow. Capability catalogues are federated: an MCP server publishes its own manifest and registers into a discovery surface, but there is no single authoritative bus. SLA negotiation is per-call at L4, not per-contract at signing time. The SOA concepts survive; the SOA governance does not. An architect who ports the vocabulary without porting the inversion will build a centralized bottleneck and blame the agents for its failure.

Nexcubator's protocol policy

Nexcubator's protocol policy settles on polyglot with clear defaults:

• Agent-to-tool (internal or external): MCP, primary. JSON-RPC envelope over HTTPS.
• Service-to-service (platform-internal, high throughput): gRPC. Typed contracts, stream-friendly.
• Service-to-customer-API (legacy integrations): REST with OpenAPI. Unchanged.
• Event-driven (internal): EventBridge + SQS. Not protocol-like; it is infrastructure.
• Agent-to-UI: Streaming HTTP (SSE) for incremental responses.

Each capability's manifest declares which surfaces are available. Customers can pick the one that matches their integration posture.

The migration plan

Nexcubator's migration unfolds over four quarters:

• Q1: Publish the internal MCP server; all new capabilities ship MCP-first.
• Q2: Wrap all existing REST capabilities at L1 — MCP-described, MCP-callable.
• Q3: Promote highest-traffic capabilities to L2 — full manifest, native MCP kernel, deprecate REST surface (still supported for 12 months).
• Q4: External-facing MCP endpoint becomes the primary customer-agent surface. REST remains available with clear depreciation schedule.

Q1 in practice. The platform team stands up a single internal MCP server, routed through the same gateway that fronts the REST estate. It advertises an initially small tool set — three or four of the capabilities most commonly composed by internal agents. The team instruments the MCP server from day one: every discovery handshake, every tool call, every error envelope is logged at the same fidelity as the REST traffic. A quiet rule: no capability shipped during Q1 uses REST as its primary surface; REST exists if needed, but MCP is the default, and adoption is measured in MCP-call-share. By the end of Q1, MCP-call-share is in the low single digits, which is the correct expectation for a new protocol with few callers.

Q2 in practice. The wrap campaign begins. Every existing REST endpoint receives a thin MCP wrapper that forwards calls, translates payloads, and — critically — attaches a minimal manifest with semantic description and example invocations. The wrappers are intentionally cheap; the goal is discoverability, not reimplementation. Internal agents that previously had to be taught individual REST URLs now discover the tools through MCP and compose them. MCP-call-share rises into the double digits. Failure cases are catalogued: which wrappers leak REST quirks through MCP, which manifests are too thin for agents to reason against, which endpoints cannot be safely wrapped without a proper L2 promotion. That catalogue becomes the Q3 backlog.

Q3 in practice. The top-traffic capabilities — the ones whose MCP-call-share is already dominant — are promoted to L2. This is not a cosmetic change. Each L2 promotion builds a full manifest, migrates the kernel to native MCP semantics rather than a REST passthrough, wires in guardrails at the capability boundary, and publishes cost and SLA terms. The REST surface is not deleted; it is marked deprecated with a 12-month support window, and new callers are nudged toward MCP via deprecation headers and developer-portal guidance. Internal adoption accelerates because L2 capabilities compose more cleanly than L1 wrappers. The error budget for REST begins to narrow: outages on deprecated REST surfaces are acknowledged but not prioritized above MCP parity work.

Q4 in practice. The external-facing MCP endpoint is opened to customer agents, guarded by the same authentication, rate-limiting, and scope negotiation the internal server proved out in Q1–Q3. Customer communications make the deprecation schedule explicit: REST remains available for twelve months, security patches only for the last six, full sunset on a published date. The sales team learns the new pitch — your agents can compose these capabilities directly — and the developer-relations team publishes migration guides. MCP-call-share crosses 50% by the close of Q4 for the L2 portfolio. Critically, no customer is forced to migrate during Q4; they are enabled to migrate. That distinction is what keeps a protocol migration from becoming a churn event.

At the end of Q4, the REST surface still exists but is not the default caller path. The agentic callers use MCP; the human-developer integrations that need REST still get it. Polyglot by design, not polyglot by accident.

Synthesis

REST is not dead; it is becoming one protocol in a polyglot layer. gRPC grows in high-throughput platform-internal roles. JSON-RPC and MCP win the agent-to-tool interaction. SOA vocabulary ports one-to-one. Nexcubator's protocol policy is polyglot-with-defaults. The migration takes four quarters and is worth the cost. With protocols in hand, the next question is where each capability sits on the maturity ladder — the subject of the next article in this series.

The protocol shift is often mis-read as the centrepiece of the agentic transition. It is not. The centrepiece is the delivery model — capabilities as the unit of sale, manifests as the unit of contract, OKL as the unit of compounding. Protocols are the pipes. Pipes matter, and picking the wrong pipe costs years, but the interesting architecture is the one the pipes connect. A team that gets the protocol right and the capability model wrong has a fast pipe to nowhere. A team that gets the capability model right will evolve its protocol stack as needed; polyglot is a durable answer because it admits that no single pipe wins forever.

← Back to The Software Lens library