For AI agents · MCP server & CLI

Let your AI agent run AI Ambassador

One scoped key and one npm package. Your agent sets up assistants, grounds them on your website, drafts broadcasts, answers guests and runs event check-in, with spending limits it cannot talk its way past.

QuickstartTool catalognpm
Claude Code
claude mcp add ai-ambassador \
  --env MSG2AI_AGENT_KEY=msgk_live_… \
  -- npx -y -p @msg2ai/ai-ambassador-toolkit ambassador-mcp
Tools
70
Tools
grouped by job
Surfaces
2
Surfaces
MCP · CLI
Packages
5
Packages
one build
Runtime deps
0
Runtime deps
Node 18+

How it works

The toolkit is a thin client. Your agent talks to it, it talks to the msg2ai agent gateway, and the gateway acts on your organization's assistants with exactly the scopes your key holds.

Your AI agent

Claude, Cursor, or any MCP client. A shell script or CI job works too.

The toolkit

ambassador-mcp for agents, ambassador for the command line. Same tools, same key.

msg2ai agent gateway

api.msg2ai.xyz/api/agent checks the key, its scopes and its daily budget on every call.

Your assistants

The same assistants your team manages in the dashboard, talking to guests on WhatsApp and SMS.

MCP server

ambassador-mcp

Register it once and your agent sees the AI Ambassador tools as native tools. It advertises only the tools your key may call, and a failed call comes back as a readable error instead of ending the conversation.

Command line

ambassador

Every tool is a subcommand with the same name. Pass fields as flags or one JSON object, get JSON back, and script it. Handy for onboarding a property, a nightly job, or checking what a key can do.

From key to first call in three steps

You need Node 18 or newer and an Admin of your organization in the msg2ai dashboard.

1

Mint an agent key

An organization Admin mints the key in the msg2ai dashboard and picks its scopes. It starts with msgk_live_ and is shown once, so store it in a secret manager.

2

Give it to the toolkit

One environment variable configures both the MCP server and the CLI.

Terminal
export MSG2AI_AGENT_KEY=msgk_live_…
# optional, this is the default:
export MSG2AI_BASE_URL=https://api.msg2ai.xyz
3

Make the first call

Ask the gateway what this key may do. No install needed; npx fetches the package.

Terminal
npx -y -p @msg2ai/ai-ambassador-toolkit ambassador tools

Connect the MCP server

Add it to your client's MCP configuration, or register it from the Claude Code command line.

MCP client configuration

For Claude Desktop, Cursor and other clients that read an mcpServers block.

JSON
{
  "mcpServers": {
    "ai-ambassador": {
      "command": "npx",
      "args": ["-p", "@msg2ai/ai-ambassador-toolkit", "ambassador-mcp"],
      "env": { "MSG2AI_AGENT_KEY": "msgk_live_…" }
    }
  }
}

Claude Code

One command. Swap in a vertical package to name the server after your business.

Terminal
claude mcp add ai-ambassador \
  --env MSG2AI_AGENT_KEY=msgk_live_… \
  -- npx -y -p @msg2ai/ai-ambassador-toolkit ambassador-mcp
Hotels
claude mcp add hotel-ambassador \
  --env MSG2AI_AGENT_KEY=msgk_live_… \
  -- npx -y -p @msg2ai/hotel-ambassador hotel-ambassador-mcp

Only the tools your key can use

At startup the server reads /capabilities and advertises nothing else. Listing tools that would fail with 403 only teaches a model to retry things it can never do.

Errors the model can act on

A failed call returns an isError result with the reason, not a protocol error, so the agent can adjust and the conversation carries on.

Use the CLI

Every tool is a subcommand. Fields go in as --flags or as one JSON object with --input, and results come back as JSON.

Basics
npm install -g @msg2ai/ai-ambassador-toolkit

ambassador tools             # what this key may call
ambassador list_assistants
ambassador get_assistant --serviceId svc_123
ambassador upload_knowledge --serviceId svc_123 --text "Checkout is 11am"
ambassador openapi > openapi.json   # no key needed
Events
npm install -g @msg2ai/event-ambassador

event-ambassador get_checkin_stats --serviceId svc_456
event-ambassador list_checkin_arrivals --serviceId svc_456
event-ambassador list_meeting_slots --serviceId svc_456
Hotels
npm install -g @msg2ai/hotel-ambassador

# Create a hotel concierge (no number is attached yet)
hotel-ambassador create_assistant --input '{
  "assistantName": "Harbor House Concierge",
  "assistantData": {
    "caseType": "CONCIERGE_ASSISTANT",
    "propertyType": "HOTEL"
  }
}'

# Ground it on one page of the hotel's site…
hotel-ambassador upload_knowledge_website \
  --serviceId svc_123 --url https://www.example-hotel.com/faq

# …or a bounded crawl (numbers go in --input)
hotel-ambassador upload_knowledge_website --input '{
  "serviceId": "svc_123", "url": "https://www.example-hotel.com",
  "mode": "crawl", "limit": 25, "maxDepth": 2
}'
  • Flags are strings. Put numbers, arrays and nested objects in --input, as in the crawl example.
  • Key and gateway per call. --key and --base-url override the environment variables.
  • Scriptable exit codes. 0 on success, 1 when the gateway refuses the call, 2 for a server or network error.
  • The contract is public. ambassador openapi prints the OpenAPI document for every tool, with no key required.

