Getting Started

Connecting to Waalaxy MCP

The Waalaxy MCP server lets AI tools that speak the Model Context Protocol read your prospect lists and campaigns and import new prospects on your behalf, directly from a chat with your assistant of choice.

Once connected, the assistant can, with your permission:

list your prospect lists and campaigns,
import LinkedIn prospects into a list and optionally enrol them in a campaign,

All actions run with your account's permissions. The assistant cannot see or do anything you couldn't do yourself in the app.

The MCP server is available on the Advanced and Business Waalaxy plans only. You can check or upgrade your plan from the billing page.

Server URL

The Waalaxy MCP server is a remote server reachable over HTTP:

Code
 
https://stargate.prod.aws.waalaxy.com/api/mcp

It uses the Streamable HTTP transport, the modern transport supported by all major MCP clients.

Authentication

Connections use user-based OAuth 2.1. Bearer API keys (the kind used by the REST API) are not supported by the MCP server.

The flow is:

The MCP client opens a Waalaxy sign-in page in your browser.
You sign in with a magic link sent to the email address of your Waalaxy account.
The client receives an OAuth access token (valid for 1 hour) and a refresh token, and uses them to call the server on your behalf.

You do not need to copy or paste any token yourself. The MCP client handles the OAuth handshake for you.

Use the same email as your Waalaxy account when the magic link page asks for it. If you sign in with a different email, the server will not be able to map the session to your prospects and campaigns.

Available tools

The server exposes four MCP tools:

Tool	What it does
`get-prospectlists`	Returns every prospect list owned by the user (`_id`, `name`, `totalProspects`, icon). Use first to pick a `prospectListId`.
`get-campaigns`	Returns the user's paused and running campaigns (`_id`, `name`).
`add-prospects-to-list-campaign`	Imports one or more LinkedIn prospects into a list and, optionally, a campaign.

`add-prospects-to-list-campaign` inputs

Field	Type	Required	Description
`prospects`	array	yes	Each entry has a LinkedIn profile `url` and an optional `customProfile` (firstName, lastName, email, company, …).
`prospectListId`	string	yes	Target list id, obtained from `get-prospectlists`.
`campaignId`	string	no	Campaign id from `get-campaigns`. Omit if the user does not want a campaign enrollment.
`canCreateDuplicates`	boolean	no	Allow importing a prospect already present in the list. Default: `false`.
`moveDuplicatesToOtherList`	boolean	no	Move existing duplicates into this list instead of skipping. Default: `false`.
`addExistingProspectInCampaign`	boolean	no	When `campaignId` is set, also enroll already-existing prospects in the campaign. Default: `false`.

Prospect imports made through MCP are imported with the mcp origin in the Waalaxy app.

Error responses (`add-prospects-to-list-campaign`)

When the import cannot run (for example after a plan downgrade), the tool returns explicit JSON — not null and not a silent empty result. The assistant should read errorCode, userMessage, and assistantGuidance:


Code
 
{
    "ok": false,
    "errorCode": "PLAN_UPGRADE_REQUIRED",
    "reason": "The Waalaxy account is authenticated but lacks the manage_api_keys permission…",
    "userMessage": "The prospect import did not run. Your Waalaxy subscription must be Advanced or Business…",
    "assistantGuidance": "Tell the user the import failed because of their Waalaxy plan…",
    "requiredPlans": ["ADVANCED", "BUSINESS"],
    "upgradePath": "/upgrade"
}

`errorCode`	Typical cause
`PLAN_UPGRADE_REQUIRED`	Account on Freemium/Pro or missing `manage_api_keys` after downgrade
`CRM_LIST_LIMIT_EXCEEDED`	Target list quota reached for the current plan
`PROSPECT_LIST_NOT_FOUND`	Invalid `prospectListId` — call `get-prospectlists` first
`NO_VALID_PROSPECTS`	LinkedIn URLs could not be parsed
`IMPORT_FAILED`	Other API error — see `upstreamMessage`

Setup by client

Claude (web & desktop)

On Pro, Max, Team and Enterprise plans, MCP servers are added from the Claude UI:

Open Customize > Connectors > Add Connectors > Add custom connectors.

Paste the URL:

Code
 
https://stargate.prod.aws.waalaxy.com/api/mcp

Choose a name for the custom connector.
Click Connect and complete the magic-link sign-in in the browser window that opens.

The Waalaxy tools then appear in the connectors panel of every new conversation.

You can also find Waalaxy directly in the list of built-in connectors in Customize > Connectors, without entering any URL.

