Upfirst

Connecting

There is nothing to install. Point your client at https://mcp.upfirst.ai and it will walk you through signing in to Upfirst the first time it connects. Authorization is a standard OAuth 2.1 sign-in, so there are no API keys to copy or store.

The server runs over streamable HTTP and gives your assistant 21 tools, which can both read your account and change it. Pick your client below.

Upfirst connects to the Claude desktop app and to claude.ai as a custom connector. Paste the prompt below into Claude and it will walk you through the setup one step at a time.

Help me connect Upfirst to Claude as a custom connector, so I
can review my calls and manage my AI receptionist from this chat.
Walk me through the exact clicks, one step at a time, and wait for
me at each one.

Open claude.ai/customize/connectors, click + Add custom connector,
and paste in these values:

  Name:                   Upfirst
  Remote MCP server URL:  https://mcp.upfirst.ai
  Advanced settings:      leave Client ID and Client Secret empty

Then click Add, click Connect, sign in to Upfirst, and approve
access.

If what I see doesn't match what you described, troubleshoot it
with me. Once it works, run get_account_overview and tell me what
you can see, then suggest three useful things I could ask you
about my calls.

Prefer to click through it yourself

1. Open Customize, then Connectors.
2. Click +, then Add custom connector.
3. Name it Upfirst and paste the URL below as the remote MCP server URL.
4. Click Add, then Connect, sign in to Upfirst, and approve access.

https://mcp.upfirst.ai

Leave the advanced Client ID and Client Secret fields empty. On Team and Enterprise plans an owner adds the connector once under Organization settings, and everyone else clicks Connect.

However you connect, the first call opens Upfirst's sign-in page. You approve access once, and the connection stays bound to your organization from then on.

Conventions

A few rules hold across every tool. Each one carries a tag for what it does to your data:

• Read Fetches data; never changes anything.
• Write Creates or updates a record.
• Delete Permanently removes a record. There is no undo.

Ids come from list tools

Agent ids come from list_agents, skill ids from list_agent_skills, knowledge ids from get_agent_knowledge, custom action ids from list_custom_actions, and call ids from list_calls. Ids are digit strings. Skill tools take the id as skillId; knowledge and custom action tools take it as id. Update and delete tools need only that id. They do not take an agentId.

Records are linked to agents

Every skill, knowledge entry, and custom action is linked to one or more agents. Create tools take agentIds, a list with at least one agent id. Set autoLinkNewAgents to true to also give the record to every agent you create later. In that case, agentIds must list every current agent. Update tools change the links only when you send both agentIds and autoLinkNewAgents. Leave both out to keep the links as they are. Editing or deleting a record changes it for every agent it is linked to.

Paging

get_agent_knowledge, list_calls, and get_call_transcript take offset and limit and return a totalCount, so the page is always drawn from the same filtered set. The other list tools return everything in one response.

Timezones

Bare dates (YYYY-MM-DD) are read in the business's timezone. Weekly schedules are read in each agent's own timezone, so one entry linked to agents in two timezones follows local hours for each. Pass a full ISO 8601 datetime when you need an exact instant.

Deletes are permanent

There is no restore over this connection. A deleted skill, knowledge entry, or custom action is gone from every agent it was linked to, and those agents stop using it within minutes.

Some settings are dashboard-only

Voice, timezone, and language; scheduling skills; the OAuth connections a custom action authenticates through; deleting a transfer skill; and importing website knowledge are managed in the Upfirst dashboard, not over MCP. Tools say so where it applies.

Example prompts

The Upfirst MCP server works from any compatible AI client. To get started, copy one of these prompts into your client and adapt it to your business.

Find gaps in your receptionist's knowledge

Use case

Use this workflow to review the past week of calls and find where the receptionist's knowledge fell short, so you know what to add to its training.

Example prompt

You are helping find gaps in an Upfirst receptionist's knowledge.

Review the calls from the last seven days, then read the receptionist's current knowledge. Look for questions callers asked that it could not answer well, information it was missing, and the same topic coming up more than once.

