MCP

The Restormel MCP package exposes tools that agents and IDEs can call via the Model Context Protocol. Use these tools to query models, estimate costs, explain routing, manage control-plane resources, and more — directly from your agent workflow.

Canonical env names: Environment vocabulary — use these RESTORMEL_* names everywhere (apps, CI, wizards). Gateway key and server token are the same secret; evaluate URL, control-plane base, and site origin are three different strings.

Runtime server

@restormel/mcp ships a stdio MCP server you run locally (Cursor, Claude Desktop, Codex, etc.). Install the package, then point your client at pnpm exec restormel-mcp or npx restormel-mcp. See the package README for env vars and security notes.

Server-side environment (policy evaluate vs control-plane)

Configure credentials in the MCP host process environment (not in the browser). Do not commit Gateway keys; do not log them. Summary of the two cloud bases:

Live policy checks (entitlements.check): set RESTORMEL_EVALUATE_URL to the full Dashboard API URL https://restormel.dev/keys/dashboard/api/policies/evaluate (self-host: same path on your host) and RESTORMEL_GATEWAY_KEY to your project Gateway Key (rk_…). Details: Cloud API (Policy evaluate section).
Route and policy MCP tools (routes.*, policies.*, fallback_chain.set): set RESTORMEL_CONTROL_PLANE_URL to the dashboard app base https://restormel.dev/keys/dashboard (no trailing slash; paths append /api/projects/…) and RESTORMEL_SERVER_TOKEN (or gateway key) for Bearer auth. This is not the same string as RESTORMEL_EVALUATE_URL.

Canonical checklist and operator notes: MCP implementation workflow (repo runbook). API portal mirror: open the Restormel API portal → MCP & agent setup.

Available tools

Tool	Description
`models.list`	List available models across configured providers
`providers.validate`	Validate provider configuration and access
`cost.estimate`	Estimate cost for a model and token volume
`routing.explain`	Explain routing decisions for a given request
`routing.export / routing.import / routing.explain_chain`	Control plane: route graph bundle export/import; read-only route + steps + policy-scope summary for agents
`entitlements.check`	Check plan entitlements and feature access
`integration.generate`	Generate integration configuration for a stack
`integration.bootstrap_nextjs`	Generate Next.js server resolver + admin KeyManager wiring contract
`routes.list/create/update/delete`	Project route CRUD in the control plane (server token required)
`policies.list/create/update/delete`	Project policy CRUD in the control plane (server token required)
`fallback_chain.set`	Set primary + fallback model chain for a route
`byok.schema.generate`	Generate DB schema templates for global and user BYOK scope
`byok.api_contract.generate`	Generate validate/add/remove/revalidate endpoint contracts
`policy.simulate`	Batch policy simulation with expected allow/deny assertions
`catalog.sync_check`	Check model references against current catalog
`catalog.deprecation_alerts`	Return deprecation/retirement alerts for referenced models
`readiness.check`	Run CI-friendly readiness checks with stable error codes
`docs.search`	Search Restormel documentation

How MCP maps to Restormel Keys

MCP exposes Restormel’s core building blocks to agent workflows. These tools correspond to the same primitives you can inspect with the CLI and validate with Doctor/Validate.

`models.list` — same model inventory as `keys models list`.
`providers.validate` — same credential health check as `keys validate`.
`cost.estimate` — same pricing lookup as `keys estimate`.
`routing.explain` — same static provider resolution as `keys routing explain` (policies require a configured project).
`routing.export` / `routing.import` / `routing.explain_chain` — control-plane route graph GitOps and agent-oriented summaries (server token + control-plane base URL).
`entitlements.check` — policy checks (local rules via `RESTORMEL_MCP_CONFIG` or remote evaluation via `RESTORMEL_EVALUATE_URL` + `RESTORMEL_GATEWAY_KEY`).
`integration.generate` — scaffolding helper for a new integration.
`integration.bootstrap_nextjs` — project-scoped server bootstrap contract for Next.js.
`routes.*` / `policies.*` / `fallback_chain.set` — control-plane write tools for operational rollout.
`byok.*` / `policy.simulate` — key lifecycle contract generation + deployment scenario simulation.
`catalog.*` / `readiness.check` — model lifecycle guardrails and CI gating outputs.
`docs.search` — offline documentation index search.

Package

Tool schemas and server factory are exported from @restormel/mcp:

import { ALL_TOOLS, createRestormelMcpServer } from "@restormel/mcp";
// or: import { createRestormelMcpServer } from "@restormel/mcp/server";

Programmatic hosts can call createRestormelMcpServer() and attach their own transport from @modelcontextprotocol/sdk.

Next steps

Cloud API — policy evaluate and resolve (same surfaces MCP uses)
CLI quickstart — terminal-based tools
AAIF overview — structured AI interaction contract
All integrations