Docs

MCP Fusion/Integrations and federation/YAML connectors

YAML connectors

Ask AI about Vinkius

Build a REST-backed MCP connector without TypeScript: secrets, connections, tools, resources, prompts and response transforms in mcpfusion.yaml.

The YAML engine is the zero-code authoring path. It compiles a declarative manifest into the same MCP surface as a typed server: tools with parameters, Presenters through response transforms, resources, prompts and connections. Use it to wrap an internal REST API quickly; move to typed MVA code when the domain needs custom behavior.

A complete manifest

yaml
version: "1.0"
server:
  name: billing
  description: Invoice operations for an AI agent
  capabilities:
    tools: true
    resources: true
secrets:
  BILLING_TOKEN:
    label: Billing API token
    type: api_key
    required: true
    sensitive: true
connections:
  billing:
    type: rest
    base_url: https://api.example.com
    auth:
      type: bearer
      token: ${SECRETS.BILLING_TOKEN}
tools:
  - name: list_invoices
    description: List invoices for the current account
    rules:
      - Never expose internal_notes to the model
    parameters:
      account_id:
        type: string
        required: true
        description: Account identifier
    execute:
      connection: billing
      method: GET
      path: /accounts/{{account_id}}/invoices
    response:
      extract: [data]
      max_items: 50

The parser validates the root schema with Zod, checks cross references, interpolates ${SECRETS.KEY} from the environment, compiles parameters to JSON Schema, resolves the connection and builds a local MCP server.

The manifest surface

  • server: name, description, capabilities and instructions
  • secrets: typed declarations such as api_key, token, password, url, required and sensitive flags
  • connections: REST base URL, auth (none, bearer, basic or custom header), headers, timeout and retry policy
  • tools: description, instruction, rules, tags, annotations, parameters, HTTP execute block and response transform
  • resources: URI templates, static or fetched content, MIME type and optional cache
  • prompts: flat primitive arguments and user/assistant message templates with {{argument}}
  • settings: exposition, DLP, FinOps, circuit breaker and lifecycle declarations

The CLI

bash
mcpfusion yaml validate mcpfusion.yaml
mcpfusion yaml dev mcpfusion.yaml --transport http --port 3001

The CLI auto-discovers mcpfusion.yaml or mcpfusion.yml in the current directory. validate stops after schema and cross-reference checks. dev runs stdio by default or Streamable HTTP on the selected port.

The current YAML package has validate and dev commands in the OSS CLI. Deploy the compiled connector through the regular Deploy flow; do not assume a separate YAML deploy command unless your installed CLI exposes it.

What OSS enforces

The open engine enforces schema shape, required fields, parameter types, cross references, secret interpolation and REST execution. The settings keys for DLP, FinOps, circuit breaker and lifecycle are parsed as part of the manifest; enforcement of those platform controls belongs to Vinkius Cloud. This split lets the same YAML run locally while the hosted connector gains the platform perimeter.

When YAML stops being enough

Choose typed MVA code when you need dynamic Presenters, role-dependent schemas, custom middleware, transactions, FSM state gates, generator handlers or domain-specific error recovery. The migration is not a rewrite of the protocol: the same tools, resources and prompts can be rebuilt with initMCPFusion() and deployed with the same command.

Next steps