Skip to main content

Overview

Nudgen hosts an MCP server at your app origin’s /mcp endpoint. It supports MCP 2026-07-28 over Streamable HTTP and requires OAuth 2.1. Sign in through your browser and approve the requested permissions. When available, choose access to one workspace or explicitly authorize all current and future workspaces you belong to. Dashboard workspace changes do not change the MCP default.

Work across workspaces

Existing connections stay limited to their original workspace until you reconnect and approve broader access. With all-workspace access, new memberships become available automatically; losing membership blocks subsequent actions in that workspace. Roles, subscriptions, and quotas still apply separately in each workspace. Use list_workspaces with page and pageSize to find workspace IDs, names, slugs, roles, and the default. It requires teams:read. Add workspaceId to a workspace tool call to override the default for that action. Omit it to use the connection default. Pass the same explicit workspace ID when reviewing and sending a campaign. Choose the default during OAuth consent. Change it in Settings → API Keys → Connected MCP apps or call set_default_workspace with workspaceId and the teams:write scope. This changes the default for every chat using that connection. An individual override does not change it. If the default is deleted or inaccessible, select another with an explicit override or update the default; Nudgen never silently picks a replacement.
Existing resource URIs use the default workspace. These resource templates target a workspace explicitly:

Why this matters

Your assistant can inspect contacts, find businesses, and create campaign drafts. Authorize sending or scheduling in chat, and the assistant runs the action directly without a browser approval link.

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. Request campaigns:read for inspection, campaigns:write for drafts and edits, and campaigns:send for authorized email actions. OAuth consent remains required.
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 campaign (one-time, drip, or lifetime). 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.

Launch a draft campaign

  1. Review the campaign name, subject, content, effective sender, audience estimate, and timing with get_campaign.
  2. Authorize the action in chat. The assistant calls launch_campaign directly with the campaign ID and either sendNow: true or scheduledAt with a future timestamp and timezone. Do not supply contradictory timing arguments. Existing authorization does not require another confirmation.
  3. Review the returned status, scheduled time, and dashboard link. Queued or scheduled does not mean delivered. Check get_campaign and get_campaign_stats before retrying an uncertain outcome.
Nudgen still checks workspace permissions, sender readiness, eligible recipients, subscription, quota, campaign version, and queue availability. Creation and editing remain draft-only; delivery requires the campaign worker.

Manage access

Open Settings → API Keys → Connected MCP apps to inspect access, change the default, or disconnect. Disconnecting a multi-workspace connection revokes its tokens and pending authorization codes across all workspaces without disconnecting separate REST connections. REST OAuth and the in-app assistant retain their existing workspace boundaries.

Troubleshooting

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

Search radius and enrichment

API and MCP searches default to 5 km and accept an explicit integer radiusKm from 1 to 100. They do not show the dashboard confirmation dialog. Keep the same search inputs when passing nextPageToken as pageToken; a page can contain no matching leads and still have another page. Contact enrichment may finish after businesses first appear. enrichmentPending marks unfinished website research. Review businessSummary and businessSources when available; imported business context can support personalized campaign introductions. A missing email can mean research is still pending. If enrichmentRetryToken is present, call retry_map_leads_enrichment with token to retry pending website research. It requires campaigns:read, is bound to the connected workspace, expires after 15 minutes, and can be used once. Merge returned leads by placeId before importing. emailOnly filters the current response; pending leads may appear after retry.

Edit drafts and product coverage

Use update_campaign to edit an existing draft and delete_campaign to delete a draft. Both require campaigns:write; neither sends or schedules email. New product domains require their own OAuth permissions. Reconnect and approve those permissions when requested. Tool discovery lists available tools and arguments. Browser handoffs do not complete actions: use the browser for payments, provider authorization, invitation sending, workspace creation/deletion/joining, and sensitive payout settings. MCP workspace targeting and default changes do not switch the dashboard workspace. Administrative functions, credentials, webhooks, tracking callbacks, and the internal assistant are excluded. Use get_api_capabilities to inspect API coverage. After authorization in chat, call send_test_email, activate_lifetime_campaign, or trigger_lifetime_campaign directly. Test sends go only to the account email. Lifetime activation enables future automated delivery. No browser approval or approval ID is required. Check status or execution history before retrying an uncertain outcome.