Automate customer onboarding with the MCP API

Who this is for

This playbook is for agencies that:

Onboard multiple customers per week and want to eliminate manual setup
Use a CRM (GoHighLevel, HubSpot, or custom) to manage their sales pipeline
Want to trigger customer provisioning automatically when a deal closes

Business goal

Manual onboarding is slow and error-prone. Every time a new client signs, someone has to:

Create the customer in the Partner Portal
Enable portal access
Map agents to the customer
Add credits

This playbook automates steps 1–3 using the MCP API, so your team only handles what requires human judgment.

What you’ll build

An integration that:

Creates a Knotie customer when a deal closes in your CRM
Enables portal access and sends invite credentials automatically
Maps your default voice agent to the new customer

Prerequisites

A Partner API key (created in Settings > Partner API Keys → Platform API tab)
At least one imported voice agent (Retell or VAPI)
A CRM or automation tool that can send HTTP requests (GHL workflows, Zapier, Make, n8n, or custom code)

Step 1 — Generate your Partner API key

Partner Portal → Settings → Partner API Keys → Platform API tab
Click Create API Key
Configure the key (see options below)
Copy the key (starts with pkt_) and store it in your automation tool’s secrets

Knotie AI Pro Partner Portal dashboard — showing where to find Settings → API Keys

Important: The key is shown only once in a reveal modal. Copy it immediately.

Knotie AI Pro Partner Portal — Customers list (where you can view onboarded customers)

Key configuration options

The Platform API key creation modal exposes:

Name (required)
Description
MCP Gateway — Enable MCP for AI-agent calls (checked by default)
Full Access — full-scoped permission (checked by default)
Expires At — optional expiration date
Rate Limit — requests per minute
Daily Limit — maximum daily requests
Monthly Limit — maximum monthly requests
Allowed IPs — restrict to specific server IPs (one per line)

Live field labels can change without notice — the list above is the verified set. The MCP-related fields (MCP Gateway, Full Access) gate the tool scopes the key can call.

After creation, a one-time modal displays:

Raw API key (pkt_...)
Ready-to-copy Authorization: Bearer pkt_... header
Ready-to-paste curl example
Endpoint info: /api/partner-mcp (AI agents) and /api/partner-rest/* (REST)
Legacy Basic-auth header (marked deprecated)

All API requests use the Authorization: Bearer pkt_... header. See the Authentication guide for details.

Security best practices

The page includes an expandable Security Best Practices section with guidance on:

Storing API keys in environment variables
Rotating keys periodically and revoking unused ones
Using IP restrictions for trusted servers
Monitoring usage for suspicious activity

Key management table

The Platform API tab shows a table of all keys with columns:

Name, Prefix, Status
Created, Last Used
Usage (Total / Today / Month)
MCP Scopes
Actions: Renew (rotate), Revoke

Note: The Partner API Keys page has 4 tabs: AI Gateway Beta, Platform API, MCP Tokens, and n8n Tokens. Make sure you are on the Platform API tab for partner automation keys (pkt_ prefix). AI Gateway keys (sk- prefix, for LLM usage) are on the separate AI Gateway Beta tab.

Use only pkt_ keys from the Platform API tab for the partner automation flow described in this doc. The MCP Tokens tab mints mt_ tokens that are tool-scoped and MCP-gateway-only — they will NOT work against /api/v1/mcp/customers/onboard or the agent map endpoints. The n8n Tokens tab is for n8n workflow integration; the AI Gateway Beta tab is for LLM-billing keys (sk- prefix), not partner automation.

Step 2 — Create the customer via API

When your CRM trigger fires (deal closed, form submitted, etc.), send:

curl -X POST "https://YOUR_BASE_URL/api/v1/mcp/customers/onboard" \
  -H "Authorization: Bearer pkt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "basic": {
      "email": "newclient@example.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "businessPhone": "+15551234567"
    },
    "business": {
      "companyName": "Client Corp"
    },
    "isQuickOnboarding": true,
    "allowPortalAccess": true
  }'

Key fields:

Field	Why it matters
`basic.email`	Must be unique — this becomes the portal login
`allowPortalAccess`	Set to `true` to auto-send the portal invite email
`isQuickOnboarding`	Skips extended intake questions

The response includes the customer id — save this for the next steps.

Step 3 — Map a voice agent to the customer

Once the customer exists, assign your default agent:

curl -X POST "https://YOUR_BASE_URL/api/v1/mcp/retell-agents/AGENT_ID/map-customer" \
  -H "Authorization: Bearer pkt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "CUSTOMER_ID_FROM_STEP_2",
    "profitMultiplier": 1.5
  }'

Replace AGENT_ID with your Retell agent ID. For VAPI agents, use /api/v1/mcp/vapi-agents/AGENT_ID/map-customer instead. The profitMultiplier controls how call costs are billed to this customer. A value of 1.5 means you charge 1.5x the base cost.

Step 4 — (Optional) Add team members

If the client needs additional portal users:

curl -X POST "https://YOUR_BASE_URL/api/v1/mcp/customers/CUSTOMER_ID/team-members" \
  -H "Authorization: Bearer pkt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "team@clientcorp.com",
    "name": "John Smith",
    "role": "member"
  }'

Team member count is limited by the customer’s maxTeamMembers setting.

Example: GoHighLevel workflow

Here’s how to wire this up in a GHL workflow:

Trigger: Pipeline stage changed → “Closed Won”
Action 1: Webhook → POST /api/v1/mcp/customers/onboard (with contact fields mapped)
Action 2: Webhook → POST /api/v1/mcp/retell-agents/{agentId}/map-customer (using the customer ID from Action 1)

Tip: Use GHL’s custom values to store your Partner API key and agent ID so they’re easy to update across workflows.

Example: n8n workflow

Trigger: Webhook (from your CRM) or schedule-based poll
HTTP Request node: POST to /api/v1/mcp/customers/onboard
HTTP Request node: POST to agent map endpoint with the returned customer ID

Verification checklist

After your first automated onboarding, confirm:

Customer appears in Partner Portal → Customers
Customer received the portal invite email
Agent mapping shows correctly in the customer’s detail view
Customer can log into their portal

Troubleshooting

Symptom	Likely cause
`400` — email already exists	Customer was previously onboarded with this email
`401` — unauthorized	API key is missing or invalid
`404` — agent not found	Agent ID doesn’t match an imported agent in your account
No invite email received	`allowPortalAccess` was `false` or omitted
Agent mapping fails	Customer ID from the onboard response wasn’t passed correctly
Can’t find “Create API Key”	Make sure you’re on the Platform API tab, not AI Gateway Beta or MCP Tokens

Next steps

Set up outbound calling for your newly onboarded customers
Configure credit management to control usage limits
Explore the full MCP API reference for additional automation options

​Who this is for

​Business goal

​What you’ll build

​Prerequisites

​Step 1 — Generate your Partner API key

​Key configuration options

​What the reveal modal shows

​Security best practices

​Key management table

​Step 2 — Create the customer via API

​Step 3 — Map a voice agent to the customer

​Step 4 — (Optional) Add team members

​Example: GoHighLevel workflow

​Example: n8n workflow

​Verification checklist

​Troubleshooting

​Next steps

Who this is for

Business goal

What you’ll build

Prerequisites

Step 1 — Generate your Partner API key

Key configuration options

What the reveal modal shows

Security best practices

Key management table

Step 2 — Create the customer via API

Step 3 — Map a voice agent to the customer

Step 4 — (Optional) Add team members

Example: GoHighLevel workflow

Example: n8n workflow

Verification checklist

Troubleshooting

Next steps