WIBI MCP Gateway

Server MCP (Model Context Protocol) that exposes the WIBI API v2 as tools for LLM assistants.

Supports two modes:

Guide for the end customer (WIBI merchant)

No need to be a developer or edit JSON files.

Claude web (claude.ai)

1. Go to claude.ai with your account.

2. Go to Settings → Connectors → Add custom connector.

3. Paste the server URL: https://wibi.com.ar/mcp (temporary test URL; see DNS note below).

4. Claude opens the WIBI login screen in the browser.

5. Enter your WIBI username and password:

   • Merchant: the same merchant credentials in the system → direct access.

   • Panel admin: WIBI panel user (not the merchant's). If the campaign has 2FA, it asks for the email code. Then you choose campaign and merchant with the same scope as in the panel (admin sees their campaigns/merchants; superadmin sees all).

6. Authorize. You can now ask Claude things like:

   • “List the products in my campaign”

   • “Find the customer with DNI …”

   • “What are my campaigns?”

Each session operates only on the selected merchant. There are no shared tokens or per-client configuration.

Claude Desktop

1. Open Claude Desktop → Settings → Connectors (or Developers, depending on the version).

2. Add a remote connector with the URL https://wibi.com.ar/mcp (temporary; see DNS note).

3. Complete the login in the browser with your WIBI username/password.

Related MCP server: meta-ads-mcp

Technical guide (internal team)

Requirements

• Node.js >= 18

• WIBI application API key (approl 1 or 3)

• API v2 deployed (includes /onzecrm/v2/auth/* and /onzecrm/v2/campanias)

Installation

cd wibi-mcp-gateway
npm install --ignore-scripts
npm run build

stdio mode (local)

export WIBI_BASE_URL=https://apiv2.wibi.com.ar
export WIBI_API_KEY=...
export WIBI_USER=...
export WIBI_PASS=...
# opcional:
# export WIBI_DEFAULT_CAMPANIA=13793
node dist/index.js

Example mcp.json (local development only):

{
  "mcpServers": {
    "wibi-local": {
      "command": "node",
      "args": ["/ruta/a/wibi-mcp-gateway/dist/index.js"],
      "env": {
        "WIBI_BASE_URL": "https://apiv2.wibi.com.ar",
        "WIBI_API_KEY": "...",
        "WIBI_USER": "...",
        "WIBI_PASS": "..."
      }
    }
  }
}

HTTP + OAuth mode (production)

Minimum variables:

Do not configure WIBI_USER, WIBI_PASS, or MCP_HTTP_TOKEN in this mode: login is interactive (merchant or panel admin).

MCP_TRANSPORT=http \
WIBI_BASE_URL=https://apiv2.wibi.com.ar \
WIBI_API_KEY=... \
WIBI_PUBLIC_URL=https://wibi.com.ar \
node dist/index.js --http

Endpoints:

• GET /healthz — healthcheck

• GET /.well-known/oauth-authorization-server — OAuth metadata

• POST /register — Dynamic Client Registration

• GET /authorize — login screen

• POST /oauth/approve — multi-step login (credentials → optional OTP → campaign/merchant selector)

• POST /token — exchanges code / refresh

• POST|GET|DELETE /mcp — MCP Streamable HTTP (Bearer OAuth)

Laravel API used by the OAuth login:

• POST /onzecrm/v2/auth/login

• POST /onzecrm/v2/auth/verify-otp / resend-otp

• POST /onzecrm/v2/auth/scoped-comercios / select-scope

• POST /onzecrm/v2/auth/refresh / revoke

Docker

cp .env.example .env   # completar WIBI_BASE_URL, WIBI_API_KEY, WIBI_PUBLIC_URL
docker compose up -d --build
curl http://127.0.0.1:3939/healthz

DNS / certificate

Required action (whoever has DonWeb access): create DNS record:

Once the DNS exists, I can:

1. Issue Let's Encrypt certificate (certbot --apache -d mcp.wibi.com.ar)

2. Create a dedicated vhost that proxies the entire root to the container (127.0.0.1:3939)

3. Change WIBI_PUBLIC_URL=https://mcp.wibi.com.ar and recreate the container

4. Remove the temporary OAuth ProxyPass entries from the wibi.com.ar vhost (/authorize, /token, /register, etc.)

Current workaround (test only): OAuth is published at https://wibi.com.ar with the existing commercial certificate, proxying OAuth routes + /mcp to the container. This is not the final design.

Notes:

• DCR clients + OAuth tokens + WibiSession are persisted in Redis (OAUTH_STORE=redis in Docker). MCP transports remain in process memory.

• Single replica today; Redis leaves the door open for multi-replica. A recreate should no longer require reconnecting Claude.

• HTTPS required (credentials travel through the form).

• The gateway never stores merchant username/password; only short JWT + opaque refresh token (in Redis in production).

Session architecture

claude.ai → OAuth (login comercio o admin) → access token MCP
         → /mcp (Bearer) → WibiClient con JWT del comercio
         → API v2 Laravel (scope por IdComercio / IdRed / idCampania)

If a panel admin logs in, the final JWT still belongs to the selected merchant (same v2 scope). The real actor (actor_id / actor_name / actor_role) travels in the JWT and in write logs for auditing.

When the WIBI JWT is about to expire, the gateway renews it with POST /onzecrm/v2/auth/refresh (without asking for the password again).

Switching merchants within the same session (admins only): an admin/superadmin can switch from one merchant to another without logging in again or going through 2FA again, using the tools wibi_buscar_campanias, wibi_comercios_de_campania, and wibi_cambiar_comercio (see below). Internally they call POST /onzecrm/v2/auth/my-campanias, POST /onzecrm/v2/auth/my-scoped-comercios, and POST /onzecrm/v2/auth/switch-scope (all with Bearer of the current token); the first two only query, the third reissues JWT + refresh preserving the real actor_id for auditing. Direct merchant (login without actor) does not see these tools.

Why wibi_buscar_campanias exists: wibi_mis_campanias only returns the campaign associated with the active merchant's network (usually just one), not the admin's entire scope. A superadmin may have access to hundreds of campaigns and doesn't know them by ID. wibi_buscar_campanias lets you ask Claude to "switch to campaign X" by name, without the user having to know the idCampania in advance.

Main tools

• Reports: movements, customers, products, classifiers, brands, segments, tags, coupons

• Behavior: customer summary, customer analysis

• Broadcasts: tags, WhatsApp templates, schedule/query

• Subscriptions: alert types, create/query

• In OAuth mode: wibi_mis_campanias

• In OAuth mode, only for admin sessions (es_admin: true in wibi_mis_campanias): wibi_buscar_campanias (searches campaigns by name within the admin's scope, without needing to know the idCampania), wibi_comercios_de_campania (lists merchants of a campaign within the admin's scope), and wibi_cambiar_comercio (changes the session's active merchant/campaign without re-login)

The email template tool is disabled until the corresponding Laravel endpoint exists.

Security

• Merchant isolation: each MCP session is tied to the OAuth sessionId + IdComercio from login.

• Writes in Laravel validate customers/tags/alerts against the token scope.

• Rate limit on /oauth/approve and /mcp.

• Cache-Control: no-store, X-Frame-Options: DENY, CSP on the login page.