MCP server — connect an AI client to Madoo

Madoo exposes a Model Context Protocol (MCP) server. Once an AI client (Claude, ChatGPT, Codex, Cursor, VS Code, Lovable, …) is connected, the assistant can do from a conversation everything this guide describes over REST: browse the node catalog, author workflows and document templates, validate and publish them, run them, follow the run and read the results.

The MCP server and the REST API v1 are two doors onto the same workspace: a workflow the assistant creates over MCP appears in the Madoo editor, and one you design in the editor can be run by the assistant. Credits are consumed the same way — only when something is executed or rendered.

Before you start you need a Madoo account whose plan includes API access (MCP counts as API access). If the account’s plan does not include it, every tool call fails with api_access_disabled.

---

1. The two MCP endpoints

Endpoint	Authentication	Use it for
{BASE_URL}/mcp	OAuth — the client registers itself, opens a Madoo login page, you pick the workspace and approve. Nothing to copy or paste.	Every interactive AI client. This is the normal way.
{BASE_URL}/mcp/automation	Bearer token obtained from an API key (01-authentication.md §1–§2).	Scripts, agents running unattended, or a client that cannot do OAuth but can send a static header.

For Testing the two URLs are:

https://testing-api.madoo.ai/mcp
https://testing-api.madoo.ai/mcp/automation

The two endpoints are deliberately separate: an OAuth token is refused on /mcp/automation, an API-key token is refused on /mcp. The OAuth token is also not a REST token — for REST calls use an API key.

---

2. What happens on first connection (OAuth, /mcp)

Whatever the client, the first connection follows the same steps. Knowing them makes every client below easy to follow.