ChatGPT

Open Settings > Apps > Advanced Settings > Activate Developers Mode > Create app.

Paste the URL (no other field is required):

Code
 
https://stargate.prod.aws.waalaxy.com/api/mcp

Choose a name for the custom connector.
Complete the magic-link sign-in in the popup.

Connector availability depends on your ChatGPT plan.

You can also find Waalaxy directly in the list of built-in connectors in Settings → Connectors, without entering any URL.

Example prompts

Once the connector is added, try prompts like:

"List my Waalaxy prospect lists and tell me which one has the most prospects."
"Import this LinkedIn profile https://www.linkedin.com/in/john-doe into my 'CRM imports' list and enroll the prospect in the 'Q2 outbound' campaign."
"Add these five LinkedIn URLs to my 'Inbound demo requests' list. Don't create duplicates."

The assistant will call get-prospectlists (and get-campaigns when needed) before add-prospects-to-list-campaign, and ask you to confirm the chosen list and campaign before importing.

Limitations

OAuth only: the MCP server does not accept the REST API's bearer API keys. For headless automation that does not require a human in the loop, use the REST API instead.
Access tokens last 1 hour and are refreshed transparently;
Prospect imports follow the same quotas and de-duplication rules as the rest of the Waalaxy app.

Troubleshooting

Symptom	Try
Tools do not appear in the assistant.	Reload the client; verify the URL is exactly `https://stargate.prod.aws.waalaxy.com/api/mcp`.
The assistant says it cannot find your lists or campaigns.	Confirm you signed in with the email of your Waalaxy account; call the `integrations-test` tool to verify auth.
The OAuth window closes without completing.	Re-trigger the connection from the client; make sure pop-ups are not blocked and that you opened the magic-link on the same device.

Useful links

Support

For any technical or commercial questions:

Type	Contact
Technical Support	support@waalaxy.com
Marketing & Partnerships	mickael.prous@waalaxy.com

Last modified on June 8, 2026

Usage Guide

Getting Started

Connecting to Waalaxy MCP

Once connected, the assistant can, with your permission:

list your prospect lists and campaigns,
import LinkedIn prospects into a list and optionally enrol them in a campaign,

All actions run with your account's permissions. The assistant cannot see or do anything you couldn't do yourself in the app.

The MCP server is available on the Advanced and Business Waalaxy plans only. You can check or upgrade your plan from the billing page.

Server URL

The Waalaxy MCP server is a remote server reachable over HTTP:

Code
 
https://stargate.prod.aws.waalaxy.com/api/mcp

It uses the Streamable HTTP transport, the modern transport supported by all major MCP clients.

Authentication

Connections use user-based OAuth 2.1. Bearer API keys (the kind used by the REST API) are not supported by the MCP server.

The flow is:

The MCP client opens a Waalaxy sign-in page in your browser.
You sign in with a magic link sent to the email address of your Waalaxy account.
The client receives an OAuth access token (valid for 1 hour) and a refresh token, and uses them to call the server on your behalf.

You do not need to copy or paste any token yourself. The MCP client handles the OAuth handshake for you.

Use the same email as your Waalaxy account when the magic link page asks for it. If you sign in with a different email, the server will not be able to map the session to your prospects and campaigns.

Available tools

The server exposes four MCP tools:

Tool	What it does
`get-prospectlists`	Returns every prospect list owned by the user (`_id`, `name`, `totalProspects`, icon). Use first to pick a `prospectListId`.
`get-campaigns`	Returns the user's paused and running campaigns (`_id`, `name`).
`add-prospects-to-list-campaign`	Imports one or more LinkedIn prospects into a list and, optionally, a campaign.

`add-prospects-to-list-campaign` inputs

Field	Type	Required	Description
`prospects`	array	yes	Each entry has a LinkedIn profile `url` and an optional `customProfile` (firstName, lastName, email, company, …).
`prospectListId`	string	yes	Target list id, obtained from `get-prospectlists`.
`campaignId`	string	no	Campaign id from `get-campaigns`. Omit if the user does not want a campaign enrollment.
`canCreateDuplicates`	boolean	no	Allow importing a prospect already present in the list. Default: `false`.
`moveDuplicatesToOtherList`	boolean	no	Move existing duplicates into this list instead of skipping. Default: `false`.
`addExistingProspectInCampaign`	boolean	no	When `campaignId` is set, also enroll already-existing prospects in the campaign. Default: `false`.