One build, named for your business

Every package below is the same toolkit at the same version. The tools and the key are identical; the vertical packages also give a new assistant the right defaults for your business.

AI Ambassador

@msg2ai/ai-ambassador-toolkit
$ ambassador$ ambassador-mcp

The base package. Works for every vertical.

Hotels

@msg2ai/hotel-ambassador
$ hotel-ambassador$ hotel-ambassador-mcp

Defaults: CONCIERGE_ASSISTANT / HOTEL

Vacation rentals

@msg2ai/vacation-rental-ambassador
$ vacation-rental-ambassador$ vacation-rental-ambassador-mcp

Defaults: CONCIERGE_ASSISTANT / VACATION_HOME

Events

@msg2ai/event-ambassador
$ event-ambassador$ event-ambassador-mcp

Defaults: MEETING_EVENT_ASSISTANT

Travel agencies

@msg2ai/trip-ambassador
$ trip-ambassador$ trip-ambassador-mcp

Defaults: CONCIERGE_ASSISTANT / TRAVEL_AGENCY

From version 0.1.2, a vertical package fills in assistantData.caseType (and propertyType where shown) when your agent creates an assistant without them. Anything the agent passes itself wins, so the explicit values in the examples work on every version.

What an agent can do with it

Real jobs, chained from the tools below. Each one lists the scopes it needs, so you can mint a key that does that job and nothing else.

Stand up a hotel concierge

Create the assistant, ground it on the hotel's own website, and save the welcome and check-out templates, ready for an operator to attach a number.

create_assistant → upload_knowledge_website → upload_knowledge → save_templates
assistants:writeknowledge:writetemplates:write

Run event day

Pull Humanitix registrations in, mint a check-in code for every attendee, then watch arrivals and meeting requests through the day.

create_event_registration_connection → generate_checkin_codes → get_checkin_stats → list_meetings
integrations:writecheckin:writecheckin:readmeetings:read

Triage the guest inbox

Scan open conversations, read the ones that need a person, and answer in the same thread, inside the key's daily budget.

list_conversations → get_conversation → reply_to_conversation
conversations:readconversations:write

Draft a campaign for review

Build an audience group from tagged contacts and draft the broadcast. Without broadcasts:send, a human presses send in the dashboard.

list_contacts → create_audience_group → add_audience_group_members → create_broadcast
audiences:readaudiences:writebroadcasts:write

70 tools, grouped by job

The MCP server exposes these names and the CLI uses them as subcommands. Each tool needs one scope, and your key only sees the tools its scopes allow.

Assistants

4 tools

List, read, create and rename assistants. A new assistant never gets a phone number automatically.

  • list_assistants
  • get_assistant
  • create_assistant
  • update_assistant
assistants:readassistants:write

Knowledge

3 tools

Ground an assistant with a text document, a single web page, or a bounded crawl of a site.

  • upload_knowledge
  • upload_knowledge_website
  • delete_knowledge
knowledge:write

Content templates

2 tools

Read and save an assistant's message templates in one write. Saving does not submit them for approval.

  • list_templates
  • save_templates
templates:readtemplates:write

Contacts, tags & audience groups

11 tools

Search and manage guests and attendees, tag them, and group them into audiences for broadcasts and reminders.

  • list_contacts
  • create_contact
  • update_contact
  • delete_contact
  • add_contact_tags
  • remove_contact_tag
  • list_audience_groups
  • create_audience_group
  • update_audience_group
  • add_audience_group_members
  • delete_audience_group
audiences:readaudiences:write

Contact consent

3 tools

Read and set a guest's consent flags: email, LinkedIn, WhatsApp, phone and meetings.

  • list_contact_preferences
  • get_contact_preferences
  • update_contact_preferences
audiences:readaudiences:write

Broadcasts

8 tools

Drafting and sending are separate tools behind separate scopes. A key can write drafts all day and never send one.

  • create_broadcast
  • update_broadcast
  • delete_broadcast
  • list_broadcasts
  • get_broadcast
  • send_broadcast
  • pause_broadcast
  • cancel_broadcast
broadcasts:writebroadcasts:send

Reminders

6 tools

Draft scheduled messages to an audience. An agent can edit, pause and delete them; a person turns them on in the dashboard.

  • list_reminders
  • get_reminder
  • create_reminder
  • update_reminder
  • disable_reminder
  • delete_reminder
reminders:readreminders:write

Guest conversations

3 tools

Triage the inbox and answer in an existing thread. The recipient always comes from the conversation.

  • list_conversations
  • get_conversation
  • reply_to_conversation
conversations:readconversations:write

Numbers

3 tools

See the numbers your organization already owns and move them between its assistants.

  • list_numbers
  • attach_number
  • detach_number
numbers:attach

Meetings

6 tools

Manage meeting requests between attendees and check which bookable slots are still open.

  • list_meetings
  • get_meeting
  • create_meeting
  • update_meeting
  • delete_meeting
  • list_meeting_slots
