zoppy-mcp-server

Official MCP server for Zoppy — operate Zoppy from an AI assistant (Claude Desktop, Cursor, VS Code) over the Model Context Protocol.

This is Fase 1: scaffolding + auth flow + the whoami smoke test. Creation tools (segments, templates, campaigns, workflows) land in later phases.

Requirements

• Node.js ≥ 18
• An MCP token generated in Zoppy by a MASTER or ADMIN (Settings → MCP Tokens). It looks like zmcp_... and is shown only once.

Install (Claude Desktop)

Add the server to claude_desktop_config.json:

{
    "mcpServers": {
        "zoppy": {
            "command": "npx",
            "args": ["-y", "zoppy-mcp-server"],
            "env": {
                "MCP_ZOPPY_TOKEN": "zmcp_xxx"
            }
        }
    }
}

Restart Claude Desktop — "zoppy" should appear as an active MCP server.

Environment variables

| Variable | Required | Default | Description | | ------------------- | -------- | -------------------------- | ------------------------------------- | | MCP_ZOPPY_TOKEN | yes | — | The zmcp_ token generated in Zoppy. | | MCP_ZOPPY_API_URL | no | https://api.zoppy.com.br | zoppy-api base URL. |

Tools (Fase 1)

| Tool | What it does | | --------------------------- | ----------------------------------------------------------------------------------------- | | whoami | Returns the authenticated user, company and token metadata (smoke test of the auth flow). | | list_my_companies | Lists the companies an operator token can work on (portfolio). | | assume_company(companyId) | Selects the company to operate (operator token); switch any time. | | verify_mcp_session(code) | Confirms the 6-digit email step-up code, then you retry the original tool. |

Auth flow

1. On boot, the server reads MCP_ZOPPY_TOKEN and ensures a stable device id (persisted in ~/.zoppy-mcp/device-id), sent on every request as X-Zoppy-Device-Id.
2. Every call sends Authorization: Bearer <token> (+ X-Zoppy-Company-Id once a company is assumed).
3. Email step-up (403): the first call (or a new device, or after 4h) returns "verification required" — run verify_mcp_session with the code sent to your email, then retry.
4. Missing config (422): the tool reports which company settings to fill before continuing.
5. 401: the token is invalid/expired/deleted — ask an admin for a new one.

Operator (portfolio) flow: list_my_companies → assume_company(<id>) → operate. Company-scoped tokens skip this (the company is fixed by the token).

Compatibility

| zoppy-mcp-server | Minimum zoppy-api | | ------------------ | ----------------- | | 1.0.0-rc1 | MCP auth (Fase 0) |

Development

npm install
npm run build
npm run lint