Prospect imports made through MCP are imported with the mcp origin in the Waalaxy app.

Error responses (`add-prospects-to-list-campaign`)


Code
 
{
    "ok": false,
    "errorCode": "PLAN_UPGRADE_REQUIRED",
    "reason": "The Waalaxy account is authenticated but lacks the manage_api_keys permission…",
    "userMessage": "The prospect import did not run. Your Waalaxy subscription must be Advanced or Business…",
    "assistantGuidance": "Tell the user the import failed because of their Waalaxy plan…",
    "requiredPlans": ["ADVANCED", "BUSINESS"],
    "upgradePath": "/upgrade"
}

`errorCode`	Typical cause
`PLAN_UPGRADE_REQUIRED`	Account on Freemium/Pro or missing `manage_api_keys` after downgrade
`CRM_LIST_LIMIT_EXCEEDED`	Target list quota reached for the current plan
`PROSPECT_LIST_NOT_FOUND`	Invalid `prospectListId` — call `get-prospectlists` first
`NO_VALID_PROSPECTS`	LinkedIn URLs could not be parsed
`IMPORT_FAILED`	Other API error — see `upstreamMessage`

Setup by client

Claude (web & desktop)

On Pro, Max, Team and Enterprise plans, MCP servers are added from the Claude UI:

Open Customize > Connectors > Add Connectors > Add custom connectors.

Paste the URL:

Code
 
https://stargate.prod.aws.waalaxy.com/api/mcp

Choose a name for the custom connector.
Click Connect and complete the magic-link sign-in in the browser window that opens.

The Waalaxy tools then appear in the connectors panel of every new conversation.

You can also find Waalaxy directly in the list of built-in connectors in Customize > Connectors, without entering any URL.

ChatGPT

Open Settings > Apps > Advanced Settings > Activate Developers Mode > Create app.

Paste the URL (no other field is required):

Code
 
https://stargate.prod.aws.waalaxy.com/api/mcp

Choose a name for the custom connector.
Complete the magic-link sign-in in the popup.

Connector availability depends on your ChatGPT plan.

You can also find Waalaxy directly in the list of built-in connectors in Settings → Connectors, without entering any URL.

Example prompts

Once the connector is added, try prompts like:

"List my Waalaxy prospect lists and tell me which one has the most prospects."
"Import this LinkedIn profile https://www.linkedin.com/in/john-doe into my 'CRM imports' list and enroll the prospect in the 'Q2 outbound' campaign."
"Add these five LinkedIn URLs to my 'Inbound demo requests' list. Don't create duplicates."

The assistant will call get-prospectlists (and get-campaigns when needed) before add-prospects-to-list-campaign, and ask you to confirm the chosen list and campaign before importing.

Limitations

OAuth only: the MCP server does not accept the REST API's bearer API keys. For headless automation that does not require a human in the loop, use the REST API instead.
Access tokens last 1 hour and are refreshed transparently;
Prospect imports follow the same quotas and de-duplication rules as the rest of the Waalaxy app.

Troubleshooting

Symptom	Try
Tools do not appear in the assistant.	Reload the client; verify the URL is exactly `https://stargate.prod.aws.waalaxy.com/api/mcp`.
The assistant says it cannot find your lists or campaigns.	Confirm you signed in with the email of your Waalaxy account; call the `integrations-test` tool to verify auth.
The OAuth window closes without completing.	Re-trigger the connection from the client; make sure pop-ups are not blocked and that you opened the magic-link on the same device.

Useful links

Support

For any technical or commercial questions:

Type	Contact
Technical Support	support@waalaxy.com
Marketing & Partnerships	mickael.prous@waalaxy.com

Last modified on June 8, 2026

Usage Guide

Connecting to Waalaxy MCP

Server URL

Authentication

Available tools

add-prospects-to-list-campaign inputs

Error responses (add-prospects-to-list-campaign)

Setup by client

Claude (web & desktop)

ChatGPT

Example prompts

Limitations

Troubleshooting

Useful links

Support

Connecting to Waalaxy MCP

Server URL

Authentication

Available tools

add-prospects-to-list-campaign inputs

Error responses (add-prospects-to-list-campaign)

Setup by client

Claude (web & desktop)

ChatGPT

Example prompts

Limitations

Troubleshooting

Useful links

Support

`add-prospects-to-list-campaign` inputs

Error responses (`add-prospects-to-list-campaign`)

`add-prospects-to-list-campaign` inputs

Error responses (`add-prospects-to-list-campaign`)