Who this is for
- Admins using AI agents to run their community — jump to MCP Admin Setup.
- Developers wiring Claude Code or a custom client — see Claude Code Setup and Bearer + Domain Headers.
- Contributors iterating on the MCP server itself — keep reading.
Authentication
Every HTTP request to the MCP server requires two headers:x-api-domain. See Bearer + Domain Headers for full details.
stdio transports (Claude Desktop) use env vars instead of headers.
Tool catalog
The MCP server exposes a set of tools categorised by concern. Tool availability is further filtered by thex-agent-mode header — see Agent modes.
Nudj platform CRUD
Core domain operations that read and write Nudj data.| Tool | Operations |
|---|---|
communities | CRUD on communities |
challenges | CRUD on challenges (with video metadata) |
actions | CRUD on engagement actions (28+ action types) |
achievements | CRUD on achievements / badges / milestones |
rewards | CRUD on rewards |
reward_allocations | Distribute rewards via challenge, achievement, action, leaderboard, manual, or giveaway |
leaderboards | Manage leaderboard configurations |
posts | Publish and edit admin posts (HTML content) |
analytics | 28 analytics operations across users, communities, challenges, achievements, rewards |
theme | Get / update organisation theme configuration |
Shopify
Shop-level integration for Shopify-backed organisations.| Tool | Operations |
|---|---|
shopify | 16 operations: get_shop, list_products, get_product, list_collections, list_orders, list_customers, get_customer_segments, list_discounts, analyze_products, get_store_health, get_discount_conflicts, get_widget_settings, set_widget_enabled, update_widget_theme, update_launcher_config, update_points_for_spend |
Public web & media
Tools that don’t require Nudj auth. Useful for research and content generation.| Tool | Operations |
|---|---|
web | Search the web, scrape page content |
social_posts | Retrieve social media posts |
youtube_channel | Fetch channel info and video lists |
youtube_video | Fetch video metadata and transcripts |
image | Generate, edit, upscale, background-remove, inpaint, outpaint images (FAL.ai + Nano Banana Pro) |
Docs & events
| Tool | Operations |
|---|---|
nudj_docs | Search the Nudj documentation |
watch | Subscribe to Nudj events and receive real-time updates |
Voice agent
A realtime voice-agent layer sits on top of the MCP tool catalog. Tool availability is filtered to the samex-agent-mode rules; the voice transport itself is a thin shell.
Agent modes
The server filters tool access based on thex-agent-mode header, so you can hand a narrower surface to less-trusted agents:
| Mode | Surface |
|---|---|
planner | Read-only Nudj operations plus public web/media tools |
builder | Full read-write on Nudj resources |
service | Public web and media tools only, no Nudj access |
x-agent-mode is omitted, the server defaults to the broadest surface your token’s RBAC role allows.
Transports
HTTP (recommended)
Serves MCP over Streamable HTTP. All cloud-hosted clients (Claude Code, Cursor, ChatGPT) use this.| Environment | URL |
|---|---|
| Production | https://mcp.nudj.cx/mcp |
| Development | https://mcp-dev.nudj.cx/mcp |
| Local | http://localhost:4010/mcp |
stdio
Used by Claude Desktop and other native desktop clients that spawn the server as a child process. See MCP Admin Setup for the canonical config.Local development
For contributors working on the MCP server itself:NEXTAUTH_SECRET so tokens validate end-to-end. See Claude Code Setup for the full local config.
Related
Admin / Claude Desktop
Admin panel MCP tokens and Claude Desktop stdio config.
Claude Code .mcp.json
Wire up Claude Code with
.mcp.json for cloud or local.Bearer + Domain Headers
The canonical auth pattern for HTTP MCP clients.
Troubleshooting
Diagnose auth, connection, and tool-call issues.