@muovi/mcp-server
[npm version]
Model Context Protocol (MCP) server for Muovi — LATAM's trust-first local services marketplace.
This package lets MCP-aware clients (Claude Desktop, Cursor, Claude Code, and any other MCP host) discover Muovi's verified LATAM service professionals, browse the service catalog and city list, read reviews, deep-link a user into the on-platform task-creation flow, and save a task draft the user publishes themselves. It is a thin wrapper over Muovi's public /v1 REST API.
Stdio mode. The package ships an npx-runnable binary that speaks JSON-RPC over stdin/stdout. The hosted HTTP/SSE variant is tracked separately (Muovi MOB-142).
What it exposes
Every tool is read-only except muovi_create_task_draft, which saves a draft on Muovi:
Anti-leakage policy
Muovi is on-platform-only. Phone, email, and WhatsApp handles are never returned by the public API — contact between consumers and professionals happens exclusively through Muovi's in-app conversation flow, reachable from each pro's profile_url.
This server enforces the policy twice:
- The
/v1 API strips contact data server-side.
- Every tool response in this package also runs through a local anti-leakage detector (a Node-compatible mirror of
src/lib/anti-leakage/detector.ts in the Muovi web repo). If a leak is detected at the agent boundary the tool returns a stable error to the LLM client and refuses to surface the payload.
Hosts that integrate this server must not synthesise off-platform contact handles from any field. Driving the user to profile_url (optionally with the deep-link query string) is the only sanctioned contact channel.
Installation & configuration
Claude Desktop
Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add the server under mcpServers:
If you have a Muovi API key (see Authentication below), pass it via env:
Restart Claude Desktop after editing the config.
Cursor
Add to ~/.cursor/mcp.json (or your workspace's .cursor/mcp.json):
Claude Code
Register the server with the Claude Code CLI:
Or add it manually to your Claude Code settings:
Manual / scripting
The process reads JSON-RPC on stdin and replies on stdout. All log output goes to stderr.
Authentication (optional)
All /v1 endpoints are public and unauthenticated by default. If your client has been issued a Muovi API key (higher rate-limit tier), set MUOVI_API_KEY in the server's environment and the package will forward it as the X-API-Key header on every request.
You can also override the API base URL for testing:
muovi_create_task_link builds its link on MUOVI_WEB_BASE_URL when that is an https origin with no path, and on https://muovi.com.ar otherwise.
Example agent workflow
A typical Claude conversation that uses these tools:
- User asks for "an electrician in Palermo who's properly licensed".
- Agent calls
muovi_list_services to map "electrician" → electricidad.
- Agent calls
muovi_list_cities to confirm palermo is a valid neighborhood under caba.
- Agent calls
muovi_search_professionals with { service: "electricidad", neighborhood: "palermo", has_matricula: true } and gets up to 5 professionals. Without both a service and a barrio the tool answers an error asking for them, so the agent asks the user first.
- Agent shows the results and offers two choices: a task for one of those professionals, or a general request to get offers from several.
- For one professional, the agent can call
muovi_get_professional and muovi_get_reviews with that result's id.
- Agent calls
muovi_create_task_link with { professional_id, service_slug: "electricidad" } and surfaces the resulting URL — or calls muovi_create_task_draft with { service_slug: "electricidad", professional_id, description } so the user lands on a draft already written. For a general request it calls muovi_create_task_draft without a professional.
- User follows the link, lands on Muovi, reviews the draft, signs in, and publishes the task in the on-platform flow.
Step 8 — the on-platform flow — is where the task is published, and where payments and disputes run.
Local development
This package is the standalone muovi-latam/mcp-server repo. Clone it, install, and run tests:
The OpenAPI drift test parses public/openapi.yaml and asserts each tool's input schema matches the corresponding operation's parameters exactly — adding a query param to /v1 requires updating the corresponding tool (and vice versa).
Publishing
npm publish is intentionally not wired into CI. Releases are cut manually from a clean tag:
prepublishOnly runs clean + build + test before any publish.
MCP Registry (mcp-publisher)
Beyond npm, this server is listed in the Model Context Protocol registry via the committed server.json manifest. Publishing to the registry is a manual step — there is deliberately no CI auto-publish (the registry is a low-frequency, human-gated surface, and namespace auth is interactive).
Committed namespace: ar.com.muovi/mcp-server — the reverse-DNS form of muovi.com.ar. This value lives in both server.json (name) and package.json (mcpName) and the two must stay byte-identical (the server-json test enforces equality). It must also match the identity you authenticate as with mcp-publisher (see below).
One-time namespace ownership setup
Prove ownership of the ar.com.muovi namespace once, before the first publish:
- DNS (preferred): add the TXT record that
mcp-publisher login dns prints to the muovi.com.ar zone, then authenticate against that domain. This ties the namespace to the domain we already control.
- GitHub OAuth (fallback):
mcp-publisher login github — authenticates via the muovi-latam GitHub org. Only use this if DNS verification is unavailable; the authenticated identity still has to line up with the committed ar.com.muovi/mcp-server namespace.
If the committed namespace and the authenticated identity disagree, mcp-publisher publish will reject the manifest — fix the namespace (in both files) or the login, do not force it.
Publish steps
validate is the step that confirms the manifest matches the current registry schema version — run it every time; the pinned $schema in server.json is a hint, not a guarantee the live schema hasn't moved.
Version-bump discipline
The server-json test asserts that four version fields agree. On every version bump, update all of them together, then re-publish to both npm and the registry:
package.json → version
src/server.ts → PACKAGE_VERSION
server.json → version
server.json → packages[0].version
Honest gating notes
The manifest advertises capabilities that are not yet fully live. Keep these caveats in mind (and do not overstate them to users):
- Remote transport (
remotes[].url = https://mcp.muovi.com.ar/) is only truthful once that endpoint reliably answers JSON-RPC initialize over streamable-HTTP. That hosted surface is tracked in MOB-207; until it lands, the stdio package (npx @muovi/mcp-server) is the only transport that actually works.
muovi_create_task_draft answers "not available" while task handovers are switched off on the server (TASK_HANDOVERS_ENABLED), which is the default.
muovi_get_professional and muovi_get_reviews remain broken against production until MOB-263 deploys the backing /v1 endpoints. The tools are registered and pass drift checks, but live calls will fail until then.
License
MIT.
Links