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.

MCP tools run on a single, shared MCP rail. Servers are registered per tenant/team in greentic-admin (tenant_mcp_servers) and are consumed by both flow nodes and agentic workers through one McpToolSource. There is no separate tool wiring for flows versus agents — the same registered server is reused everywhere.

The rail supports two transports:

• http — a remote MCP server reached over Streamable HTTP (JSON-RPC 2.0, protocol 2025-06-18).
• local-wasm — a wasix:mcp/router WASM component run in-process by the runner. No HTTP hop.

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. Register MCP servers on the shared rail (http or local-wasm) for runtime wiring.

Transports

A registered MCP server uses one of two transports. Both are reached the same way by callers (flow nodes and agentic workers) through the shared McpToolSource.

Transport	What it is	Where it runs
http	A remote MCP server over Streamable HTTP (JSON-RPC 2.0, protocol 2025-06-18).	An external process/service.
local-wasm	A wasix:mcp/router WASM component executed in-process by the runner.	Inside the Greentic runner — no HTTP hop.

Use http for existing or hosted MCP servers. Use local-wasm when you want a sandboxed, signed tool that ships and runs as a WASM component with no network round-trip. See Local-WASM Tools below for the authoring path.

Where MCP Fits

http transport                local-wasm transport
--------------                --------------------
Remote MCP server             wasix:mcp/router .gtxpack
(Streamable HTTP,             (gtdx new --kind mcp)
 JSON-RPC 2025-06-18)                |
        |                            v
        |                     publish to store
        |                            |
        +------------+---------------+
                     v
        Register in greentic-admin
        (tenant_mcp_servers, per tenant/team)
                     |
                     v
        Shared McpToolSource
                     |
        +------------+------------+
        v                         v
   Flow nodes              Agentic workers

Local-WASM Tools (gtdx)

A local-wasm MCP tool is a wasix:mcp/router WASM component packaged as a .gtxpack. The end-to-end path is:

1. Scaffold a router component:

   gtdx new --kind mcp my-tool

   This generates a wasix:mcp/router component (exports wasix:mcp/router@25.6.18).

2. Publish the .gtxpack to the store. The store validates kind: wasix:mcp/router against its describe-mcp-v1 schema.

3. Register the server in greentic-admin. Admin pulls the .gtxpack, verifies its sha256 and Ed25519 signature against trusted publisher keys, and caches the tool list by running list_tools at registration (best-effort and non-fatal — tools is left null on failure).

4. Author in the Designer. The flow-editor prompt and the agentic-worker tool picker surface the cached tools without an HTTP probe.

5. Run. The runner pulls, verifies, caches, and executes the component in-process.

Tool lists can be warmed eagerly via the best-effort greentic.mcp.warm.v1 NATS event; a lazy store-pull is the fallback.

gtdx kinds

gtdx new --kind accepts design, bundle, deploy, provider, wasm-component, mcp, and llm. Use --kind mcp for a wasix:mcp/router local-wasm tool. See gtdx CLI.

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

For a publish-ready wasix:mcp/router extension from an OpenAPI or Swagger spec, use the gtdx high-level wrapper:

gtdx new --kind mcp --from-openapi ./openapi/weatherapi.yaml

gtdx shells out to greentic-mcp-gen and auto-authors describe.json — deriving runtime.permissions.network from the spec’s servers and secret_requirements from its security schemes. See Creating MCP Tools for the full step-by-step including dependency setup and gtdx publish.

For lower-level control, call greentic-mcp-gen directly:

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