For each gap, point to the calls that show it and suggest a specific knowledge entry that would fill it, written the way the receptionist should answer. Group related gaps together and rank them by how often they came up.

Do not change anything. Present the gaps and the suggested entries for review.

Receptionist: [Name, or leave blank for all]

Set up your receptionist from a description

Use case

Use this workflow to describe how you want your receptionist to handle calls and let your assistant build the setup: the greeting, knowledge, transfer rules, schedules, and texting skills.

Example prompt

You are helping configure an Upfirst AI receptionist from a plain description of how it should handle calls.

Turn the description into a complete setup: a greeting and goodbye, the knowledge it needs to answer common questions, transfer rules for calls that should reach a person, schedules for information or transfers that only apply during certain hours, and any texting skills the description calls for.

Ask about anything important the description leaves unclear, such as hours, who calls should reach, or how to handle common requests, instead of guessing.

Show the full proposed setup for review before creating anything, then apply it once it's approved.

How the receptionist should handle calls: [Describe your business, your hours, what callers usually need, and who calls should reach]

Fix a call that didn't go well

Use case

Use this workflow to point out a call that didn't go the way you wanted, say what you'd have preferred, and have your assistant adjust the receptionist's knowledge so similar calls go better.

Example prompt

You are helping improve an Upfirst receptionist based on a call that didn't go well.

Read the call I point to, including its transcript, and compare what the receptionist did with what I wanted to happen. Work out what led to the outcome: whether something in its knowledge was missing, unclear, or contradicted by another entry.

Suggest the specific changes that would make a call like this go better next time, written as the exact knowledge to add or edit, and explain why each one helps.

Show the changes for review before applying them, then make the approved edits.

Call: [ID or a short description of the call]
What I wanted to happen instead: [Describe the outcome you were hoping for]

01

Account & agents

Orient yourself, then read or update an individual AI receptionist.

Start here. A compact snapshot of the whole account: the business name, every receptionist with its timezone, greeting, phone numbers, skills and knowledge, and the number of calls handled in the last 30 days.

No parameters.

Returns Business name · agents (id, name, timezone, greeting, phone numbers, skill & knowledge names) · calls in the last 30 days (settled calls only; test and archived calls are not counted).

List the organization's AI agents. Use a returned id with the agent-scoped tools below.

No parameters.

Returns agents, each with id and name.

Read one agent's full conversational settings and attached phone numbers.

Parameter	Type	Description
agentId	string req	Numeric agent id from list_agents.

Returns greeting & goodbye messages, voice tone, speech rate, hold music, timezone, spam & toll-free blocking, and attached phone numbers.

Change an agent's conversational settings. Partial update: send only what changes; at least one settable field is required.

Parameter	Type	Description
agentId	string req	Agent to update.
greetingMessage	string opt	Opening message.
goodbyeMessage	string opt	Closing message.
voiceTone	enum opt	friendly · professional
speechRate	number opt	0.7 · 0.85 · 1 · 1.1 · 1.2
holdMusic	enum opt	ringTone · gentleGuitar · marimba · softKeys
isSpamCallsBlocked	boolean opt	Block suspected spam calls.
isTollFreeCallsBlocked	boolean opt	Block toll-free calls.

Voice, timezone, and language are managed on the dashboard and can't be changed here. The blocking flags apply to this agent; the dashboard sets them for all agents at once.

Returns the updated agent, in the same shape as get_agent_by_id.

02

Skills

A skill is an action a receptionist can take on a call: texting the caller, texting a scheduling link, transferring the call, booking an appointment, or calling an external API. Each kind has its own tools, so the fields you pass are always the ones that kind uses. Scheduling skills are read-only here and managed on the dashboard. A webhook skill's settings live on the custom action it is linked to; read and edit them with the Custom actions tools below.

List the skills configured for an agent, including inactive ones by default.

Parameter	Type	Description
agentId	string req	Agent whose skills to list.
llmTool	enum opt	Only skills of this kind: sendSms · sendScheduleSms · transferCall · scheduleSlot · customWebhook.
includeInactive	boolean opt	Include switched-off skills. Default true.

