Docs · MCP

Connect your AI assistant

Let Claude, ChatGPT, Cursor, VS Code or your own agent run your AI Employee workspace: build voice and phone agents, buy numbers, queue outbound calls, create widgets, generate media, post to social and more.

Your server address

Every app uses the same address. It speaks MCP over Streamable HTTP.

https://home.aiemployee.com/api/mcp

There are two ways to connect:

  • Sign in (recommended): the app opens an AI Employee sign-in window and connects to the workspace you have selected in the dashboard. Nothing to copy or store.
  • API key: for apps that can't sign in, scripts and servers. You choose exactly what the key may do.

Signing in or creating a key needs an owner or admin role on the workspace. Every action still follows that person's current role and any limits your agency set.

Option 1 — Sign in

  1. Sign in at home.aiemployee.com and switch to the workspace you want the app to use.
  2. Add the server address in your app (steps for each app are below) with no key or header.
  3. When the app asks, sign in and approve access.
  4. Ask the assistant to "call whoami". It answers with your workspace and role.

To connect a different workspace, disconnect the app (see Manage access), switch workspaces in the dashboard, and connect again.

Option 2 — API key

  1. In the dashboard, open Task Engine → Settings → API keys.
  2. Name the key, pick the Employee, and either click Full MCP access or tick only the scopes you want (see what each scope allows). Buying or releasing phone numbers needs numbers:purchase.
  3. Copy the key (it starts with cw_live_sk_). It is shown only once.
  4. Send it on every request as Authorization: Bearer cw_live_sk_….

Treat the key like a password: keep it in a secret store, never in shared files or chat.

Set up your app

Claude (claude.ai and Claude Desktop)

  1. Open Settings → Connectors → Add custom connector.
  2. Name it AI Employee, paste https://home.aiemployee.com/api/mcp, and add it.
  3. Click Connect and sign in. Turn the connector on in a chat from the tools menu.

Custom connectors need a Claude plan that supports them.

Claude Code

Sign in:

claude mcp add --transport http ai-employee https://home.aiemployee.com/api/mcp
# then, inside Claude Code:
/mcp   # choose ai-employee → Authenticate

Or with an API key:

claude mcp add --transport http ai-employee https://home.aiemployee.com/api/mcp \
  --header "Authorization: Bearer $AI_EMPLOYEE_API_KEY"

ChatGPT

  1. Open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
  2. Back in Apps & Connectors, choose Create, paste https://home.aiemployee.com/api/mcp, and pick OAuth as the authentication.
  3. Sign in when prompted, then enable the connector in a chat.

Availability of custom connectors depends on your ChatGPT plan.

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Without headers, Cursor offers to sign in.

{
  "mcpServers": {
    "ai-employee": {
      "url": "https://home.aiemployee.com/api/mcp",
      "headers": { "Authorization": "Bearer cw_live_sk_…" }
    }
  }
}

VS Code (GitHub Copilot agent mode)

Add to .vscode/mcp.json. Leave out headers to sign in instead; the prompt input keeps the key out of the file.

{
  "inputs": [
    { "type": "promptString", "id": "ai-employee-key", "description": "AI Employee API key", "password": true }
  ],
  "servers": {
    "ai-employee": {
      "type": "http",
      "url": "https://home.aiemployee.com/api/mcp",
      "headers": { "Authorization": "Bearer ${input:ai-employee-key}" }
    }
  }
}

Apps that only run local (stdio) servers

Bridge them with the open-source mcp-remote package:

{
  "mcpServers": {
    "ai-employee": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://home.aiemployee.com/api/mcp",
               "--header", "Authorization: Bearer ${AI_EMPLOYEE_API_KEY}"],
      "env": { "AI_EMPLOYEE_API_KEY": "cw_live_sk_…" }
    }
  }
}

Your own agent or code

Use any MCP client library (for example the official TypeScript or Python SDK) with a Streamable HTTP transport and the Bearer header. Plain HTTP works too:

curl https://home.aiemployee.com/api/mcp \
  -H "Authorization: Bearer $AI_EMPLOYEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"whoami","arguments":{}}}'

What your assistant can do

The assistant only sees the tools its key allows. Signed-in apps get every scope, still limited by your role.

AreaScopesTools
Workspaceany keywhoami
AI Employee tasksthreads:*, messages:*, runs:*ask_coworker, create_thread, send_message, get_run, get_run_result, wait_for_run, list_threads, list_runs
Voice agentsagents:read / agents:writelist_agents, get_agent, create_agent, update_agent, delete_agent
Website widgetswidgets:read / widgets:writelist_widgets, get_widget (includes embed code), create_widget, update_widget, delete_widget
Phone agents & callstelephony:read / telephony:writelist_phone_agents, get_phone_agent, create_phone_agent, update_phone_agent, delete_phone_agent, list_phone_numbers, search_available_numbers, assign_phone_number, unassign_phone_number, list_calls, get_call, get_call_stats, get_calling_balance
Outbound callingtelephony:read / telephony:writeadd_call_leads, schedule_call, list_call_leads, get_call_lead_stats, retry_call_lead, cancel_call_lead, list_do_not_call, add_do_not_call, remove_do_not_call
Buying numbersnumbers:purchasepurchase_phone_number, release_phone_number
Content Studiocontent:read / content:writelist_media_models, list_media_assets, get_media_asset, generate_media, get_media_job, compose_video_plan, get_media_plan
Social postssocial:read / social:writelist_social_accounts, list_social_posts, create_social_post, cancel_social_post
Schedulesschedules:read / schedules:writelist_schedules, create_schedule, set_schedule_state
Knowledge, conversations, leadsknowledge:read, conversations:read, leads:readlist_knowledge_bases, list_conversations, get_conversation, list_leads

Account connections (social accounts, your own calling-provider account, widget logos) are still set up in the dashboard.

Spending money, calling people, publishing

  • Buying a number charges its monthly price (shown in search results) now and every month. Media generation holds credits up front and charges only on success.
  • Outbound calls need your confirmation that the contacts agreed to automated calls. Every call is still checked at dial time against your Do Not Call list, the contact's local quiet hours, and your calling balance.
  • Social posts publish publicly unless created as a draft.
  • Deleting an agent or releasing a number requires repeating its exact name or number. A released number cannot be recovered.

Well-behaved assistants confirm these with you first; you can also give them a read-only key.

Manage access

  • Signed-in apps: Task Engine → Settings → API keys → Signed-in MCP apps. Disconnect stops the app on its next request; Reconnect restores it.
  • API keys: revoke a key on the same page. Revoking takes effect immediately.
  • If a team member's role changes, their keys and connected apps change with it.

Troubleshooting

  • 401 / "Invalid API key": the key was mistyped, revoked or expired, or the sign-in was disconnected. Create a new key or reconnect.
  • A tool is missing: the key lacks that scope. Create a key with the scope, or use Full MCP access.
  • "forbidden": your role (or your agency's limits) doesn't allow that action in this workspace.
  • You signed in but the app still can't connect: make sure you are an owner or admin of the selected workspace, and open AI Employee in the dashboard once so the workspace has an Employee. Then connect again.
  • Sign-in isn't offered on an agency's own domain: sign-in works at home.aiemployee.com; on agency domains use an API key.
  • "rate_limited": slow down; spend tools are limited per key to protect your balance.

Still stuck? Contact us.

Connect your AI assistant (MCP) | AI Employee | AI Employee