Creating MCP Tools

Overview

MCP tools in Greentic run on a shared MCP rail and are reached over one of two transports (see MCP Overview):

• local-wasm — a wasix:mcp/router WASM component, scaffolded with gtdx new --kind mcp, that the runner executes in-process. Best for sandboxed, signed tools with no network hop.
• http — a remote MCP server reached over Streamable HTTP. Register an existing or hosted server directly.

This page also covers generating a WASM component from an API description (OpenAPI or Google Discovery) when you want to turn an existing API surface into callable tools.

Use these paths when you want a digital worker to call systems such as weather APIs, GitHub, Google APIs, ticketing systems, CRMs, HR systems, inventory systems, or internal HTTP services.

Do not start from the old generic WIT example

Older docs showed a hand-written wit/tool.wit, tool.yaml, and type: mcp-tool flow node. That does not match the current local Greentic sources. Use gtdx new --kind mcp for a local-wasm tool, greentic-mcp-gen for API-backed MCP tools, or the component wizard when you are building a custom Greentic component.

Create a Local-WASM Tool

A local-wasm tool is a wasix:mcp/router WASM component packaged as a .gtxpack and executed in-process by the runner.

1. Scaffold the router component

   gtdx new --kind mcp my-tool

   This generates a wasix:mcp/router component that 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, non-fatal — tools is left null if the probe fails).

4. Use it

   The Designer flow-editor prompt and the agentic-worker tool picker surface the cached tools with no HTTP probe. At runtime the runner pulls, verifies, caches, and executes the component in-process.

gtdx new --kind accepts design, bundle, deploy, provider, wasm-component, mcp, and llm. See gtdx CLI for the full scaffolding surface.

Generate a Publish-Ready MCP Extension

gtdx new --kind mcp --from-openapi is the high-level wrapper around greentic-mcp-gen. It generates a wasix:mcp/router component from an OpenAPI or Swagger spec and auto-authors describe.json — populating runtime.permissions.network from the spec’s servers and secret_requirements from its security schemes — producing a publish-ready extension in one step.

1. Install dependencies

   Install the greentic-mcp-gen binary (requires a GITHUB_TOKEN with access to the private repo) and the wasm32-wasip2 Rust target:

   export GITHUB_TOKEN=ghp_...
   cargo binstall greentic-mcp-generator
   rustup target add wasm32-wasip2

   cargo, cargo-component, and gtdx must also be available (gtc install installs gtdx).

2. Generate from an OpenAPI spec

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

   gtdx shells out to greentic-mcp-gen, which produces the wasix:mcp/router component. It then auto-authors describe.json with:

   • runtime.permissions.network — derived from the spec’s servers list, so the component has exactly the network access the API requires.
   • secret_requirements — derived from the spec’s security schemes (e.g. API key, OAuth 2.0 scopes), so credential injection is wired automatically.

3. What gets produced

   my-tool/
   ├── describe.json          # auto-authored manifest (network + secrets pre-filled)
   ├── Cargo.toml
   └── target/wasm32-wasip2/
       └── release/
           └── my_tool.component.wasm

   Validate before publishing:

   gtdx validate .
   gtdx lint --publish

4. Publish to the store

   Pass the pre-built WASM with --wasm so gtdx publish skips cargo component build and packages the generated artifact directly:

   gtdx publish \
     --wasm ./target/wasm32-wasip2/release/my_tool.component.wasm \
     --manifest ./Cargo.toml \
     --registry store.greentic.cloud \
     --sign --key-id my-key \
     .

   The store validates kind: wasix:mcp/router against the describe-mcp-v1 schema and verifies the Ed25519 signature.

A sibling passthrough greentic-dev mcp gen <args...> reaches the same generator directly when you prefer the lower-level greentic-mcp-gen surface from within the gtc dev toolchain.

Generate From OpenAPI

1. Prepare an OpenAPI or Swagger spec

   Put the API description in your pack or workspace, for example:

   openapi/weatherapi.yaml

2. List generated tools

   greentic-mcp-gen \
     --spec ./openapi/weatherapi.yaml \
     --list-tools

3. Inspect the input schema for an operation

   greentic-mcp-gen \
     --spec ./openapi/weatherapi.yaml \
     --tool-schema forecast_weather

4. Inspect the HTTP execution plan

   greentic-mcp-gen \
     --spec ./openapi/weatherapi.yaml \
     --tool-plan forecast_weather

5. Generate the component

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

The installed generator supports single-spec mode and batch mode. In batch mode it reads from ./input and writes generated WASM files to ./output unless you override those directories.

Generate From Google Discovery

For Google APIs, use discovery support directly:

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

Profiles restrict large APIs to a useful operation subset. The generator includes profile commands:

greentic-mcp-gen profiles list
greentic-mcp-gen profiles show sheets-crm

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

Then run the normal OpenAPI generation path against ./specs/sheets.openapi.json.

Use the Tool in a Flow

Once the generated component is available to the pack/runtime, call it with mcp.exec:

flow.ygtc

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

Use component for the logical component name, action for the operation, and args for the operation input.

Validate Tool Maps

For tool-map based MCP wiring, keep a toolmap.json near the component artifacts:

toolmap.json

{
  "tools": [
    {
      "name": "weather_api",
      "component": "./output/weatherapi_current.component.wasm",
      "entry": "tool_invoke",
      "timeout_ms": 5000,
      "max_retries": 1,
      "retry_backoff_ms": 250
    }
  ]
}

Run doctor checks:

greentic-dev mcp doctor providers/weather --json

The doctor accepts a relative path to a tool-map file or a directory containing one of:

• toolmap.json
• toolmap.yaml
• toolmap.yml
• mcp.json
• mcp.yaml

It checks duplicate tool names, resolves component paths, and reports whether the referenced WASM files exist.

Package With a Pack

An MCP tool is useful only when the pack also carries the right runtime information:

• generated .wasm component artifact
• flow nodes that call the component with mcp.exec
• binding hints for required MCP servers or endpoints
• secret requirements for API keys and OAuth tokens
• network allowlists for outbound calls
• observability/control settings for audit, tracing, retries, and policy

Use the pack and bundle wizard flow for packaging. Coding agents should fetch the current wizard schema first, fill the answers JSON, then replay the wizard non-interactively:

gtc wizard --schema
gtc wizard --answers pack-create-answers.json

Custom Components

If the integration is not well represented by OpenAPI or Discovery, create a custom Greentic component instead of forcing it into the MCP generator. Use the component wizard and current component templates:

gtc wizard --schema
greentic-component wizard --schema

Then use the generated answers file with the relevant wizard command. The exact answers schema is versioned by the installed CLI, so always inspect --schema before generating files by hand or with a coding agent.

Testing Guidance

Before packaging a generated MCP component:

1. Use --list-tools to confirm the expected operations exist.
2. Use --tool-schema to confirm required arguments and JSON shapes.
3. Use --tool-plan to confirm the HTTP method, URL, path/query/body mapping, and base URL.
4. Run the component against representative inputs in your local test harness.
5. Run greentic-dev mcp doctor for tool-map based wiring.

Best Practices

• Prefer generated MCP components for API-backed tools.
• Keep operation names stable after flows depend on them.
• Put API keys and OAuth tokens in secrets, not generated source or flow files.
• Declare expected network endpoints so deployment and security tooling can enforce policy.
• Keep retries and timeouts explicit for external systems.
• Capture tool latency and failures through observer/telemetry extensions.

Next Steps

• MCP Overview
• Components Guide
• Flows