MCP Overview

Introduction

MCP (Model Context Protocol) is a standard way to describe tools that an AI system can call. In Greentic, MCP is used as an integration surface for digital workers that need to call external APIs, SaaS systems, internal services, and generated tool components.

Greentic does not treat MCP as a separate hand-written YAML tool language. The current implementation centers on:

• generated wasm32-wasip2 MCP components, usually from OpenAPI or Google Discovery documents
• flow nodes that call MCP-backed operations with mcp.exec
• host binding hints for MCP servers, network access, secrets, and environment variables
• tool maps that can be inspected with greentic-dev mcp doctor

Older examples

Older examples used type: mcp-tool, greentic-mcp test, and per-tool YAML manifests. Those are not the current flow shape in the local Greentic sources. Use mcp.exec in flows and generated MCP components or validated tool maps for runtime wiring.

Where MCP Fits

OpenAPI / Discovery document
        |
        v
greentic-mcp-gen
        |
        v
wasm32-wasip2 MCP component
        |
        v
Greentic pack / bundle
        |
        v
Flow node: mcp.exec
        |
        v
Host bindings: MCP endpoint, network, secrets, telemetry

Key Concepts

Generated Components

greentic-mcp-gen turns API descriptions into WASM components that expose MCP tools.

Flow Calls

Flows call MCP-backed operations through mcp.exec, passing an action and JSON-style arguments.

Binding Hints

Packs can describe MCP servers, endpoints, transports, capability tags, secrets, environment variables, and network allowlists for the host.

Doctor Checks

greentic-dev mcp doctor inspects tool maps and reports missing component files, entries, retry settings, and timeouts.

MCP in Flows

Current Greentic flow fixtures use component-style nodes. An MCP call is represented as a node operation named mcp.exec:

weather_bot.ygtc

nodes:
  forecast_weather:
    mcp.exec:
      component: weather_api
      action: forecast_weather
      args:
        q: in.q_location
        days: parameters.days_default
    routing:
      - to: weather_text

The important fields are:

Field	Purpose
component	Logical MCP component or adapter name available to the pack/runtime.
action	Tool operation to call on that component.
args	Arguments passed to the operation. These should match the tool input schema.

This is different from older docs that showed:

type: mcp-tool

Do not use that older shape for new flows.

Generating MCP Components

Use greentic-mcp-gen to generate MCP components from an API description:

greentic-mcp-gen \
  --spec ./openapi/weatherapi.yaml \
  --output-dir ./output

Useful validation commands:

greentic-mcp-gen --spec ./openapi/weatherapi.yaml --list-tools
greentic-mcp-gen --spec ./openapi/weatherapi.yaml --tool-schema forecast_weather
greentic-mcp-gen --spec ./openapi/weatherapi.yaml --tool-plan forecast_weather

The installed generator help states that generated components target the current protocol with:

greentic-mcp-gen --protocol latest

The local generator source currently supports latest / 25.06.18.

Google Discovery Documents

For Google APIs, use the discovery subcommand:

greentic-mcp-gen discovery \
  --url "https://sheets.googleapis.com/$discovery/rest?version=v4" \
  --profile sheets-crm \
  --out ./output

You can also convert Discovery to OpenAPI first:

greentic-mcp-gen discovery-to-openapi \
  --url "https://sheets.googleapis.com/$discovery/rest?version=v4" \
  --profile sheets-crm \
  --out ./specs/sheets.openapi.json

Binding Hints

Greentic types include MCP binding hints so the runner can prepare host-side tool access:

{
  "mcp": {
    "servers": [
      {
        "name": "weather_api",
        "transport": "http",
        "endpoint": "https://api.weather.example",
        "caps": ["weather"]
      }
    ]
  }
}

Binding hints are not a substitute for secrets or policy. They tell the host what the pack expects so runtime setup can wire the right endpoint, transport, and capability tags.

Tool Maps

The dev CLI can inspect MCP tool maps. The current source accepts JSON or YAML files named toolmap.json, toolmap.yaml, toolmap.yml, mcp.json, or mcp.yaml.

toolmap.json

{
  "tools": [
    {
      "name": "echo",
      "component": "./target/wasm32-wasi/release/echo_tool.wasm",
      "entry": "tool_invoke",
      "timeout_ms": 3000,
      "max_retries": 1,
      "retry_backoff_ms": 100
    }
  ]
}

Run:

greentic-dev mcp doctor providers/weather

or:

greentic-dev mcp doctor providers/weather --json

The doctor resolves component paths relative to the tool-map file and reports missing components, entry names, retry settings, and timeout settings.

Security

MCP integrations still follow Greentic’s host capability model:

• network access should be declared and allowlisted
• credentials should come from secret bindings, not component source code
• environment variables must be explicitly passed through
• generated components should be tested against their input schemas before they are packaged
• telemetry and observer extensions should capture tool failures, latency, and retry behavior

Next Steps

• Creating MCP Tools
• Flows
• Components