Returns skills: id, name, slug, kind, active flag, stored config, optional weekly schedule. A customWebhook row has an empty config and a webhook block with the linked action's url, HTTP method, and timing; read its full configuration with list_custom_actions.

A schedule is honored on calls for transfer skills only. Other kinds store one but ignore it.

Add a texting skill: an SMS the receptionist can send to a caller during a call. sendSms texts the message as written. sendScheduleSms texts it together with the organization's scheduling link.

Parameter	Type	Description
agentIds	string[] req	Agents that get the skill, at least one. Ids from list_agents.
autoLinkNewAgents	boolean opt	Also give the skill to every agent created later. When true, agentIds must list every current agent. Default false.
llmTool	enum req	sendSms · sendScheduleSms
name	string req	Short label, shown on the dashboard.
message	string req	The SMS text the agent sends, up to 306 characters.
instruction	string req	When the agent should send it during a call.
isActive	boolean opt	On from the start. Default true.

The message passes a content filter that rejects promotional or otherwise restricted wording.

Returns the new skill's id and the fields you sent (llmTool, name, message, instruction, isActive). Read the stored skill with list_agent_skills.

Change a texting skill. Partial update: only the fields you send change. Send at least one settable field or a new set of agents.

Parameter	Type	Description
skillId	string req	Skill id from list_agent_skills.
llmTool	enum opt	Switch between sendSms and sendScheduleSms.
name	string opt	New label.
message	string opt	New SMS text, up to 306 characters.
instruction	string opt	New guidance on when to send it.
isActive	boolean opt	Switch the skill on or off.
agentIds	string[] opt	New set of agents that get the skill. Send it together with autoLinkNewAgents, or leave both out to keep the current links.
autoLinkNewAgents	boolean opt	Also give the skill to every agent created later. When true, agentIds must list every current agent.

Returns the fields the update wrote.

Permanently delete a texting skill from every agent it is linked to. Those agents stop sending that message.

Parameter	Type	Description
skillId	string req	Skill id to delete.

There is no way to restore a deleted skill. Getting it back means creating it again from scratch.

Returns { id, note }, where note confirms the delete in plain language.

Add a transfer skill: the rule that hands a live call to a person. condition tells the agent when to transfer, preTransferMessage is what it says to the caller first, and destinations are the numbers it dials in order.

Parameter	Type	Description
agentIds	string[] req	Agents that get the skill, at least one. Ids from list_agents.
autoLinkNewAgents	boolean opt	Also give the skill to every agent created later. When true, agentIds must list every current agent. Default false.
name	string req	Short label, shown on the dashboard.
condition	string req	When to transfer, in plain language.
preTransferMessage	string req	What the agent says before transferring.
destinations	array req	One or more targets, tried in order, each { phoneNumber, label, phoneExtension }. phoneNumber is required and must be E.164 (e.g. +12025550123).
ringTimeoutSeconds	number opt	Ring time per destination, 5–60.
noAnswerAction	enum opt	endCall · returnToAgent
transferMethod	enum opt	cold hands the caller over directly · warm briefs the destination first.
transferCallerId	enum opt	Number the destination sees: upfirstNumber · callerNumber.
recordingMode	enum opt	agentOnly stops recording at the transfer · fullCall keeps recording after it.
isActive	boolean opt	On from the start. Default true.
schedule	object opt	Weekly hours the skill is offered, in the agent's timezone. Omit for always available. See Schedules.

Every destination must be in the same country as one of the Upfirst numbers of the linked agents. When omitted, the skill uses the dashboard's defaults at call time: a 30 second ring, end the call on no answer, cold transfer, the Upfirst number as caller id, and recording stops at the transfer.

Returns the new skill's id and the fields you sent. Read the stored skill with list_agent_skills.

Change a transfer skill. Partial update: only the fields you send change. Send at least one settable field or a new set of agents.

