Use Cases¶

Here is an overview of typical use cases where Ikanos helps developers and platform teams deliver Spec-Driven Integration at runtime — consuming upstream systems, orchestrating flows, and exposing capabilities as REST resources, MCP tools, and agent skills from a single declarative contract. Additional capabilities are being added as described in the Ikanos roadmap.

1. AI integration¶

Connect AI assistants to your systems through capabilities, so they can access trusted business data and actions without custom glue code.

How the Ikanos engine achieves this technically: - Declare upstream systems in capability.consumes (typically type: http) with namespace, baseUri, authentication, headers, and operation contracts that Ikanos resolves at runtime. - Expose the same domain as type: mcp tools and/or type: api resources in capability.exposes, served at runtime by the Ikanos engine, so both AI agents and traditional clients use one integration layer. - Use call, with, steps, and JSONPath mapping in outputParameters to return normalized, task-ready payloads instead of raw provider responses.

Integrate AI

Key features¶

2. Rightsize AI context¶

Expose only the context an AI task needs, reducing noise, improving relevance, and keeping prompts efficient.

How the Ikanos engine achieves this technically: - Shape response payloads with typed outputParameters (string, object, array) and fine-grained JSONPath mapping expressions, executed by the Ikanos runtime. - Keep only relevant fields in exposed tool/resource schemas, while hiding irrelevant upstream fields from the AI surface. - Attach meaningful info.description, tool descriptions, and tags so discovery is semantic and context quality stays high.

Rightsize AI context

Key features¶

3. Elevate an existing API¶

Wrap a current API as a capability to make it easier to discover, reuse, and consume across teams and channels.

How the Ikanos engine achieves this technically: - Model the legacy/existing API once in consumes.resources.operations with explicit methods, paths, parameters, and body formats. - Add a stable capability namespace and expose curated resource paths/tools that are easier to consume than vendor-native endpoints — surfaced by the Ikanos engine. - Reshape not just data but also operation semantics: declare semantics (safe, idempotent, cacheable) on aggregate flows so the engine derives correct HTTP methods for REST adapters and hints for MCP tools automatically. - Rely on the capability schema (capability-schema.json) so the elevated contract stays consistent and machine-checkable before Ikanos serves it.

Elevate existing APIs

Key features¶

4. Elevate Google Sheets API¶

Wrap Google Sheets as a capability so spreadsheet rows become a reusable, domain-specific API for traditional clients and AI agents.

How the Ikanos engine achieves this technically: - Consume the Google Sheets values endpoint in consumes.resources.operations, with templated spreadsheet_id and range path parameters plus API key injection through binds. - Transform raw row arrays from $.values into named objects using positional JSONPath mappings such as $[0], $[1], and $[2] inside typed outputParameters — evaluated by the Ikanos runtime. - Expose the normalized result through type: rest, type: mcp, or both, so one spreadsheet integration serves both application and agent use cases.

Elevate GSheets API

Key features¶

Declarative Google Sheets API consumption
Templated spreadsheet ID and A1 range parameters
API key injection via externalized bind values
Declarative row-to-object transformation
Positional JSONPath mapping from array columns to named fields
Typed JSON array exposure for downstream consumers
Dual-channel exposure from one capability
REST resource exposure for conventional clients
MCP tool exposure for AI agents

5. Compose AI context¶

Combine data from multiple APIs into one capability to deliver richer, task-ready context to AI clients.

How the Ikanos engine achieves this technically: - Register multiple consumed APIs with unique namespaces, then orchestrate cross-source calls using ordered steps in the Ikanos engine. - Bridge calls through step mappings and per-step input injection, so outputs from one source feed inputs of the next. - Return a single composed output model via mapped outputParameters, giving AI clients one coherent result.

Rightsize AI context

Key features¶

6. Rightsize a set of microservices¶

Create a simpler capability layer over many microservices to reduce client complexity and improve consistency.

How the Ikanos engine achieves this technically: - Aggregate multiple microservice endpoints under one exposed namespace and a small set of business-oriented resources/tools, served by the Ikanos engine. - Standardize auth/header behavior and parameter handling at capability level instead of duplicating logic in every client. - Use orchestration and output shaping to hide service fragmentation and return consistent contracts.

