MCP Server Setup

The NUDG3 MCP (Model Context Protocol) server lets you query your workspace data from any MCP-compatible AI client. Once connected, the client can pull visibility metrics, run competitive analysis, fetch boosters, and trace citations — without leaving the chat.

NUDG3 is published two ways:

• nudg3-mcp on PyPI — the stdio package (uvx nudg3-mcp / pip install nudg3-mcp), used by every desktop/editor MCP client today.
• Hosted Streamable HTTP at https://mcp.nudg3.ai/mcp — the same tools, served over HTTPS for clients (and bridges) that prefer remote.

Pick the path that matches your client:

What you get

Eleven composable investigation tools, callable from your AI client:

These are composable — your AI client chains them to answer complex questions. Ask Claude "how am I doing on retirement queries vs Capitec" and it will call analyze_competitors + analyze_prompts and reason over the combined output.

Every tool that returns workspace data (everything except get_metric_catalog and list_workspaces) accepts an optional workspace_id parameter — required only for agency-scoped keys that authorise more than one workspace. See API key personas.

Prerequisites

1. An active NUDG3 workspace (or agency).
2. An API key with read:analytics and read:insights scopes — generate at app.nudg3.ai/api-keys.
3. Your client of choice (Claude Desktop, Cursor, or Windsurf).

Each client adds one tool-specific dependency — noted below.

API key personas

Since 1.1.0, the MCP server supports two key scopes. The MCP behaviour depends on which you hold:

Most customers (single brand, one workspace) want a workspace-scoped key. Agencies managing multiple clients want one agency-scoped key — the "service account" pattern — instead of N workspace keys to rotate separately.

Generating your API key

Workspace key (single-workspace customers, recommended for personal use)

1. Open app.nudg3.ai/api-keys.
2. Confirm the workspace switcher (top-left) is on the workspace you want this key for.
3. Click Create API key.
4. Tick scopes: read:analytics and read:insights.
5. Name it (e.g., Claude Desktop).
6. Copy the key immediately — it's shown once, then you only see the prefix.

The key inherits the workspace's binding — no further configuration needed in the MCP client.

Agency key (multi-client / multi-workspace, agency admins only)

Only users with the agency admin role (or super-user role) can mint agency-scoped keys. The dashboard surfaces this option when you have the appropriate role. The flow:

1. Open app.nudg3.ai/api-keys.
2. Switch to the Agency keys tab.
3. Confirm the portfolio preview — the dialog lists every workspace this key will be able to access.
4. Click Create agency key.
5. Name it (e.g., BI tooling production).
6. Tick scopes: read:analytics and read:insights.
7. Optionally restrict by IP (CIDR list — strongly recommended for production tooling).
8. Default expiration is 90 days (vs 365 for workspace keys); we recommend keeping it.
9. Confirm the blast-radius checkbox and submit.
10. Copy the key immediately. Store it in your secrets manager, not in source control.

Agency keys begin with nudg3_live_aak_ (note the aak) — workspace keys begin with nudg3_live_ak_. The third underscore position tells you the scope at a glance.

Distribution

The stdio package and the hosted endpoint serve the same 11 tools backed by the same backend. Stdio runs in your client process; hosted runs on NUDG3's infrastructure.

Claude Desktop

Claude Desktop is configured via a JSON config file. The desktop app's Settings → Connectors UI does not yet accept static Bearer-token authentication for arbitrary remote MCP servers — that path needs OAuth. Until OAuth ships, use one of the two config-file routes below.

Route A: Hosted via mcp-remote bridge (recommended)

mcp-remote is a tiny npm package that wraps any remote MCP server as a stdio process, with full support for --header injection. This is the lightest-touch way to use the hosted endpoint from Claude Desktop.

Prerequisite: Node.js 18+ installed locally (node --version to verify).

1. Open the config file. Easiest way:

   • In Claude Desktop: Settings (Cmd-, on macOS / Ctrl-, on Windows) → Developer in the left sidebar → click Edit Config. Claude Desktop opens the file in your default text editor and creates it if it doesn't exist yet. Use this — it's the path Anthropic supports.

   If you must open it from a terminal instead (mind the spaces in the path — they need quoting):

   • macOS: open -a TextEdit "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
     • If the file doesn't exist yet, create it first: mkdir -p "$HOME/Library/Application Support/Claude" && echo '{}' > "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
   • Windows (PowerShell): notepad "$env:APPDATA\Claude\claude_desktop_config.json"
     • If missing: New-Item -ItemType Directory -Force "$env:APPDATA\Claude" | Out-Null; Set-Content "$env:APPDATA\Claude\claude_desktop_config.json" '{}'
   • Linux: xdg-open "$HOME/.config/Claude/claude_desktop_config.json"

2. Add the NUDG3 entry:

   {
     "mcpServers": {
       "nudg3": {
         "command": "npx",
         "args": [
           "-y", "mcp-remote",
           "https://mcp.nudg3.ai/mcp",
           "--header", "Authorization: Bearer nudg3_live_ak_..."
         ]
       }
     }
   }

3. Replace nudg3_live_ak_... with the key from app.nudg3.ai/api-keys.

4. Restart Claude Desktop — fully quit (Cmd-Q / right-click → quit) and relaunch. MCP servers load at startup; closing the window isn't enough.

