Creating MCP Tools

Overview

The preferred way to create MCP tools for Greentic is to generate a WASM component from an API description, then call that component from a flow with mcp.exec.

Use this path 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.

Generate From OpenAPI

Prepare an OpenAPI or Swagger spec

Put the API description in your pack or workspace, for example:
```
openapi/weatherapi.yaml
```

List generated tools

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

Inspect the input schema for an operation

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

Inspect the HTTP execution plan

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

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:

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:

{
  "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:

Use --list-tools to confirm the expected operations exist.
Use --tool-schema to confirm required arguments and JSON shapes.
Use --tool-plan to confirm the HTTP method, URL, path/query/body mapping, and base URL.
Run the component against representative inputs in your local test harness.
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.