Rightsize microservices

Key features¶

Declarative source HTTP adapter and target REST adapter
Support for source APIs with JSON payloads
Convert YAML, Protobuf, XML, Avro, and CSV payloads to JSON
Support sequence of steps with calls
Multiple consumed adapters per capability
Namespace-scoped auth, headers, and base URI per adapter
Unified parameter handling across microservices
Input parameters in query, header, path, cookie, and body
Regex pattern validation on string inputs

7. Rightsize a monolith API¶

Extract focused capabilities from a broad monolith API so consumers get only what they need for each use case.

How the Ikanos engine achieves this technically: - Select only required monolith operations in consumes and remap them to narrower exposed resources/tools. - Use output filtering/mapping to publish smaller, purpose-built payloads for each consumer scenario — executed by the Ikanos runtime. - Optionally forward selected routes with forward.targetNamespace to keep passthrough paths where full transformation is not needed.

Rightsize monolith APIs

Key features¶

Selective operation exposure from a broad API
Remap consumed operations to narrower exposed resources
Output filtering via typed parameters and JSONPath mapping
Forward proxy for pass-through routes
forward.targetNamespace for direct routing
Trusted header forwarding for security
Dual-channel exposure from one capability
REST resource exposure for conventional clients
MCP tool exposure for AI agents

8. Capability-driven context engineering¶

Design capabilities first for MCP clients, then map them to underlying APIs for a clean AI-native integration model.

How the Ikanos engine achieves this technically: - Define type: mcp exposure with server-level description and tool-level contracts (name, description, input/output parameters) that Ikanos serves directly. - Support MCP transports (http or stdio) through the Ikanos engine, so the same capability can run in remote server mode or local IDE/agent mode. - Wire tools to one or many consumed operations via call or orchestrated steps, without changing upstream APIs.

Capability-driven approach

Key features¶

9. Capability-driven API reusability¶

Start from existing APIs and define reusable capabilities on top, so API investments can power new AI and app experiences.

How the Ikanos engine achieves this technically: - Begin with consumed API declarations (baseUri, auth, resources, operations), then incrementally add exposed REST/MCP adapters served by the Ikanos engine. - Reuse existing security and configuration using binds with file or runtime injection and injected variables (e.g., ``). - Add format-aware parsing and mapping (JSON, YAML, XML, CSV, TSV, PSV, Avro, Protobuf, HTML, Markdown support in the framework) to normalize diverse backends.

Capability-driven approach

Key features¶

10. Interoperate with OpenAPI¶

Bridge existing OpenAPI ecosystems with Naftiko capabilities: import OAS documents to bootstrap consumption adapters, and export REST adapters as standard OpenAPI specifications.

How the Ikanos engine achieves this technically: - Import an OpenAPI 3.0 or 3.1 document (or a Swagger 2.0 document, which is auto-converted) with ikanos import openapi, generating a ready-to-use consumes HTTP adapter with authentication, operations, input parameters, and output parameters pre-filled. - Export a REST exposes adapter with ikanos export openapi, producing a standards-compliant OAS document that can be shared with API gateways, developer portals, and documentation tools. - Use --adapter <namespace> to target a specific REST adapter when the capability exposes more than one.

Key features¶

11. Monitor and debug capabilities¶

Observe capability behavior in real time with built-in metrics, distributed traces, and health checks — configured entirely from the spec.

How the Ikanos engine achieves this technically: - Add a type: control adapter in capability.exposes to expose a management plane with health, metrics, traces, and diagnostic endpoints on a dedicated port of the Ikanos engine. - Configure capability.observability to enable OpenTelemetry-based distributed tracing and RED metrics (Rate, Errors, Duration) with configurable sampling and OTLP export. - Scrape Prometheus-format metrics from the control port's /metrics endpoint and inspect recent traces via /traces — no additional infrastructure code required.

Key features¶

12. Transform data between API calls¶

Reshape, filter, or aggregate data between consumed API calls using inline script steps — without building a separate microservice or writing Java code.