5. Confirm: click the 🔨 icon in the chat composer — you should see the 10 NUDG3 tools.

6. Try it: ask "Pull my NUDG3 visibility overview for this week". Claude calls get_overview, asks permission, returns results.

mcp-remote is fetched on-demand by npx; no global install needed. Restart your client after any header/URL change.

Route B: Stdio direct via uvx nudg3-mcp

If you prefer a Python-based bridge (or don't have Node.js installed), use the stdio package directly.

Prerequisite: uv installed locally:

• macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
• Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
• Alternative: pip install nudg3-mcp and use python -m nudg3_mcp instead of uvx nudg3-mcp.

Config (same file as above):

{
  "mcpServers": {
    "nudg3": {
      "command": "uvx",
      "args": ["nudg3-mcp"],
      "env": {
        "NUDG3_API_KEY": "nudg3_live_ak_..."
      }
    }
  }
}

Restart Claude Desktop. Confirm via the 🔨 icon.

NUDG3_API_URL defaults to https://api.nudg3.ai — don't set it unless pointing at a non-prod environment.

Cursor

Cursor supports both stdio and Streamable HTTP MCP servers natively, and accepts a custom Authorization header for the latter. Use the hosted endpoint directly.

Cursor → Settings → MCP → Add Server. Or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "nudg3": {
      "url": "https://mcp.nudg3.ai/mcp",
      "headers": {
        "Authorization": "Bearer nudg3_live_ak_..."
      }
    }
  }
}

Restart Cursor. The 10 tools appear in the agent panel.

For added security, reference an environment variable instead of inlining the key:

"headers": {
  "Authorization": "Bearer ${env:NUDG3_API_KEY}"
}

Windsurf

Same shape as Cursor. Path: ~/.codeium/windsurf/mcp_config.json (verify per your Windsurf version).

{
  "mcpServers": {
    "nudg3": {
      "url": "https://mcp.nudg3.ai/mcp",
      "headers": {
        "Authorization": "Bearer nudg3_live_ak_..."
      }
    }
  }
}

If your Windsurf build doesn't support the url / headers fields yet, fall back to the same stdio pattern as Claude Desktop Route B (uvx nudg3-mcp + NUDG3_API_KEY env var).

claude.ai web and ChatGPT (not yet)

Both platforms have UI dialogs to add custom MCP servers, but their auth fields only accept OAuth client_id / client_secret — no static Bearer token / custom header option. The NUDG3 MCP server uses Bearer auth (your existing API key), so the direct paste-the-URL flow does not work yet.

Workarounds:

• Use one of the config-file paths above on a desktop client (Claude Desktop, Cursor, Windsurf).
• Use the NUDG3 REST API via ChatGPT custom GPT actions if you specifically need ChatGPT.

Both browser connectors will work with NUDG3 once OAuth support ships.

What to ask once connected

Governance

The MCP server inherits everything that protects the REST API:

• Tenant-isolated — workspace-scoped keys see one workspace. Agency-scoped keys see their portfolio only; cross-scope requests return 403 WORKSPACE_ACCESS_DENIED. Resolution is enforced at the backend, not by the MCP client, so a compromised client can't escalate.
• Audit-logged — every tool call recorded with timestamp + resolved workspace + tool name + X-Client-Type: mcp header. For agency keys, the audit log shows the resolved workspace per call, so you can see which clients the key actually queried.
• Scope-restricted — the API key's scopes limit which tools work (read:analytics for overview/competitors/prompts/sources/responses/exports, read:insights for reports/insights/actions, export:data for CSV export).
• Rate-limited — same 3-tier sliding window as the REST API (Starter 30/min, Professional 120/min, Enterprise 600/min). For agency keys the limit is per-key, not per-workspace; if you have a noisy BI workload, consider one agency key per major workflow rather than sharing one.
• Brute-force protected — 10 failed auth attempts in 5 minutes triggers a 15-minute lockout from your IP. The hosted endpoint forwards the original client IP via X-Forwarded-For so the lockout tracks per real user, not per shared Cloud Run NAT.
• Read-only in v1 — no write operations exposed to the AI client.
• TLS everywhere — hosted endpoint served via Cloudflare with always-on HTTPS.
• IP allow-list (agency keys) — agency-scoped keys accept an optional allowed_ips (CIDR list) at creation. Requests from outside the allow-list are rejected before the scope check runs. Use this for production tooling.

For enterprise customers, this is the compliance answer that unlocks AI council approval — your team can use Claude/Cursor with NUDG3 data because it's wired through a governed MCP server with audit logs and tenant isolation.

Agency-key security checklist

If you're issuing agency-scoped keys, treat them with the same care as a service-account credential:

• Store the secret in a managed vault (1Password, AWS Secrets Manager, GCP Secret Manager, Vault) — never in source control.
• Enable allowed_ips if the consumer runs on stable infrastructure.
• Default expiration is 90 days. Set a calendar rotation reminder; rotation is one new-key-mint + one revoke.
• Use one key per integration, not one key for "everything". Revoke surgically when a tool is decommissioned.
• Audit usage monthly via the dashboard — look for unfamiliar last_used_ip values or new workspace IDs being queried.
• Revoke immediately on departure of any employee with access.

Troubleshooting

Hosted (mcp-remote bridge or direct HTTP)

Stdio (uvx nudg3-mcp)

Related