CertiWatt MCP server

Agent-facing MCP adapter for CertiWatt's HTTP API.

Package

npx -y @certiwatt/mcp

Tools

• search_models
• search_rules
• get_model
• verify_power_bank
• get_sources

The server intentionally stays thin. Canonical catalog, source, and verdict logic remain in the web/API layer.

Recommended agent flow

1. If the user gives any product name, alias, or recall model, call search_models.
2. If a canonical model_id is found and model facts or related models matter, call get_model.
3. For the actual travel question, call verify_power_bank.
4. If the user asks about a rule loosely, call search_rules.
5. If the user asks "why" or requests evidence, call get_sources.

Do not use search_rules as a substitute for product lookup. Product, recall, and related-model questions still begin with search_models.

Do not treat insufficient as a weak version of allowed. It means CertiWatt does not have enough verified coverage to produce a fully supported verdict.

If search_models returns no result and the user has not provided usable manual specs (watt_hour, or capacity_mah + voltage_v), ask for the device-label details instead of calling verify_power_bank just to force an insufficient response.

Example prompts

• "Can I fly with my Anker 737 from China to Japan on Cathay?"
• "Find the closest match for PowerCore 24K, then tell me if it can fly."
• "Show the evidence behind that power-bank verdict."

Error behavior

Malformed requests and server failures still raise errors.

Domain gaps are returned as structured results so an agent can continue reasoning:

• MODEL_NOT_FOUND
• AIRLINE_NOT_COVERED
• COUNTRY_NOT_COVERED
• RULE_NOT_FOUND

These responses include:

• status
• reason_code
• message
• suggested_next_step
• http_status

Production behavior

By default the published server calls:

https://certiwatt.app/api

No API configuration is required for normal use:

npx -y @certiwatt/mcp

Local development

cd apps/mcp
npm install
npm run build

Only override the API base URL when you are developing against a local web app:

CERTIWATT_API_BASE_URL=http://localhost:3004/api npm run dev

Local tests

With the web app running locally on http://localhost:3004:

CERTIWATT_API_BASE_URL=http://localhost:3004/api npm run test:contract
CERTIWATT_API_BASE_URL=http://localhost:3004/api npm run test:protocol

test:contract validates the four tool handlers against the HTTP API.
test:protocol starts the compiled MCP server over stdio, lists tools, and performs a real MCP tool call.

Repo-local plugin

The current plugin scaffold lives at:

plugins/certiwatt/

Its .mcp.json launches:

npx -y @certiwatt/mcp

Packaging

Validate the publishable tarball locally:

npm pack --dry-run

Expected package contents are intentionally small:

• dist/
• README.md
• package.json