Skip to main content

​
Overview

Nudgen hosts an MCP server at your app origin’s /mcp endpoint. It speaks MCP 2026-07-28 over Streamable HTTP and requires OAuth 2.1. Connect a client that supports that transport. Sign in to Nudgen in your browser, choose a workspace, and approve the permissions the client requests. Your connection stays bound to that workspace, even if you later switch workspaces in the dashboard.

​
Why this matters

Your assistant can read contacts and campaigns, find nearby businesses, draft content, and prepare a campaign for launch without handling a dashboard session or a Personal Access Token. You review each real send or schedule in your browser before it can proceed.

​
Connect your client

The production endpoint is:
Add it as a remote HTTP MCP server in a client with OAuth support. The client discovers Nudgen’s authorization server from the endpoint and opens a browser sign-in and consent flow. Select the workspace you want the client to access and approve only the scopes it needs. Discovery documents: The authorization server uses authorization code with PKCE S256, resource binding, and refresh-token rotation. It accepts Client ID Metadata Documents and dynamic client registration. For Codex CLI, use:
If a client named nudgen is already configured, update that entry with the /mcp URL. If you only need to inspect data, request campaigns:read. Add campaigns:write when the client should change contacts, drafts, brand settings, or imported leads. Add campaigns:send only when the client needs to request launch approval.
Personal Access Tokens authenticate the Developer API, but they do not authenticate /mcp. An MCP client must complete OAuth sign-in.

​
Available tools

create_campaign saves a draft one-time campaign. It cannot send or schedule directly. get_campaign lets you check the subject, content, link, audience, and sender before launch. The server also exposes read-only resources on campaigns:read:

​
Find and import map leads

  1. Ask the assistant to call search_map_leads with a location and business keywords, such as a city and marketing agency.
  2. Optional filters are radiusKm (1–100), lat and lng, and emailOnly to keep businesses that publish an email.
  3. When the result includes nextPageToken, pass it as pageToken to load another page.
  4. Ask the assistant to call import_map_leads with the same location and keywords, plus the lead objects to save. Each call accepts up to 200 leads.
Import writes contacts in the connected workspace. Leads without an email are skipped. A lead that already exists is updated.

​
Approve a campaign launch

  1. Ask the assistant to inspect the draft with get_campaign.
  2. Ask it to call prepare_campaign_launch with the campaign ID and the exact send-now or scheduled time you want. This returns a one-time approval URL; no email is sent yet.
  3. Open the URL, review the workspace, recipient estimate, content, sender, and timing, then click Approve launch.
  4. Return to the client so it can call launch_campaign with the same campaign ID, timing, and approvalId.
An approval expires after 10 minutes and can be used once. If the campaign or sender changes, request a new approval. Nudgen checks sender readiness, eligible recipients, subscription, quota, and queue availability again when launching. Delivery begins only after the campaign worker processes the launch.
Approving and completing launch_campaign can send real email. Use the dashboard’s test-send flow to check an inbox preview before approving a real audience.

​
Manage access

Open Settings → API Keys → Connected MCP apps to see each connected client’s workspace and scopes. Revoke a connection there if it should no longer have access. Revocation disables its tokens and pending launch approvals. You can reconnect through OAuth later. OAuth grants last at most 90 days. Losing access to a workspace also prevents the client from using that workspace’s connection.

​
Troubleshooting

For scripts using bearer tokens and direct REST endpoints, see the Developer API.