meetings:readmeetings:write

Event check-in

5 tools

Mint check-in codes, look up one attendee, and watch arrivals come in. There is no bulk export of codes.

  • generate_checkin_codes
  • regenerate_attendee_checkin_code
  • get_attendee_checkin
  • get_checkin_stats
  • list_checkin_arrivals
checkin:writecheckin:read

Event registration (Humanitix)

5 tools

Connect a Humanitix event to an assistant so its registrations are imported, and see why a sync failed.

  • list_event_registration_connections
  • create_event_registration_connection
  • update_event_registration_connection
  • delete_event_registration_connection
  • list_event_registration_sync_events
integrations:readintegrations:write

Surveys

9 tools

Author surveys and read what guests answered: aggregate results, masked individual responses and a CSV export. Changing a survey's status never messages anyone.

  • create_survey
  • update_survey
  • delete_survey
  • set_survey_status
  • list_surveys
  • get_survey_results
  • get_survey_statistics
  • list_survey_responses
  • export_survey_responses
surveys:writesurveys:readresults:readresults:export

Discovery & usage

2 tools

Ask what this key may do, and how many messages the organization has sent.

  • capabilities
  • get_usage
usage:read

One key, one organization

An agent key is a narrow credential for one job, not a login.

  • Minted by an Admin. Only an Admin of your organization can create a key, in the msg2ai dashboard.
  • Shown once. The msgk_live_ secret is displayed a single time and cannot be recovered. Lost it? Mint a new one.
  • Scopes fixed at mint. Each key carries the scopes chosen when it was created. Give a reporting agent read scopes only.
  • Stays in its tenant. A key acts as exactly one organization. It cannot reach another tenant and is not a platform credential.

Scope vocabulary

  • assistants:read / :writeRead or create and update assistants
  • knowledge:writeAdd and remove knowledge documents
  • templates:read / :writeRead or save content templates
  • audiences:read / :writeContacts, tags, audience groups, consent flags
  • broadcasts:writeDraft, edit and delete broadcasts — never send
  • broadcasts:sendSend, pause and cancel broadcasts (spends money)
  • reminders:read / :writeRead, draft and pause reminders — never turn one on
  • conversations:readRead guest conversations
  • conversations:writeReply in a conversation (spends money)
  • numbers:attachMove owned numbers between assistants
  • meetings:read / :writeMeeting requests and slots
  • checkin:read / :writeCheck-in stats, arrivals and codes
  • integrations:read / :writeHumanitix registration connections
  • surveys:read / :writeList surveys, or create, edit and schedule them
  • results:read / :exportSurvey results, masked responses and CSV
  • usage:readMessage counts for the organization

Safe to automate

An agent works fast and never gets tired, so the limits live in the gateway, not in the prompt. Here is what it will refuse.

Spend is checked before anything queues

send_broadcast and reply_to_conversation spend money. Recipients are counted and charged against the key's daily budget first; a send over the per-call ceiling or the daily budget is refused outright, never partly delivered.

Drafting and sending are separate

create_broadcast only ever makes a DRAFT. Sending needs broadcasts:send, a different scope, so you can hand an agent the pen without the button.

No phone number by accident

Creating an assistant does not attach a number. The number pool is operator-owned; until a number is attached, template submission refuses with AGENT_NUMBER_REQUIRED.

Refused, not silently dropped

Instructions, guardrails, privacy settings, provider credentials and billing flags are rejected with an explanation. Your agent learns why instead of thinking it worked.

Guest data stays masked

Phone numbers are masked in list results. Contact emails, notes and enrichment are never returned, and conversation lists carry no message text.

Only the tools a key can use

The MCP server reads /capabilities at startup and advertises only the tools the key may call, so a model is never shown a tool that would fail with 403.

Failures the model can read

A tool failure comes back as an isError result, not a protocol error. The model sees the reason and adapts; the conversation keeps going.

A person arms reminders

Reminders are sent later by the scheduler, not by the key, so they are never left to an agent: create_reminder always makes a DRAFT, and only a person can turn one on in the dashboard.

Also on WhatsApp Campaigns & Surveys?

Surveys for your AI Ambassador assistants are covered above. If you build WhatsApp campaign templates or run surveys in WhatsApp Campaigns & Surveys, it has its own agent toolkit: @wa-campaigns/agent-toolkit (wa and wa-mcp), with its own tools and its own keys.

WhatsApp Surveys for agentsWhatsApp Campaigns for agentsWhatsApp Campaigns API docs

Frequently Asked Questions

About the AI Ambassador MCP server and CLI

It is a Model Context Protocol server, ambassador-mcp, that lets an AI agent manage your AI Ambassador assistants: knowledge, templates, contacts, broadcasts, reminders, surveys, conversations, meetings and event check-in. It ships in the npm package @msg2ai/ai-ambassador-toolkit alongside the ambassador command-line tool.

Building an agent for your property or event?

Tell us what you want it to do. We'll help you set up the assistant, attach a number and pick the scopes for its key.

View on npm

Looking for the guest experience instead? See AI Ambassador for hotels, vacation rentals and events.