Skip to content

Ikanos — Schema — Exposes

The exposes array declares the server adapters that surface a capability to the outside world. Each entry is a discriminated object on type: — rest, mcp, skill, or control.

capability:
  exposes:
    - type: mcp
      port: 3001
      namespace: shipyard-tools
      tools: { ... }                    # keyed map by tool name
    - type: rest
      port: 3002
      namespace: shipyard-api
      resources: { ... }                # keyed map by resource name
    - type: skill
      port: 3003
      namespace: shipyard-skills
      skills: [...]
    - type: control
      port: 9090
      namespace: control
      observability: {...}

REST Expose (type: rest)

Field Required Description
type ✅ "rest"
port ✅ TCP port (1–65535)
namespace ✅ Unique identifier for this exposed API
address Hostname, IPv4, or IPv6; default 0.0.0.0
authentication Bearer, API key, Basic, Digest
resources ✅ At least one exposed resource (keyed map)

ExposedResource

resources:                              # keyed map; key IS the resource name
  ships:
    path: "/ships"
    description: "Fleet of ships"
    operations: { ... }
    # — or, for pure pass-through:
    forward:
      targetNamespace: registry

ExposedOperation (simple mode)

operations:                             # keyed map; key IS the operation name
  get-ship:
    method: GET
    path: "/ships/{imo}"
    inputParameters:                    # keyed map
      imo: { in: path, required: true }
    call: registry.get-ship
    with:
      imo_number: shipyard-api.imo
    outputParameters: [...]

ExposedOperation (orchestrated mode)

operations:
  build-manifest:
    method: GET
    path: "/manifests/{voyageId}"
    inputParameters:
      voyageId: { in: path, required: true }
    steps: { ... }                      # keyed map (see Steps page)
    mappings: [...]

Exactly one of call: or steps: must be present. Using ref: is a third option — see Aggregates.

MCP Expose (type: mcp)

Field Required Description
type ✅ "mcp"
port ✅ TCP port (omit for stdio transport)
namespace ✅ Unique identifier
transport "http" (default) or "stdio"
description Server-level description shown to MCP clients
authentication Bearer or API key
tools MCP tools (keyed map by tool name)
resources MCP static resources
prompts MCP prompt templates

McpTool

tools:                                  # keyed map; key IS the tool name
  get-ship:
    description: "Retrieve a ship's details by IMO"
    inputParameters:                    # keyed map
      imo: { type: string, required: true, description: "IMO number" }
    call: registry.get-ship
    with: { imo_number: shipyard-tools.imo }
    outputParameters:
      - type: object
        properties:
          imo:  { type: string, mapping: "$.imo_number" }
          name: { type: string, mapping: "$.vessel_name" }
    hints:
      readOnly: true
      idempotent: true

Mock-mode tools omit call:, with:, and mapping: — they declare outputParameters with literal or Mustache-templated value::

tools:
  greet:
    inputParameters:
      who: { type: string, required: true }
    outputParameters:
      - { name: message, type: string, value: "Hello, {{who}}!" }

MCP transport

transport Listens on Use case
http (default) TCP port Remote MCP clients, AI gateways
stdio stdin/stdout Local IDE/agent integrations

Skill Expose (type: skill)

- type: skill
  port: 3003
  namespace: shipyard-skills
  skills:                                 # keyed map; key IS the skill name
    fleet-ops:
      description: "Fleet management tools"
      tools:                              # keyed map; key IS the tool name
        list-ships:
          from: { sourceNamespace: shipyard-tools, action: list-ships }

Skill tools are references to MCP tools defined in another expose. The Skill adapter auto-exposes a discovery API:

  • GET /skills
  • GET /skills/{name}
  • GET /skills/{name}/download
  • GET /skills/{name}/contents

Control Expose (type: control)

- type: control
  port: 9090
  namespace: control
  observability:
    tracing:
      exporter: otlp
      endpoint: http://otel-collector:4317
    metrics:
      exporter: prometheus

Exposes operational endpoints:

Endpoint Purpose
GET /health Liveness + readiness
GET /metrics Prometheus RED metrics
GET /status Runtime diagnostics
GET /traces In-memory trace summary

Only one Control expose per capability is allowed.

Authentication on exposes

authentication:
  type: bearer
  token: "MCP_SERVER_TOKEN"          # bind reference

Authentication on exposes validates incoming requests. Authentication on consumes provides credentials for outgoing requests. Both use the same Authentication object schema.