How the Ikanos engine achieves this technically: - Add type: script steps in orchestrated operations to transform data between call steps using JavaScript, Python, or Groovy, executed by the Ikanos engine. - Scripts run in sandboxed environments (GraalVM for JS/Python, SecureASTCustomizer for Groovy) with no filesystem or network access. - Previous step results are bound as variables; scripts assign to result to produce output for subsequent steps or mappings. - Govern execution centrally via the Control Port's management.scripting block — set defaults, timeouts, statement limits, and allowed languages.

Key features¶

13. Replace an unstable vendor MCP server¶

Stop depending on a vendor's hosted MCP server. Consume that vendor's HTTP API directly and originate your own MCP surface, so you own the runtime — and can add the operations the vendor's server left out.

How the Ikanos engine achieves this technically: - Point a type: http adapter at the vendor's REST base URI in capability.consumes, removing the vendor's MCP server from the request path and dropping the extra MCP→HTTP hop it adds on every call. - Re-expose a type: mcp surface served by the Ikanos engine, so deployment, scaling, retries, timeouts, and HTTP cache semantics (ETag, Cache-Control) are back under your control instead of the vendor's uptime and rate limits. - Declare the operations the generic server under-modeled or skipped — a frequent example being an API's comments endpoints — as first-class aggregate flows, so the capability ceiling is the underlying HTTP API, not whatever the vendor chose to expose.

Key features¶

Direct HTTP consumption of the vendor API
Self-hosted runtime — own uptime, scaling, and version cadence
Bypass the vendor MCP transport and its extra protocol hop
Model operations the vendor MCP omitted
Add reads and writes the generic server skipped
Correct MCP tool hints derived from aggregate semantics
HTTP resilience and caching re-opened once you consume HTTP directly
ETag / Cache-Control honored on consumed calls
Externalized secrets via binds — vendor tokens never inline

14. Fuse public and private APIs into one agent surface¶

Shape the MCP surface around one agent's job, not one vendor's API. A real use case usually spans several systems — some public SaaS, some private and behind the firewall — fused into a single curated toolset.

How the Ikanos engine achieves this technically: - Register several upstreams in capability.consumes (it is an array): a public SaaS is a plain baseUri, while a private API adds a zero-trust tunnel: type: ziti block so it is reachable outbound-only with no inbound firewall rule. - Unify them in capability.aggregates as domain flows, then expose one type: mcp server with exactly the tools the agent needs — e.g. list-open-comments (public), get-linked-ticket (private Jira), notify-review-complete (public webhook). - Keep the public/private split invisible to the agent: every tool looks identical on the MCP surface regardless of whether it crosses the firewall, because the shape lives in the use case rather than in any vendor's API boundary.

Key features¶

Multiple consumed adapters fused into one MCP surface
Public SaaS via plain baseUri
Private API via zero-trust OpenZiti tunnel: type: ziti
One curated toolset shaped by the use case, not the vendor
Tools map to aggregate flows by ref
Firewall crossing invisible to the agent
Governed as a single YAML artifact
Secrets via binds; OTel traces and Prometheus metrics per tool
Reviewable in a PR and validated against the capability schema Ikanos loads

15. Originate an MCP server where none exists¶

For the silent majority of enterprise systems — legacy SaaS, internal apps, and data sources — no vendor MCP server exists and none ever will. Ikanos originates one from the underlying API, so the choice stops being "which MCP server" and becomes "agent access, or none."

How the Ikanos engine achieves this technically: - Consume a system's existing HTTP API (baseUri, auth, operations) in capability.consumes, then project a fresh type: mcp surface over it with the Ikanos engine — no upstream MCP server required as input. - Reach internal applications behind the corporate network over a zero-trust tunnel: type: ziti, turning a homegrown CRM or claims app that no vendor will ever wrap into an agent-addressable capability in one YAML file. - For non-HTTP data sources (databases, warehouses, object stores, queues), consume a thin internal HTTP facade today; direct data-port consumption is on the Ikanos roadmap.

Key features¶

MCP surface originated from an existing HTTP API
No vendor MCP server required as input
Legacy SaaS becomes agent-addressable without waiting on a vendor roadmap
Internal apps reached over a zero-trust reverse tunnel
Outbound-only OpenZiti tunnel — no inbound firewall rule
Data sources via a thin HTTP facade today
Native FILE and SQL client adapters on the roadmap