Parameter	Type	Description
skillId	string req	Skill id from list_agent_skills.
destinations	array opt	Replaces the whole list. Send every number you want to keep.
schedule	object opt	Replaces the stored hours. null clears the schedule, making the skill available around the clock.
Other create fields	opt	name, condition, preTransferMessage, ringTimeoutSeconds, noAnswerAction, transferMethod, transferCallerId, recordingMode, isActive. Same values as create.
agentIds	string[] opt	New set of agents that get the skill. Send it together with autoLinkNewAgents, or leave both out to keep the current links.
autoLinkNewAgents	boolean opt	Also give the skill to every agent created later. When true, agentIds must list every current agent.

Every destination must be in the same country as one of the Upfirst numbers of the linked agents.

A skill's kind is fixed at creation. Passing the id of a scheduling or webhook skill reads as not found.

Returns the fields the update wrote.

There is no tool for this. Transfer skills are deleted on the Upfirst dashboard. Over MCP you can switch one off instead: set isActive: false with update_transfer_call_skill, and the agent stops offering the transfer while the skill stays configured.

03

Knowledge

A receptionist's knowledge is what it answers callers from. In the Upfirst dashboard these entries live under Training. Each one is text you write, or content imported from a website. An entry can be linked to several agents, and editing or deleting it changes what every linked agent answers. Writes retrain the receptionist automatically within minutes.

Read an agent's knowledge base. Every entry is returned whole with its full content, never a preview.

Parameter	Type	Description
agentId	string req	Agent whose knowledge to read.
id	string opt	Return just this one entry.
offset	number opt	Entries to skip. Default 0.
limit	number opt	Max entries, 1–100. Default 25.

Returns entries: id, name, type (text/website), active flag, full content, source url, and weekly schedule, plus totalCount.

Add a text entry to the training of one or more receptionists. The new entry goes to the top of each linked agent's list.

Parameter	Type	Description
agentIds	string[] req	Agents that get the entry, at least one. Ids from list_agents.
autoLinkNewAgents	boolean opt	Also give the entry to every agent created later. When true, agentIds must list every current agent. Default false.
name	string req	Display name of the entry.
content	string req	Plain text, up to 250,000 characters.
isActive	boolean opt	Active from the start. Default true.
schedule	object opt	Restrict the entry to business hours. Omit for always-active. See Schedules.

Returns the new entry's id, name, isActive, schedule (null when always active), and contentLength in characters. Read the full entry with get_agent_knowledge.

Change an entry's name, active flag, content, schedule, or which agents see it. Partial update: send at least one settable field or a new set of agents.

Parameter	Type	Description
id	string req	Entry id from get_agent_knowledge.
name, isActive	opt	New name / active flag.
content	string opt	New text, replacing the stored content entirely. Up to 250,000 characters.
schedule	object opt	New schedule. null clears it, making the entry always available; omit to keep the stored one.
agentIds	string[] opt	New set of agents that get the entry. Send it together with autoLinkNewAgents, or leave both out to keep the current links.
autoLinkNewAgents	boolean opt	Also give the entry to every agent created later. When true, agentIds must list every current agent.

Content is replaced, never appended. Read the entry with get_agent_knowledge first and send back the full text you want it to have, including whatever you are keeping. The edit changes what every agent linked to the entry says.

Returns the fields the update wrote. New content comes back as contentLength, not as the full text.

Permanently delete a knowledge entry.

Parameter	Type	Description
id	string req	Entry id to delete.

There is no way to restore a deleted entry. Deleting it removes it from every agent it is linked to.

Returns { id, note }, where note confirms the delete in plain language.

A schedule restricts a knowledge entry (or transfer skill) to business hours, honored in the agent's business timezone. It's a per-weekday object. Every schedule you send must include all seven days; a day the entry should not apply on is enabled: false with an empty workingPeriods. Times are 24-hour HH:MM in the agent's timezone.

A scheduled entry is only in the receptionist's knowledge during its windows. Outside them, it's as if the entry doesn't exist, so the receptionist never answers from it at the wrong time.

That makes schedules a dependable way to handle time-specific facts. To make open and closed hours foolproof, add one entry restricted to your open hours that reads "We are currently open," and a second restricted to your closed hours that reads "We are currently closed." Only one is ever active, so the receptionist can't mix them up.

