Blog

Five Fragmented Specs, One Ikanos Capability

Jerome Louvel ·August 13, 2026

Table of contents

There is a question every integration platform has to answer, and most answer it implicitly: what, exactly, gets delivered?

For an iPaaS, the answer is a workflow. For a connector marketplace, an entry in an inventory. For the newer agent-integration vendors, increasingly, generated code. For Naftiko’s Agentic Integration Platform, the answer is a capability — and the reason we can give that answer at all is the Ikanos Spec sitting underneath everything else.

This post is about why that spec exists, what it borrows from the specs you already use, and what shipped across the 1.0 Beta 3 release train.

Five specs, three jobs, no unit

The specification landscape is not short of good work. It is short of a unit that spans it — and it has quietly split into groups that do not talk to each other.

Some describe how you call an API. OpenAPI answers what is this API? — endpoints, schemas, auth, the contract that generates your SDKs. Postman collections and Open Collection answer how do I actually run this? — requests you can fire, environments, tests. Both are mature, well-adopted, and pointed firmly at the upstream systems you depend on.

One describes how calls compose. Arazzo answers how do these calls combine into something meaningful? — multi-step sequences, dependencies between steps, data flowing from one call into the next, success and failure criteria. It is neither the upstream API nor the thing you offer downstream; it is the composition in the middle, and it is the only one of the five that lives there.

The rest are new, and point the other way. MCP describes how a tool surface is offered to a model — tools, prompts, resources, and the hints that say whether calling something is safe to repeat. SKILL.md describes how an agent should use those tools: the procedural knowledge, the workflow, the judgement a tool list never conveys.

All five are good. The awkwardness is that a single piece of integration work now needs items from all three groups — and they were designed by different communities, at different times, for different readers. So you end up with an OpenAPI document for the upstream API, a collection to test it, a workflow description for the sequencing, an MCP server implementation to expose it, and a SKILL.md to explain it. Five artifacts, one integration, drifting apart at five different speeds.

And there is a question none of them answers, because it was never any single one’s job:

What does this unit of functionality consume, how does it compose that, and what does it expose?

Those three questions are not separate concerns that happen to sit near each other. They are one decision, viewed from three angles. Splitting them across five documents means nobody can review the decision.

What Ikanos takes, and what it adds

The Ikanos Spec is not a rejection of that prior work — the specification explicitly credits OpenAPI, Arazzo and OpenCollections for the patterns it builds on. It is an attempt to raise the strengths of all five into one artifact whose unit is the capability. And it maps them onto exactly three top-level fields.

`consumes` — the upstream half

From OpenAPI, the schema discipline. Inputs and outputs are typed and described. And the relationship is concrete rather than philosophical: Ikanos ships bidirectional OpenAPI conversion. ikanos import openapi turns an existing contract into a consumed source; ikanos export openapi projects a capability’s REST adapter back out as an OpenAPI 3.0 or 3.1 document. Your existing specs are an input, not a thing you abandon.

From Open Collection, the executability. An Ikanos spec is not documentation about a running system — ikanos serve is the running system. There is no generated project to maintain alongside the description, and therefore nothing to drift.

`aggregates` — the composition in the middle

From Arazzo, the flows. This is its own top-level field, and deliberately so. An aggregate is a namespaced group of named flows, and each flow declares its steps, how values map from one step’s output into the next, and the semantics of what the flow actually does. That is the Arazzo idea — sequencing, dependencies, data flow between calls — expressed as a first-class part of the capability rather than a second document describing it from outside.

The payoff is reuse. A flow is defined once and referenced by any adapter that needs it, so the same composition can back a REST endpoint and an MCP tool without being written twice. And because the flow declares its semantics, the linter can check that they stay consistent with the MCP tool hints and REST methods it projects to — a read-only flow should not be surfacing as a mutating tool.

`exposes` — the downstream half

From MCP, the agent-facing surface. exposes includes a first-class MCP server type: tools, prompts and resources, declared in the same YAML. Tools carry readOnly and idempotent hints, so a caller — human or agent — can tell the difference between “safe to probe while figuring out what to do” and “call this once, deliberately.” You are not writing an MCP server; you are declaring one.

From SKILL.md, the procedural layer. Ikanos exposes a skill catalog adapter that serves skills and their tool groupings over HTTP — listing available skills, their metadata and tool catalog, and their downloadable contents. Tools alone tell an agent what exists; a skill tells it how the work is done. Both now come from the same source document.

Alongside both, every capability carries an info block — label, description, tags, stakeholders with their roles, created and modified dates. This is the discovery metadata that lets a capability be found, filtered, attributed to an owner and catalogued, and the linter treats it as load-bearing rather than decorative: a capability with no description and no tags is invisible to exactly the agents meant to discover it.