1. You give the client the server URL (https://testing-api.madoo.ai/mcp).
2. The client calls it, receives 401 and discovers from the response where Madoo’s authorization server is (https://testing-auth.madoo.ai). It registers itself automatically — you never create a client id or a secret.
3. A browser window opens on the Madoo sign-in page. Sign in with your Madoo email and password.
4. Choose the organization and the workspace the assistant will work in. The connection is bound to that single workspace: the assistant sees only its workflows, templates, assets and executions.
5. Review the requested permissions (scopes, §6) and approve. The browser hands control back to the client, which now lists Madoo’s tools.

After that the client refreshes its access silently (access tokens last 15 minutes; the refresh token keeps the connection alive for up to 14 days of inactivity). You can see and revoke every connection in the portal under Settings → Connected apps (https://testing-portal.madoo.ai/settings/connected-apps).

Wrong workspace? The workspace is chosen at step 4 and cannot be switched from the client. Remove the connector (or revoke it in Connected apps) and connect again, choosing the right workspace.

---

3. Connecting each client

Status legend — verified: a real connection from that client has completed OAuth and called tools on Madoo Testing; documented: the client supports remote MCP with OAuth and the steps follow its official documentation, but we have not yet recorded a connection from it on Testing. Menu names in third-party products change often; if a label differs, look for “connectors”, “integrations” or “MCP”.

3.1 Claude — web (claude.ai) and Claude Desktop · verified

1. Open Settings → Connectors and choose Add custom connector.
2. Name: e.g. Madoo (Testing). URL: https://testing-api.madoo.ai/mcp. Leave the advanced OAuth fields (client id / secret) empty — Madoo registers the client automatically.
3. Click Connect, then follow §2 in the browser window.
4. In a conversation, enable the connector from the tools menu ( + / “Search and tools”) if it is not already on.

On a Claude Team/Enterprise plan, custom connectors may have to be added by an organization owner (Organization settings → Connectors); each member then connects with their own Madoo account. The connector is shared between claude.ai, Claude Desktop and the Claude mobile apps.

3.2 Claude Code (terminal) · verified

Run this in your own terminal, not by asking Claude to run it:

claude mcp add --transport http --scope user madoo-testing https://testing-api.madoo.ai/mcp

Then start a new Claude Code session, type /mcp, select madoo-testing and choose Authenticate: the browser opens on §2. Claude Code keeps the token and renews it by itself — nothing expires after an hour.

• --scope user makes the server available in every folder. Without it the server is registered only for the folder where the command ran (the local scope): open Claude Code in another folder and the server is not there. --scope project shares it with the repository through .mcp.json instead (each person still authenticates with their own account).
• Servers are loaded when a session starts. A server added while a session is open — for example by Claude running claude mcp add itself — appears only in the next session.
• Check it worked: /mcp shows madoo-testing as connected with its tools. Claude Code loads MCP tools on demand, so they are not in the model’s list from the start: ask for something Madoo does (“list my workflows”) or search the tools for madoo — they are named mcp__madoo-testing__search_node_types and so on.
• claude mcp list checks the servers configured for the folder it runs in. “Connected” there only says the server answers; it does not prove the open session loaded it.

Use the API-key route (§4) only for scripts: its token lasts one hour and a header written into the configuration does not renew.

3.3 OpenAI Codex (CLI and IDE extension) · documented

codex mcp add madoo-testing --url https://testing-api.madoo.ai/mcp
codex mcp login madoo-testing

codex mcp login opens the browser on §2. The same server is written to ~/.codex/config.toml and is shared with the Codex IDE extension:

[mcp_servers.madoo-testing]
url = "https://testing-api.madoo.ai/mcp"

Older Codex versions need experimental_use_rmcp_client = true at the top of config.toml for remote servers with OAuth — update Codex if mcp login is not recognised.

3.4 ChatGPT · verified

Custom MCP connectors require ChatGPT developer mode (available on paid plans; on Business/Enterprise an admin may have to allow it).

1. Settings → Apps & Connectors → Advanced settings: turn on Developer mode.
2. Back in Apps & Connectors, choose Create (new connector). Name Madoo (Testing), MCP server URL https://testing-api.madoo.ai/mcp, authentication OAuth. Accept the “custom connector” notice.
3. Connect and follow §2.
4. In a chat, pick Developer mode from the + menu and enable the Madoo connector.

3.5 Lovable · verified

1. In Lovable open Settings → Connectors (personal connectors / MCP servers) and add a custom MCP server.
2. Server URL: https://testing-api.madoo.ai/mcp, authentication OAuth. Connect and follow §2.
3. In a project chat, ask Lovable to use Madoo (e.g. “search the Madoo workflows of my workspace”).

If Lovable later reports token expired, use its reconnect action (or remove and re-add the connector): this is a client-side refresh behaviour, your Madoo account and workflows are unaffected.

3.6 Visual Studio Code (GitHub Copilot) · documented

Add the server to .vscode/mcp.json in your workspace (or to your user mcp.json via MCP: Open User Configuration):

{
  "servers": {
    "madoo-testing": {
      "type": "http",
      "url": "https://testing-api.madoo.ai/mcp"
    }
  }
}

Click Start above the server entry; VS Code asks to allow authentication and opens §2. The tools are available in Copilot Chat in Agent mode.

3.7 Cursor · documented

Cursor Settings → MCP (Tools & Integrations) → New MCP server opens ~/.cursor/mcp.json (or use .cursor/mcp.json in a project):

{
  "mcpServers": {
    "madoo-testing": {
      "url": "https://testing-api.madoo.ai/mcp"
    }
  }
}

Back in the MCP settings the server shows Needs login / Connect: click it and follow §2.

3.8 Any other MCP client

Madoo works with any client that supports the streamable HTTP transport and OAuth 2.1 with automatic (dynamic) client registration — give it https://testing-api.madoo.ai/mcp and nothing else. Madoo does not serve the legacy SSE transport. If a client can only send a static header, use §4.

---

4. The API-key route (/mcp/automation)

For scripts and unattended agents, or when you want to pin exactly which scopes a connection has:

1. In the portal, Settings → API keys (https://testing-portal.madoo.ai/settings/api-keys), create a key in the right workspace and select its scopes (§6). Copy client_id and client_secret — the secret is shown only once.

2. Exchange it for a token (valid one hour, no refresh — request a new one when it expires):

   curl -s -X POST "https://testing-api.madoo.ai/api/v1/auth/token" \
     -u "$MADOO_CLIENT_ID:$MADOO_CLIENT_SECRET" \
     -d "grant_type=client_credentials"

3. Configure the client with the automation URL and the header Authorization: Bearer <access_token>. For example, Claude Code:

   claude mcp add --transport http madoo-automation https://testing-api.madoo.ai/mcp/automation \
     --header "Authorization: Bearer $MADOO_ACCESS_TOKEN"

Because the token expires after an hour, this route is meant for automation that can fetch a fresh token itself; for day-to-day interactive use prefer OAuth (§2–§3).

---

5. What the assistant can do

The server exposes 63 tools, grouped in families: a tool with an operation (or view) argument covers the closely related commands REST v1 keeps as separate routes, so an assistant reads fewer, clearer tools. The server also sends the client a short set of instructions with the recommended flow, so a capable assistant follows it without being told; the list below is for you.

Area	Main tools
Discover the catalog	search_node_types, get_node_type, get_json_schema, list_fonts
Workflows — find, author, check, publish	search_workflows, get_workflow, create_workflow_draft, update_workflow_draft, update_workflow, validate_workflow, estimate_execution, publish_workflow, inspect_data_source
Run and read results	execute_workflow, get_execution, list_executions, get_execution_result, get_execution_outputs, get_execution_trace, cancel_execution
Files as inputs	list_assets (find a file already in the workspace by name), create_asset_upload + finalize_asset_upload (local files, see below), import_asset_from_url, upload_asset (tiny files only), resumable_asset_upload for large multipart uploads (operation sign_part, status, complete, abort)
Workflow folders	get_workflow_folder (view content: subfolders and workflows of a folder; view tree: every folder), organize_workflow_folders (operation create or move) — the editor’s folder tree, e.g. a folder of example workflows to learn from
Document templates — read	list_design_templates (status: published, draft, archived, all), get_design_template (view: contract, versions, draft, outline, content, readiness, palette), list_design_template_shapes, preview_design_template_sample_set, render_design_template (output pdf or pages)
Document templates — author	create_design_template_draft (optionally from a whole content document), replace_design_template_content, duplicate_design_template; pages edit_design_template_page (add, update, duplicate, move) and master pages edit_design_template_master_page (create, assign, set_rule, batch_assign); elements add_design_template_text, add_design_template_static_image, add_design_template_image_placeholder, add_design_template_repeating_text_list, shapes, lines, SVG, update_design_template_element (condition, char_spacing, z_order, follows_row_height, link, …), arrange_design_template_elements, configure_design_template_repeat, configure_design_template_element_placeholder, edit_design_template_palette, edit_design_template_style, edit_design_template_component; samples edit_design_template_sample_set; remove_design_template_item (element, page, master page — the only destructive edit)
Document templates — publish	publish_design_template_draft, change_design_template_lifecycle (action archive or revert_to_draft)
Templates in workflows	nodes design/template_render (one document, pinned revision, page images), document/pdf (one PDF) and aggregate/pdf (one PDF with a page set per item of an iteration) take template_id + optional template_revision; their input ports are the template’s field codes. get_workflow_template_revisions / upgrade_workflow_template_revision review and move a saved pin — see 10 §1.2
Bundles	compose_bundle_manifest, validate_bundle_manifest
Webhooks	list_webhooks, manage_webhook

REST v1 keeps one route per command, and the in-app AI agent one capability per command (it only sees the template capabilities in the turns that author templates, and each keeps its own approval and audit); the MCP families call the same Application services, so results and errors are the same on every surface.

The recommended authoring loop is: discover → draft → validate (repeat until valid) → estimate → publish → execute → poll → read results. Only published workflows run; the draft and the published version are tracked with an etag so two editors cannot overwrite each other.

Passing files. Chat clients cannot send a large file through the conversation itself, so:

• Public URL → import_asset_from_url (Madoo downloads and stores it).
• Local file, client with a shell (Claude Code, Codex, Cursor, VS Code) → create_asset_upload returns an upload URL, the assistant PUTs the bytes with the listed headers, then calls finalize_asset_upload to get the asset_path to use as a workflow input. The file bytes never pass through the conversation.
• File attached to a web chat (claude.ai) → the same create_asset_upload flow: the chat’s code-execution sandbox receives the attachment and PUTs it to the upload URL. It needs code execution enabled in the chat’s settings and its network access allowed to the storage host of the upload URL (*.blob.core.windows.net). Verified on claude.ai on 2026-09-27; where that is not available, upload the file in the Madoo portal and let the assistant find it with list_assets.
• File already in Madoo (uploaded in the portal, imported, produced by a run) → list_assets with part of its name returns its asset_path.
• Tiny file (≤ 64 KiB) → upload_asset with base64 content.

---

6. Permissions (scopes)

The consent screen (OAuth) and the API-key form use the same scope vocabulary as the REST API (01-authentication.md §3.2):

Scope	Lets the assistant…
catalog:read	read the node catalog, models, presets, effects
workflows:read	find and read workflows, validate and estimate them
workflows:write	create, edit and publish workflows
workflows:execute	start and cancel runs — the permission that spends credits
executions:read	follow runs and read their results
assets:read / assets:write	list / upload and import files
design-templates:read / design-templates:write	read / author and publish document templates
webhooks:read / webhooks:write	read / manage webhook subscriptions

On top of the scopes, your workspace role still applies: a scope never grants more than your role in that workspace allows.

The tool list follows the scopes. tools/list — what the assistant reads at the start of every conversation — shows only the tools the connection’s scopes allow: a key for running workflows (catalog:read workflows:read workflows:execute executions:read assets:write) sees about 25 tools, not the ~35 document-template authoring tools it could not use. A tool called by name anyway answers with its own missing_scope error. Grant design-templates:write only to connections that author templates.

6.1 Choosing toolsets

A connection can also ask for some toolsets only, with ?toolsets= on the MCP URL or the X-MCP-Toolsets header (comma-separated; the same convention as the GitHub MCP server). Without it, every toolset the scopes allow is listed.

Toolset	Tools
catalog	search_node_types, get_node_type, get_json_schema, list_fonts
workflows	find, author, validate, estimate and publish workflows; folders; template pins
executions	execute_workflow, cancel_execution and the execution reads (result, outputs, trace)
assets	uploads, URL import, data-source inspection, bundle manifests
templates	list_design_templates, get_design_template, render_design_template, preview_design_template_sample_set
template_authoring	every document-template edit (about 30 tools, the largest group)
webhooks	list_webhooks, manage_webhook

# A connection that runs workflows and reads their results, nothing else
claude mcp add --transport http madoo-run "https://testing-api.madoo.ai/mcp?toolsets=catalog,workflows,executions,assets"

Toolsets shape the list only: a tool outside them still runs when called by name (and still checks its scopes). Pick them when the connection is created: changing the list during a conversation would invalidate the client’s prompt cache.

6.2 Answer size

A tool answer longer than about 80,000 characters (≈ 23,000 tokens; Claude Code refuses answers over 25,000 tokens) is replaced by the error response_too_large, which says how to ask for less on that tool — a page of the template outline (page_id), the document without its sample sets, a narrower search or a lower limit — or which REST v1 route returns the whole thing. get_design_template view content leaves the sample sets out unless include_sample_sets is true: they are example values, often with inline images, and can weigh most of a template.

---

7. Troubleshooting

Symptom	Cause and fix
The client lists no Madoo tools after adding the URL	Authentication was not completed. Run the client’s authenticate/login action (Claude Code /mcp, codex mcp login, Cursor Connect, VS Code Start).
Claude Code: claude mcp list says Connected, but the session finds no Madoo tool	The open session did not load the server: it was added during the session, or for another folder (local scope). Add it from your terminal with --scope user and start a new session (§3.2).
Claude Code with /mcp/automation: the tools worked, then vanished or answer 401	The token written in --header expired after one hour. Use OAuth on /mcp (§3.2), or re-add the server with a fresh token.
api_access_disabled	The organization’s plan does not include API access.
The assistant cannot find your workflows	The connection is bound to another workspace (§2, step 4). Revoke it and reconnect choosing the right one.
missing_scope / permission denied on one tool	The connection lacks that scope — typically a connection created before the scope existed. Remove it and reconnect to approve the new scopes; for /mcp/automation, create a key with the scope.
“Token expired” in a web client	Use the client’s reconnect action or remove and re-add the connector.
A run stops for insufficient credits	Check the balance in the portal. Credits are reserved before a run and the unused part is returned.
401 on /mcp/automation	The API-key token expired (one hour) — request a new one. An OAuth token does not work on this endpoint.

Each reconnect registers a new client entry on the Madoo side; this is expected. Avoid repeated connect/disconnect loops: client registrations are capped per network address (200 per 24 hours on Testing), and a whole office behind the same public IP shares that cap.