# Effortlessapi Effortless Claude Effortless MCP > Effortless MCP Server — Install + Use - Skill: `tomevault-io/effortlessapi-effortless-claude-effortless-mcp` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/effortlessapi-effortless-claude-effortless-mcp` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/effortlessapi-effortless-claude-effortless-mcp/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/effortlessapi-effortless-claude-effortless-mcp --- # Effortless MCP Server — Install + Use A versioned `ssotme://` tool deployed to Control Plane. Speaks the Model Context Protocol over **streamable HTTP** (default) or **stdio**. Every active transpiler in the baked catalog snapshot becomes an MCP tool; every text file under each skill folder becomes an MCP resource. | What | Where | |---|---| | **Deployed (HTTP)** | `https://effortless-mcp-server-v2026-05-02-1329-cmvbd4phczmeg.7pktzg2z971j0.cpln.app/mcp` | | **Source** | [Versioned-Stable-SSoTme-Tools/tools/effortless/mcp-server/](../../../../api.effortlessapi.com/Versioned-Stable-SSoTme-Tools/tools/effortless/mcp-server/) | | **Local dev port** | `30051` | | **Browser explorer** | `/explorer` (single-page UI that calls `/mcp` from the browser) | The deployed URL is **version-pinned** — bumping versions publishes a new URL, and the previous URL keeps working until clients are migrated. ## Surface **Tools** (callable via `tools/call`): | Tool | What it does | |---|---| | `effortless_ping` | Health/echo. Returns server version + your message. Use to verify wiring. | | `effortless_build` | Shells out to the `effortless` CLI to run a project pipeline. Inputs: `projectDir`, `includeDisabled` (the `-id` flag). | | `query_rulebook` | Structured queries against an `effortless-rulebook.json`. Inputs: `input` (path), `query` (`tables` / `schema` / `relationships` / `calculated_fields` / `field` / `dag`), optional `table` / `field`. | | `validate_dag` | DAG integrity check on an `effortless-rulebook.json`. Catches cycles, broken FK targets, missing Name fields, naming-convention violations. | | `` (~54) | One auto-generated tool per active transpiler in the baked catalog snapshot. Schemas come from the Airtable Parameter table. POSTs directly to the transpiler's Control Plane URL — does **not** shell out to the CLI. | **Resources** (read via `resources/read`): - `effortless://skills/index` — list of all skills in the baked snapshot. - `effortless://skills/` — manifest for one skill. - `effortless://skills//` — every text file under that skill folder. The baked skill snapshot is a frozen copy of `github.com/effortlessapi/effortless-claude/skills/` taken at image build time. ## Install ### Claude Code Already wired at user level if you see `mcp__effortless-mcp__*` tools in the deferred list. To configure manually, add to `~/.claude.json` under the appropriate project (or the user-level block): ```json { "mcpServers": { "effortless-mcp": { "type": "http", "url": "https://effortless-mcp-server-v2026-05-02-1329-cmvbd4phczmeg.7pktzg2z971j0.cpln.app/mcp" } } } ``` Restart Claude Code (or `/mcp` to inspect). Tool names will appear as `mcp__effortless-mcp__effortless_ping`, etc. ### Cursor / Windsurf ```json { "mcpServers": { "effortless-mcp": { "url": "https://effortless-mcp-server-v2026-05-02-1329-cmvbd4phczmeg.7pktzg2z971j0.cpln.app/mcp", "transport": "streamable-http" } } } ``` ### Self-describing config generation `POST /run` with `{"clientType": "claude-code" | "cursor" | "windsurf" | ...}` returns a fileset including a pre-wired settings snippet. Use this when wiring a new client type rather than guessing the schema. ## Smoke tests ```bash BASE='https://effortless-mcp-server-v2026-05-02-1329-cmvbd4phczmeg.7pktzg2z971j0.cpln.app' curl -s "$BASE/healthz" # liveness curl -s "$BASE/_meta" # version + protocol metadata curl -s -X POST -H 'Content-Type: application/json' -d '{}' "$BASE/run" | jq .summary ``` In Claude Code: ask *"Run `effortless_ping` with message 'hello'."* — should return JSON with the server version. ## Local development The MCP server lives as a `ssotme://` versioned tool at [tools/effortless/mcp-server/](../../../../api.effortlessapi.com/Versioned-Stable-SSoTme-Tools/tools/effortless/mcp-server/). Local dev reads skills from the sibling `effortless-claude/skills/` repo directly (no bake step needed); the deployed image bakes a snapshot. ```bash cd /Versioned-Stable-SSoTme-Tools/tools/effortless/mcp-server ./scripts/bake-catalog.sh # workload/catalog.json (homedir CLI cache → snapshot) ./start.sh # HTTP on :30051 ./start.sh --stdio # stdio mode (for clients that spawn a child process) ``` `start.sh` requires Node ≥ 18. It tries `nvm use 20` automatically if your default is older. Port-squatters on `:30051` get killed. To point a local Claude Code at the dev server instead of the deployed one: ```json { "mcpServers": { "effortless-mcp-local": { "type": "http", "url": "http://localhost:30051/mcp" } } } ``` ## Deploy a new version Through the **transpiler-server UI at `http://localhost:3000`**, not the cpln CLI directly. The flow: 1. `./scripts/bake-catalog.sh` — freeze the desired catalog snapshot. 2. `./scripts/bake-skills.sh` — freeze the desired `effortless-claude/skills/` snapshot. 3. Bump the version in [workload/ssotme-tool.json](../../../../api.effortlessapi.com/Versioned-Stable-SSoTme-Tools/tools/effortless/mcp-server/workload/ssotme-tool.json) (`vYYYY.MM.DD.HHMM` mirrored across `name`, `version`, `names.*`, `metaData.versionNumber`, `metaData.createdAt`, `metaData.createdOn`). 4. Bump `workload/package.json` `version` (semver, parallel to the timestamp). 5. Open the transpiler-server UI → navigate to `effortless/effortless/mcp-server` → **Publish New Version**. The UI runs `docker build`, pushes to the Control Plane org, applies `cpln/workload.yaml`, and inserts a `TranspilerVersion` row in Airtable base `app1dOUUtasVF6wc2`. 6. Verify: `curl /_meta`. Update the deployed URL in `~/.claude.json` and any other client configs. The previous version stays addressable at its pinned URL — existing clients keep working until migrated. ## When to invoke MCP tools vs. local CLI vs. Airtable API | Goal | Use | |---|---| | Run a project's full build pipeline | `effortless_build` (or `effortless build` from a shell — same effect) | | Call one transpiler in isolation | `mcp__effortless-mcp__` (direct HTTP to Control Plane — no local CLI needed) | | Inspect rulebook structure cheaply | `query_rulebook` (faster + smaller-context than reading the JSON) | | Sanity-check rulebook before commit | `validate_dag` | | Scalar field add / CRUD | Airtable REST API (see `effortless-airtable`) — **not** the MCP transpiler tools | | Formula / lookup / rollup / new table | OMNI via Playwright (see `effortless-airtable-omni`) | The MCP server's transpiler tools are equivalent in effect to running the corresponding `effortless ` CLI command, but they POST directly to Control Plane — useful when the CLI isn't installed (Cursor on a teammate's laptop, ChatGPT in the browser, etc.). ## See also - `effortless-cli` — the CLI binary; complementary surface over the same catalog. - `effortless-pipeline` — what `effortless_build` actually orchestrates. - `effortless-query` — local one-liners equivalent to `query_rulebook`. - `effortless-diagnostics` — what `validate_dag` is checking for. - `effortless-claude-updates` — for editing the **skill set** that this server exposes as resources. --- > Source: [EffortlessAPI/effortless-claude](https://github.com/EffortlessAPI/effortless-claude) — distributed by [TomeVault](https://tomevault.io).