That is the point people underestimate. A capability projects to REST, MCP and skills from a single declaration — so the tool an agent calls, the endpoint a service calls, and the skill a human reads are guaranteed to describe the same behaviour, because they are generated from the same lines.

Why the unit matters more than the format

It would be easy to read all of the above as a format preference — five things merged into one, tidier. It is not. Consolidation is the side effect. The point is that the artifact becomes reviewable.

A declarative capability can be exhaustively reviewed without being executed. Every upstream operation, every flow, every exposed tool, every credential binding — declared in binds as named keys resolved from a vault, a file or the environment, never inlined — is enumerable by reading the document. There is no control flow to reason about, because the surface is the artifact.

That property is what the alternatives cannot offer. A connector inventory is sized for the upstream API rather than for the task. A unified API normalises toward a category’s common denominator, dropping precisely the domain-specific parts you cared about. Generated code cannot be statically proven right-sized, because working out which endpoints a piece of TypeScript will actually call — with computed URLs, branching, and a transitive dependency tree — is not a tractable analysis. You find out in production telemetry.

It also matters that all three halves are in the same document. Reviewing an MCP server implementation tells you what tools exist, but not what they reach upstream. Reviewing an OpenAPI document tells you what an API offers, but not which of it you actually exposed to an agent. Reviewing a workflow tells you the sequence, but not what authorises it. When a reviewer can see, in one file, that this tool runs that flow, which calls exactly these three upstream operations under that credential, the approval gate finally sees the same surface production will.

That is not a formatting argument. That is the argument.

What shipped in 1.0 Beta 3

The Beta 3 train landed on 6 August 2026, pinned by the 1.0.0-beta3 Fleet tag (codename Brigantine) — the umbrella release that fixes a known-good combination of component versions across Ikanos, Polychro, Crafter, Warden, Skipper and the Shipyard docs.

Broken spec? It now points you to the exact line. JSON Schema violations previously came back with a JSON path and no source location — you were told $.capability.consumes[0].baseUri was wrong and left to find it yourself. Polychro now resolves every schema diagnostic through the document’s source map, so schema errors carry a precise line and column range, exactly like the rest of the engine’s diagnostics already did.

That fix travels further than it looks. Since Beta 1, Crafter — the VS Code extension — has run validation through a bundled Polychro native binary rather than a separate engine, so the moment Polychro learned to report ranges, the editor started drawing squiggles under the offending line instead of reporting an error with nowhere to point. One commit in the linter, and the authoring loop in the editor gets tighter for free. That is the release train working as intended.

Two other changes worth calling out for anyone running capabilities in anger:

Credential resolution now has one source of truth. Server and client adapters resolve binding variables through the same mechanism — the capability’s own binds. Outgoing requests correctly carry their authentication headers. If you hit auth edge cases on Beta 2, this is your upgrade.
204 No Content responses are handled properly, which removes a class of surprising failures when consuming APIs that use them for deletes and updates.

The engine also moved to the current MCP protocol revision, keeping exposed tools aligned with what today’s clients expect.

Polychro and Ikanos continue to ship in lockstep. That is deliberate and it is the point of a release train: the schema the linter validates against is the same schema the engine parses, published from the same source. When Polychro flags something, Ikanos will agree with it — and Crafter shows you both without leaving the editor.

Guidance, not just validation

Because Polychro validates against a capability model rather than a generic document schema, the rules can be about design rather than syntax. The shipped Ikanos ruleset checks things like:

Namespaces are globally unique across every adapter and binding
info.tags is present and non-empty — because empty tags hurt discoverability for the agents that will consume this
Consumed sources, exposed resources and operations each carry a description
OAuth2 authorisation servers use https://, and scopes are actually declared
Aggregate flow semantics stay consistent with the MCP tool hints and REST methods they project to
Control adapters bind to localhost rather than a public interface
baseUri does not still point at example.com from whatever you copied it from

None of these are schema violations. They are the review comments a careful colleague would leave, encoded once and applied everywhere.

Where to start

If you are new to this, the path is short:

Write one capability. Wrap a single API you already call by hand. Declare what you consume and what you expose. ikanos create capability gives you the skeleton.
Lint it. Run Polychro — or just author in Crafter and watch the diagnostics appear inline, now with schema errors landing on the right line.
Run it. ikanos serve and the same file is live — as an MCP server, a REST endpoint, a skill catalog, or all three. Point an inspector or an agent at it.
Then grow. ikanos export openapi if you need to hand a REST contract to another team; aggregates when one capability starts needing another.

The smallest useful version of this is one tool around one API call. Start there.

Start with Ikanos today, and read the full changelog for what’s new.

Further reading