AI Assistant (MCP)

What it is: A Model Context Protocol (MCP) server that lets an AI assistant operate your Wadood platform on your behalf — building pages, managing data, syncing environments, and more, in plain language. Who should read this: Administrators and developers who want to drive Wadood from an AI assistant instead of clicking through the admin app. Status: ✅ Available.

Introduction

The Wadood MCP exposes the platform's admin operations as tools an AI assistant can call. Instead of clicking through the admin app, you describe what you want ("create a page called Contact with a form and add it to the main menu"), and the assistant carries it out by calling the same admin API the portal uses.

Two things stay true no matter what the assistant does:

The server is in charge. Every tool call goes through the normal Wadood API, so tenant, site, permission, and storage/user limits are all enforced server-side — exactly as they are for the admin app. The MCP can never do more than your account is allowed to do.
Everything is logged. Because you connect with your own access, all activity is attributed to you in the activity log — not to a shared robot account.

The assistant can read and write across the platform: Pages, Layouts, Shared Elements, Menus, Forms, Data Store, Localization, Option Groups, Sites & Environments, Users, Roles, File Manager, and Sync Manager, plus read-only reference data and the product documentation you're reading now.

Read-only mode: the assistant can run in a safe read-only mode that blocks every create/update/delete. Keep it on while you explore, turn it off when you're ready to make changes.

Two ways to connect

There are two separate ways to connect Wadood to your AI assistant. Pick the one that matches the app you use — you don't need both:

	Option 1 — Connector	Option 2 — npx MCP
Hosted or local	Hosted by Wadood	Runs on your own machine
Best for	ChatGPT, Claude web & mobile apps	Claude Desktop, Cursor, Claude Code, VS Code, IDEs
Install	None	Runs via `npx` (needs Node.js 20+)
How you sign in	Sign in & approve in the browser (OAuth)	A personal access token you generate once

Both act as you — bounded by your role and site access, and fully logged. Set up whichever one fits your app below, then How to use it applies to both.

Option 1 — Connector

The hosted server, and the easiest path: connect by URL. It's the only option for browser-based assistants (ChatGPT, Claude web & mobile). No install, no token — you sign in and approve access.

In your assistant, open Settings → Connectors (in ChatGPT, turn on Developer mode first) → Add custom connector.
Name it Wadood and enter the URL https://mcp.wadood.io/mcp → add it.
Click Connect. A window opens to portal.wadood.io → sign in with your Wadood account → an authorization screen shows exactly what the app will be able to do (read, or read & write) → click Allow.
The wadood tools appear. Ask the assistant to run the health check (wadood_health) to confirm.

Disconnect anytime. In the portal, Account → Connected apps lists every AI app you've authorized; Disconnect revokes its access instantly, without affecting your login. What the app can do (read-only vs. read & write) is set by the scope you approve on the authorization screen.

Option 2 — npx MCP

The local connector, for desktop and IDE clients (Claude Desktop, Cursor, Claude Code, VS Code, JetBrains, …). Your client launches it on your own machine with npx. Two one-time steps: generate a token, then register the server. (Needs Node.js 20+.)

Step 1 — Generate your access token

The assistant authenticates as you using a personal MCP Access Token. You create it once from your account page.

Sign in to the admin portal and open your Account page.
Find the MCP Access Tokens card.
Click Generate token, give it a label (e.g. "Claude on my laptop"), and optionally an expiry date.
Copy the token now — it starts with wdat_ and is shown only once. Store it somewhere safe (a password manager). If you lose it, revoke it and generate a new one.

You can revoke a token at any time from the same card — the assistant instantly loses access, without affecting your portal login.

Treat the token like a password. Anyone holding it can act as you, within your permissions. Never paste it into a page, a chat, or a shared document. Generate a separate token per device/tool so you can revoke just one if needed.

Step 2 — Register the connector in your client

Every MCP client has a place to register servers (Claude Desktop → Settings → Developer; Claude Code → the mcp config; Cursor → MCP settings). Add this — npx fetches @wadood/mcp from npm on first run, so there's no manual install:

json

{
  "mcpServers": {
    "wadood": {
      "command": "npx",
      "args": ["-y", "@wadood/mcp"],
      "env": {
        "WADOOD_API_BASE_URL": "https://portal.wadood.io",
        "WADOOD_AGENT_TOKEN": "wdat_your_token_here",
        "WADOOD_MCP_READ_ONLY": "true"
      }
    }
  }
}

Variable	Meaning
`WADOOD_API_BASE_URL`	Your Wadood server base URL, no trailing slash.
`WADOOD_AGENT_TOKEN`	The `wdat_…` token you generated in Step 1.
`WADOOD_MCP_READ_ONLY`	`true` blocks all changes (read-only). Set to `false` — or remove it — when you want the assistant to make changes. Start with `true`.

Restart your client after saving the config. The wadood server should appear in its list of connected tools.

Desktop Extension (one-click install): we also plan to ship a .mcpb Desktop Extension bundle so Claude Desktop users can install the connector without editing JSON — you'll just double-click the file and paste your token. Watch this page for the download link at release.

How to use it

Whichever way you connected, ask your assistant to run the health check first (a tool named wadood_health). If it succeeds, you're connected.

