Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nudgen.net/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Nudgen MCP gives AI agents tool-based access to your Nudgen workspace. Use it when your agent supports Model Context Protocol and you want it to call Nudgen tools directly instead of writing REST requests.

Hosted server

Connect to Nudgen over HTTPS. No local MCP server process is required.

PAT auth

Use the same Personal Access Token as the Developer API.

Campaign tools

Create contacts, draft emails, create campaigns, and schedule launches.

​
Why this matters

MCP lets an AI assistant operate through structured Nudgen tools. That makes workflows like “create this contact, draft a campaign, schedule it for tomorrow, and report stats” easier for the agent to perform reliably. Use MCP when your agent supports Model Context Protocol tools. The Nudgen MCP server is hosted, so you do not need to run a local server process. 
Server URL:  https://nudgen.net/api/mcp
Server card: https://nudgen.net/.well-known/mcp/server-card.json

​
Before you connect

  1. Create a Personal Access Token from Settings -> API Keys.
  2. Store the token as an environment variable, for example NUDGEN_PAT.
  3. Confirm your active workspace in Nudgen. MCP tools operate on the token owner’s active workspace.
export NUDGEN_PAT="pat_..."
The MCP server can create contacts, update brand settings, create campaigns, and launch real email. Keep manual approval enabled for tool calls when your MCP client supports it.

​
Claude Code

Add Nudgen as an HTTP MCP server: 
claude mcp add --scope project --transport http nudgen "https://nudgen.net/api/mcp" \
  --header "Authorization: Bearer ${NUDGEN_PAT}"
If you prefer project config, add this to .mcp.json: 
{
  "mcpServers": {
    "nudgen": {
      "type": "http",
      "url": "https://nudgen.net/api/mcp",
      "headers": {
        "Authorization": "Bearer ${NUDGEN_PAT}"
      }
    }
  }
}
Restart Claude Code or run its MCP refresh command, then ask: 
List my Nudgen campaigns using MCP tools.

​
Cursor

Open Cursor Settings -> Tools & MCP -> New MCP Server and add: 
{
  "mcpServers": {
    "nudgen": {
      "type": "http",
      "url": "https://nudgen.net/api/mcp",
      "headers": {
        "Authorization": "Bearer ${NUDGEN_PAT}"
      }
    }
  }
}
Restart Cursor if the tools do not appear immediately. Then ask Cursor to use MCP tools, for example: 
Use Nudgen MCP to show my active team and recent campaigns.

​
Windsurf

Open the Windsurf MCP configuration and add the hosted HTTP server: 
{
  "mcpServers": {
    "nudgen": {
      "type": "http",
      "url": "https://nudgen.net/api/mcp",
      "headers": {
        "Authorization": "Bearer ${NUDGEN_PAT}"
      }
    }
  }
}
Reload Windsurf after saving. If your Windsurf version does not support HTTP MCP headers, use the REST API directly until header support is available.

​
Codex CLI

Add the server to your Codex MCP configuration: 
[mcp_servers.nudgen]
type = "http"
url = "https://nudgen.net/api/mcp"

[mcp_servers.nudgen.headers]
Authorization = "Bearer ${NUDGEN_PAT}"
Then verify the server is available: 
codex mcp list

​
Generic MCP clients

Any MCP client that supports hosted HTTP MCP servers and custom headers can connect with this configuration: 
{
  "name": "nudgen",
  "type": "http",
  "url": "https://nudgen.net/api/mcp",
  "headers": {
    "Authorization": "Bearer ${NUDGEN_PAT}"
  }
}
If your client only supports local command-based MCP servers, use the REST API for now or run a small local proxy that forwards requests to https://nudgen.net/api/mcp with the Authorization header.

​
Verify with JSON-RPC

You can verify the server without an MCP client: 
curl -X POST https://nudgen.net/api/mcp \
  -H "Authorization: Bearer ${NUDGEN_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

​
Available MCP tools

Available MCP tools mirror the core REST workflows:
ToolREST equivalent
get_current_userGET /api/v1/user/me
list_contactsGET /api/v1/contacts
create_contactPOST /api/v1/contacts/add
list_campaignsGET /api/v1/campaigns
create_campaignPOST /api/v1/campaigns
launch_campaignPOST /api/v1/campaigns/:id/launch
get_campaign_statsGET /api/v1/campaigns/:id/stats
get_brand_settingsGET /api/v1/settings/brand
update_brand_settingsPATCH /api/v1/settings/brand
generate_email_draftPOST /api/v1/ai/generate

​
Troubleshooting

SymptomWhat to check
UnauthorizedConfirm the PAT is copied correctly, not revoked, and sent as Authorization: Bearer <token>.
Tools do not appearRestart the MCP client and confirm it supports hosted HTTP MCP servers.
Writes fail with 403Confirm the workspace plan and role can perform write actions.
Campaign does not sendConfirm the campaign worker is running and the campaign has eligible contacts.
Dashboard stats stay at zeroTest sends are excluded from launched campaign stats. Launch a real campaign or schedule one through launch_campaign.

​
Security recommendations

  • Create a separate PAT for each agent or environment.
  • Revoke tokens when an agent, laptop, CI job, or workspace is no longer trusted.
  • Keep manual approval enabled for write tools such as create_campaign, launch_campaign, and update_brand_settings.
  • Use future scheduledAt values when testing campaign launch workflows.
  • Avoid pasting raw PATs into chat logs, issue comments, or source files.

​
REST alternative

If your client does not support hosted HTTP MCP servers or custom headers, use the Developer API. The REST API uses the same PAT and exposes equivalent campaign, contact, brand, and AI draft operations.