{
  "days": {
    "monday":    { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "tuesday":   { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "wednesday": { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "thursday":  { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "friday":    { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "saturday":  { "enabled": false, "workingPeriods": [] },
    "sunday":    { "enabled": false, "workingPeriods": [] }
  }
}

04

Custom actions

A custom action is a call the receptionist makes to an external HTTP API. timing decides when it runs: before fires ahead of the conversation and may only use system variables; during is offered to the agent on the call, which decides from the description whether to call it; after fires once the call has ended, either every time or when a plain-language condition holds.

Variables are interpolated into the url, query params, headers, and body as {{name}}. An action is linked to one or more agents, and editing or deleting it changes what every linked agent does. In list_agent_skills, a customWebhook skill is the agent-side view of a custom action. The OAuth connections an action can authenticate through are set up on the Upfirst dashboard.

Every custom action an agent can use, each with its whole configuration. Read this before rewriting an action, so nothing is overwritten unseen.

Parameter	Type	Description
agentId	string req	Agent whose actions to list. Every action linked to this agent is included.
id	string opt	Return just this one action.

Returns customActions, each with id, agentIds (every agent the action is linked to), autoLinkNewAgents, name, description, timing, HTTP method, url, auth type and OAuth connection id, fallback message, timeout, active flag, variables, query params, headers, allowed output fields, sample values, body template, and the after-timing condition.

A header whose name looks like a credential (token, key, secret, authorization) comes back as [redacted]; the real value is never read out. Deleted actions are omitted.

Add a custom action and link it to one or more agents.

Parameter	Type	Description
agentIds	string[] req	Agents that get the action, at least one. Ids from list_agents.
autoLinkNewAgents	boolean opt	Also give the action to every agent created later. When true, agentIds must list every current agent. Default false.
name	string req	Short label, shown on the dashboard.
description	string req	What the action does, in plain language. before and during timing put it in front of the agent, which decides from this text whether to call the API. after timing ignores it.
timing	enum req	before · during · after
httpMethod	enum req	GET · POST · PUT · PATCH · DELETE
url	string req	Endpoint the request goes to. May contain {{variable}} placeholders.
authType	enum req	none sends the request unauthenticated · bearer needs an Authorization header in headers · customHeaders authenticates through the headers you supply · oauth_connection resolves a token from a connection and needs oauthConnectionId.
fallbackMessage	string req	What the agent tells the caller when the request fails or times out.
oauthConnectionId	string opt	Numeric id of a connected OAuth connection. Required for oauth_connection, rejected for every other auth type. Take it from list_custom_actions on an action already using one.
variables	array opt	Values interpolated into the request, each { name, description, exampleValue, isSystem, required }. name and description are required and names must be unique. System variables are filled in by Upfirst from the call itself; custom ones are collected from the caller. A before -timing action may only use system variables. Default [].
queryParams	array opt	Query string parameters, each { key, value }. Values may use placeholders. Default [].
headers	array opt	Request headers, each { key, value }. Bearer auth carries its token in an Authorization header here. Never send the [redacted] placeholder back. Default [].
allowedOutputFields	string[] opt	Fields of the JSON response the agent may read. Empty passes the response through untouched. Default [].
bodyTemplate	string opt	Request body sent as-is with placeholders substituted. Empty for none.
sampleValues	object opt	A value per variable name, used when the action is tried out.
timeoutSeconds	integer opt	1–30. Default 10.
isActive	boolean opt	On from the start. Default true.
condition	string or null opt	after timing only. Plain-language rule checked against the finished call; null fires after every call. Leave it out for before and during.

Returns the created action with its new id.

Change a custom action. Partial update: only the fields you send change. Send at least one settable field or a new set of agents. Lists are replaced whole, not merged, so read the action with list_custom_actions first.

Parameter	Type	Description
id	string req	Action id from list_custom_actions.
agentIds	string[] opt	New set of agents that get the action. Send it together with autoLinkNewAgents, or leave both out to keep the current links.
autoLinkNewAgents	boolean opt	Also give the action to every agent created later. When true, agentIds must list every current agent.
oauthConnectionId	string or null opt	null clears it. Send null in the same call that moves the action off the oauth_connection auth type.
condition	string or null opt	null clears it. Send null in the same call that moves the action off after timing.
variables, queryParams, headers, allowedOutputFields	array opt	Each replaces its whole list. Send every entry you want to keep. A header carrying the [redacted] placeholder is refused; send the real value or leave that header out.
Other create fields	opt	name, description, timing, httpMethod, url, authType, bodyTemplate, sampleValues, fallbackMessage, timeoutSeconds, isActive. Same values as create.

An action linked to several agents is edited for all of them.

Returns the fields the update wrote.

Permanently delete a custom action. Every agent linked to it stops calling that API.

Parameter	Type	Description
id	string req	Action id to delete.

There is no way to restore a deleted action. Getting it back means creating it again from scratch, and list_custom_actions returns its configuration only while it still exists.

Returns { id, note }, where note confirms the delete in plain language.

05

Calls

Read the business's call history, one call's details, and its transcript. Only calls that have finished appear; a call shows up shortly after it ends.

List and filter call history, most recent first. Compact rows with no transcripts or summaries (use the tools below for those).

Parameter	Type	Description
statuses	enum[] opt	Filter by outcome, each call has exactly one: test · blocked · spam · hungUp · completed.
query	string opt	Free-text search over call summaries and transcripts.
tags	string[] opt	Match calls carrying any of these tags (by name or id).
startDate	date opt	Bare YYYY-MM-DD = calendar day in the business timezone, or a full ISO datetime.
endDate	date opt	As above; inclusive.
archived	boolean opt	Return archived calls instead of active ones. Default false.
offset, limit	number opt	Paging. limit is 1–100, default 25.

Returns call rows (caller, time, duration, outcome, tags, linked contact, transcript-turn count) plus totalCount.

Full details of one call, everything except the transcript text and recording.

Parameter	Type	Description
callId	string req	Numeric call id from list_calls.

Returns timing, outcome, caller & receptionist numbers, the AI-written summary, captured data fields, the skills the agent used (with when each fired), tags, your team's comments, and the transcript-turn count.

The conversation text of one call as ordered turns, each stamped with an [mm:ss] offset and its speaker.

Parameter	Type	Description
callId	string req	Numeric call id from list_calls.
offset, limit	number opt	Paging over turns. limit is 1–200, default 100. A typical call fits in one response; page only when the note says more turns remain.

Speakers are Agent (the AI receptionist), Caller (the person who dialed), and Transferee (a human the call was handed to).

Returns turns (offset, speaker, text) plus totalCount.

FAQ

How do I get Upfirst to start answering my calls?

We give you a phone number. You can hand that number out and have people call it directly, but most businesses forward calls to it from the line they already use.

You choose how much to forward: every call, only the ones you miss, or, depending on your phone, carrier, or VoIP system, only during certain hours. The steps differ for every provider, so see Forward all your calls to Upfirst for yours.

Do I need an API key?

No. Authorization is a standard OAuth 2.1 sign-in. The first call opens Upfirst's sign-in page, you approve access once, and there is nothing to copy, paste, or store.

Which AI assistants can I use this with?

Any client that supports remote MCP servers over HTTP. The Connecting section has setup for Claude, Claude Code, Cursor, VS Code, and Codex. For anything else, point it at https://mcp.upfirst.ai as a streamable HTTP server and it will handle the sign-in on the first call.

What can my assistant reach?

Only the organization you signed in as. Every tool is scoped to that organization, and ids from any other one are never accessible. Within it, the assistant can read calls and transcripts and change receptionist settings, skills, knowledge, and custom actions, and choose which receptionists each one applies to, so treat the connection the way you would treat being signed in to the dashboard.

Why doesn't a call I just took show up?

Only finished calls appear, and a call shows up shortly after it ends. Calls in progress are not available until they hang up. If a call is still missing, check whether it was archived, since list_calls returns active calls unless you pass archived: true.

What can't I do over MCP?

Voice, timezone, and language; scheduling skills; OAuth connections for custom actions; deleting a transfer skill; and importing knowledge from a website are all managed in the Upfirst dashboard. Call recordings are not available over this connection either. The tools say so where it applies.