From there, just describe what you want in plain language. A few examples:

"List the pages on my Development environment for the marketing site."
"Create a new page Pricing, add a hero shared element at the top, and put it in the main menu."
"Add a Contact form with name, email, and message fields, and drop it on the Contact page."
"How many unprocessed submissions does the Contact form have?" (the assistant reports the counts by status), then "mark all the unprocessed ones as in-progress" (it changes them in one batch — it'll confirm the count with you first).
"Show me the submissions where country is Jordan and gender is female." (the assistant filters on the submitted field values; it matches the stored option value, so it reads the form first to map a label like "Jordan" to its value).
"Promote everything I changed from Development to Production" (the assistant uses Sync Manager — remember to publish the synced versions in the target, and to queue an item's dependencies together; see Sync Manager).
"Add French and Arabic localization keys for the homepage headings."

The assistant follows the platform's own best practices — using built-in Forms and Menus instead of hand-rolled HTML, reusing Layouts for shared structure, adding the viewport metadata on new sites, and pairing a "Can view …" privilege with any add/edit/delete privilege when it creates roles.

Which AI clients can I use?

Browser assistants → use Option 1 — Connector. ChatGPT and the Claude web & mobile apps connect only to remote MCP servers, so they use the hosted URL https://mcp.wadood.io/mcp — no Node, no token.

Desktop & IDE clients → use Option 2 — npx MCP. Any MCP client that can run a local (stdio) server works — most of them can. The popular ones:

Assistants

Claude Desktop (Anthropic) — Settings → Developer → Edit Config. The most common choice.
Claude Code (Anthropic) — the CLI; add it with claude mcp add.
Goose (Block) — open-source desktop/CLI agent.
LibreChat, 5ire, Witsy — open-source chat apps.

Code editors & IDEs

Cursor
Visual Studio Code — GitHub Copilot agent mode.
Windsurf (Codeium)
JetBrains IDEs — IntelliJ, WebStorm, PyCharm, … (AI Assistant, 2025.2+).
Zed

Editor extensions

Cline, Roo Code, Continue (VS Code / JetBrains).

The setup is the same everywhere: register a server with the command npx -y @wadood/mcp and the three environment variables from Step 2. Each client just has a different place to put it (a JSON config file, a settings panel, or a CLI command). Prerequisite: Node.js 20+ on the machine.

For the full, always-current list of MCP-capable apps, see the official MCP clients directory.

Good habits

Start read-only. Explore with WADOOD_MCP_READ_ONLY=true (Option 2) or by approving read-only scope (Option 1), then switch it off when you're confident.
One token per device. Easier to revoke a single one if a laptop is lost. (Option 2.)
Watch the limits. Data, media, and user limits still apply — the assistant will surface a clear message if an action would exceed your plan, but it can't raise the limit for you.
Publish after sync. Synced Pages/Layouts/Shared Elements arrive unpublished in the target environment; publish them there to go live.
Review before you ship to Production. The assistant is fast; a quick look at what it built (or a preview) before publishing is always worth it.
Custom domains need you. When you add or change a site's domain, you must verify DNS ownership yourself: in the portal open Site Configuration → Verify, copy the TXT record value it shows, add it as a DNS TXT record at your DNS provider (Cloudflare, GoDaddy, …), then click Verify again. The assistant will walk you through these steps — it can't sign in to your DNS provider or add the record for you, and the site won't connect on that domain until it's verified.

Troubleshooting

Symptom	Likely cause / fix
Option 1: the sign-in window doesn't finish, or the tools never appear	Make sure pop-ups aren't blocked for the assistant, and that you clicked Allow on the authorization screen. Re-add the URL `https://mcp.wadood.io/mcp` and try Connect again.
Option 2: edited the config but nothing appears — no wadood tools, and the server isn't even listed	The client wasn't fully quit, so it never re-read the config. Closing the window isn't enough — on Windows the app keeps running in the system tray (bottom-right, under the `^`), on macOS in the menu bar. Right-click the Claude icon → Quit (or just restart your computer), then relaunch. The config is only read on a real restart.
Option 2: client shows the server as failed to start	Check the `command`/`args` and that Node.js 20+ is installed. Re-open the client after editing config.
Authentication errors	Option 2: the token is wrong, expired, or revoked — generate a new one from the MCP Access Tokens card and update the config. Option 1: your session expired or access was revoked — Connect and Allow again.
Every change is rejected	You're in read-only mode. Option 2: set `WADOOD_MCP_READ_ONLY` to `false` (or remove it). Option 1: reconnect and approve read & write scope.
Permission denied on an action	Your account lacks that privilege — the MCP can't grant more than your role allows. Ask an administrator to adjust your role.
Storage / user limit message	You've hit a plan limit. Free up space/seats or upgrade the plan; this isn't something the connector can override.

For the technical reference, see the package's README.md and SKILL.md on npm.

AI Assistant (MCP) ​

Introduction ​

Two ways to connect ​

Option 1 — Connector ​

Option 2 — npx MCP ​

Step 1 — Generate your access token ​

Step 2 — Register the connector in your client ​

How to use it ​

Which AI clients can I use? ​

Good habits ​

Troubleshooting ​