# Upfirst MCP Server

Upfirst's MCP server lets an AI assistant, like Claude, ChatGPT, or Cursor,
connect to your Upfirst account through the Model Context Protocol (MCP).

Once it's connected you can work by asking instead of clicking. Pull up last
week's calls, read a transcript, fix an answer your receptionist got wrong, add
a rule for transferring callers, connect it to an external API, or set up a
whole new receptionist from a description of your business.

Reference page: https://upfirst.ai/docs/mcp

## 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 25 tools, which
can both read your account and change it.

### Claude (desktop app and claude.ai)

Upfirst is in Claude's connector directory. Open the link below, add Upfirst,
then sign in to Upfirst and approve access.

https://claude.ai/directory/upfirst

To add it as a custom connector instead: open **Customize > Connectors**, click
**+**, then **Add custom connector**. Name it `Upfirst`, paste
`https://mcp.upfirst.ai` as the remote MCP server URL, then click **Add**,
click **Connect**, sign in to Upfirst, and approve access. 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.

### ChatGPT

Upfirst is in ChatGPT's plugin directory. Open the link below, add Upfirst,
then sign in to Upfirst and approve access.

https://chatgpt.com/plugins/plugin_asdk_app_6aa057dfb19c81919777fdc34a9d1f12?search=upfirst

### Claude Code

```
claude mcp add --transport http upfirst https://mcp.upfirst.ai
```

That adds it to the current project. Add `--scope user` to make it available
everywhere. Then run `/mcp` inside Claude Code and sign in.

### Cursor

`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "upfirst": {
      "url": "https://mcp.upfirst.ai"
    }
  }
}
```

Use `.cursor/mcp.json` in a project instead to scope it to that project.
Cursor prompts you to sign in the first time it calls the server.

### VS Code

`.vscode/mcp.json`:

```json
{
  "servers": {
    "upfirst": {
      "type": "http",
      "url": "https://mcp.upfirst.ai"
    }
  }
}
```

Start the server from the play button in the config file, then use it from
Copilot's agent mode. Sign in when prompted.

### Codex

`~/.codex/config.toml`:

```toml
[mcp_servers.upfirst]
url = "https://mcp.upfirst.ai"
```

Then run `codex mcp login upfirst` to authorize.

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`, greeting ids
from `list_agent_greetings`, 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, greeting, 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.

## Account & agents

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

### get_account_overview (Read)

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 and knowledge names); calls in the last 30 days (settled calls only; test
and archived calls are not counted).

### list_agents (Read)

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.

### get_agent_by_id (Read)

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

| Parameter | Type | Description |
| --- | --- | --- |
| `agentId` | string, required | Numeric agent id from `list_agents`. |

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

### update_agent (Write)

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

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

Voice, timezone, and language are managed on the dashboard and can't be changed
here. The two blocking flags are organization-wide: setting either one changes
it for every active agent, the same as the dashboard. `greetingMessage` is the
default greeting. Greetings for certain hours or dates have their own tools
under Scheduled greetings.

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

## Scheduled greetings

A scheduled greeting is what a receptionist says first on calls that fall inside
its schedule, like an after-hours or holiday greeting. Each one belongs to a
single agent. When no scheduled greeting matches the time of the call, the agent
uses its default greeting, which is read with `get_agent_by_id` and changed
with `update_agent`.

### list_agent_greetings (Read)

List an agent's scheduled greetings, including inactive ones. Read this before
changing a greeting, so nothing is overwritten unseen.

| Parameter | Type | Description |
| --- | --- | --- |
| `agentId` | string, required | Agent whose greetings to list. |

Returns: each greeting's id, `text`, active flag, `kind`, and
`schedule`. `kind` is read-only: `text` means the greeting is spoken as
written, `instruction` means the agent builds the greeting from it, and
`unknown` means it is not classified yet.

### create_agent_greeting (Write)

Add a scheduled greeting to an agent. The greeting is saved only when the whole
request is valid.

| Parameter | Type | Description |
| --- | --- | --- |
| `agentId` | string, required | Agent the greeting belongs to. |
| `text` | string, required | The exact words to say, or an instruction for how to greet. |
| `schedule` | object, required | When the greeting is used, in the agent's timezone. See Greeting schedules. |
| `isActive` | boolean, optional | Whether the greeting is used on calls from the start. Defaults to `true`. |

The schedule must not overlap another active greeting of the same agent. Weekly
hours and dates are checked separately. `kind` is set by the system: it reads
`unknown` right after a write and is classified within seconds.

Returns: the new greeting's id and its fields.

### update_agent_greeting (Write)

Change a scheduled greeting's text, active flag, or schedule. Partial update:
send only what changes; at least one field is required.

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string, required | Greeting id, from `list_agent_greetings`. |
| `text` | string, optional | New greeting text. |
| `isActive` | boolean, optional | Whether the greeting is used on calls. |
| `schedule` | object, optional | New schedule. See Greeting schedules. |

A new schedule replaces the stored one entirely, so read the greeting first and
send back the full schedule you want it to have. The same overlap rule applies
as on create. A text change resets `kind` to `unknown` until it is classified
again.

Returns: the fields the update wrote.

### delete_agent_greeting (Delete)

Permanently delete a scheduled greeting.

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string, required | Greeting id to delete. |

There is no way to restore a deleted greeting. Calls in its time slot then use
another matching greeting, or the agent's default greeting when none matches.

### Greeting schedules

A greeting's schedule has weekly hours in `days` and optional exact dates in
`dates`, all in the agent's timezone. `days` uses the same shape as
Schedules, under Knowledge: all seven days, each with `enabled` and
`workingPeriods`. Each entry in `dates` has a `date` as `YYYY-MM-DD` and
at least one time range in `periods`. A date entry wins over the weekly hours
for that day, which is how you set a holiday greeting.

```json
{
  "days": {
    "monday":    { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "tuesday":   { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "wednesday": { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "thursday":  { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "friday":    { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "saturday":  { "enabled": false, "workingPeriods": [] },
    "sunday":    { "enabled": false, "workingPeriods": [] }
  },
  "dates": [
    { "date": "2026-12-25", "periods": [{ "from": "00:00", "to": "23:59" }] }
  ]
}
```

## 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_agent_skills (Read)

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

| Parameter | Type | Description |
| --- | --- | --- |
| `agentId` | string, required | Agent whose skills to list. |
| `llmTool` | enum, optional | Only skills of this kind: `sendSms`, `sendScheduleSms`, `transferCall`, `scheduleSlot`, `customWebhook`. |
| `includeInactive` | boolean, optional | 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.

### create_sms_skill (Write)

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[], required | Agents that get the skill, at least one. Ids from `list_agents`. |
| `autoLinkNewAgents` | boolean, optional | Also give the skill to every agent created later. When `true`, `agentIds` must list every current agent. Default `false`. |
| `llmTool` | enum, required | `sendSms`, `sendScheduleSms` |
| `name` | string, required | Short label, shown on the dashboard. |
| `message` | string, required | The SMS text the agent sends, up to 306 characters. |
| `instruction` | string, required | When the agent should send it during a call. |
| `isActive` | boolean, optional | 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`.

### update_sms_skill (Write)

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, required | Skill id from `list_agent_skills`. |
| `llmTool` | enum, optional | Switch between `sendSms` and `sendScheduleSms`. |
| `name` | string, optional | New label. |
| `message` | string, optional | New SMS text, up to 306 characters. |
| `instruction` | string, optional | New guidance on when to send it. |
| `isActive` | boolean, optional | Switch the skill on or off. |
| `agentIds` | string[], optional | New set of agents that get the skill. Send it together with `autoLinkNewAgents`, or leave both out to keep the current links. |
| `autoLinkNewAgents` | boolean, optional | Also give the skill to every agent created later. When `true`, `agentIds` must list every current agent. |

Returns: the fields the update wrote.

### delete_sms_skill (Delete)

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

| Parameter | Type | Description |
| --- | --- | --- |
| `skillId` | string, required | 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.

### create_transfer_call_skill (Write)

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[], required | Agents that get the skill, at least one. Ids from `list_agents`. |
| `autoLinkNewAgents` | boolean, optional | Also give the skill to every agent created later. When `true`, `agentIds` must list every current agent. Default `false`. |
| `name` | string, required | Short label, shown on the dashboard. |
| `condition` | string, required | When to transfer, in plain language. |
| `preTransferMessage` | string, required | What the agent says before transferring. |
| `destinations` | array, required | One or more targets, tried in order, each `{ phoneNumber, label, phoneExtension }`. `phoneNumber` is required and must be E.164 (e.g. `+12025550123`). |
| `ringTimeoutSeconds` | number, optional | Ring time per destination, 5-60. |
| `noAnswerAction` | enum, optional | `endCall`, `returnToAgent` |
| `transferMethod` | enum, optional | `cold` hands the caller over directly; `warm` briefs the destination first. |
| `transferCallerId` | enum, optional | Number the destination sees: `upfirstNumber`, `callerNumber`. |
| `recordingMode` | enum, optional | `agentOnly` stops recording at the transfer; `fullCall` keeps recording after it. |
| `isActive` | boolean, optional | On from the start. Default `true`. |
| `schedule` | object, optional | 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`.

### update_transfer_call_skill (Write)

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, required | Skill id from `list_agent_skills`. |
| `destinations` | array, optional | Replaces the whole list. Send every number you want to keep. |
| `schedule` | object, optional | Replaces the stored hours. `null` clears the schedule, making the skill available around the clock. |
| Other create fields | optional | `name`, `condition`, `preTransferMessage`, `ringTimeoutSeconds`, `noAnswerAction`, `transferMethod`, `transferCallerId`, `recordingMode`, `isActive`. Same values as create. |
| `agentIds` | string[], optional | New set of agents that get the skill. Send it together with `autoLinkNewAgents`, or leave both out to keep the current links. |
| `autoLinkNewAgents` | boolean, optional | 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.

### Deleting a transfer skill

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.

## 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.

### get_agent_knowledge (Read)

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

| Parameter | Type | Description |
| --- | --- | --- |
| `agentId` | string, required | Agent whose knowledge to read. |
| `id` | string, optional | Return just this one entry. |
| `offset` | number, optional | Entries to skip. Default `0`. |
| `limit` | number, optional | Max entries, 1-100. Default `25`. |

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

### create_agent_knowledge (Write)

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[], required | Agents that get the entry, at least one. Ids from `list_agents`. |
| `autoLinkNewAgents` | boolean, optional | Also give the entry to every agent created later. When `true`, `agentIds` must list every current agent. Default `false`. |
| `name` | string, required | Display name of the entry. |
| `content` | string, required | Plain text, up to 250,000 characters. |
| `isActive` | boolean, optional | Active from the start. Default `true`. |
| `schedule` | object, optional | 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`.

### update_agent_knowledge (Write)

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, required | Entry id from `get_agent_knowledge`. |
| `name`, `isActive` | optional | New name / active flag. |
| `content` | string, optional | New text, replacing the stored content entirely. Up to 250,000 characters. |
| `schedule` | object, optional | New schedule. `null` clears it, making the entry always available; omit to keep the stored one. |
| `agentIds` | string[], optional | New set of agents that get the entry. Send it together with `autoLinkNewAgents`, or leave both out to keep the current links. |
| `autoLinkNewAgents` | boolean, optional | 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.

### delete_agent_knowledge (Delete)

Permanently delete a knowledge entry.

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string, required | 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.

### Schedules

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.

```json
{
  "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": [] }
  }
}
```

## 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.

### list_custom_actions (Read)

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, required | Agent whose actions to list. Every action linked to this agent is included. |
| `id` | string, optional | 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.

### create_custom_action (Write)

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

| Parameter | Type | Description |
| --- | --- | --- |
| `agentIds` | string[], required | Agents that get the action, at least one. Ids from `list_agents`. |
| `autoLinkNewAgents` | boolean, optional | Also give the action to every agent created later. When `true`, `agentIds` must list every current agent. Default `false`. |
| `name` | string, required | Short label, shown on the dashboard. |
| `description` | string, required | 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, required | `before`, `during`, `after`. |
| `httpMethod` | enum, required | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. |
| `url` | string, required | Endpoint the request goes to. May contain `{{variable}}` placeholders. |
| `authType` | enum, required | `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, required | What the agent tells the caller when the request fails or times out. |
| `oauthConnectionId` | string, optional | 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, optional | 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, optional | Query string parameters, each `{ key, value }`. Values may use placeholders. Default `[]`. |
| `headers` | array, optional | Request headers, each `{ key, value }`. Bearer auth carries its token in an `Authorization` header here. Never send the `[redacted]` placeholder back. Default `[]`. |
| `allowedOutputFields` | string[], optional | Fields of the JSON response the agent may read. Empty passes the response through untouched. Default `[]`. |
| `bodyTemplate` | string, optional | Request body sent as-is with placeholders substituted. Empty for none. |
| `sampleValues` | object, optional | A value per variable name, used when the action is tried out. |
| `timeoutSeconds` | integer, optional | 1-30. Default `10`. |
| `isActive` | boolean, optional | On from the start. Default `true`. |
| `condition` | string or null, optional | `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.

### update_custom_action (Write)

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, required | Action id from `list_custom_actions`. |
| `agentIds` | string[], optional | New set of agents that get the action. Send it together with `autoLinkNewAgents`, or leave both out to keep the current links. |
| `autoLinkNewAgents` | boolean, optional | Also give the action to every agent created later. When `true`, `agentIds` must list every current agent. |
| `oauthConnectionId` | string or null, optional | `null` clears it. Send `null` in the same call that moves the action off the `oauth_connection` auth type. |
| `condition` | string or null, optional | `null` clears it. Send `null` in the same call that moves the action off `after` timing. |
| `variables`, `queryParams`, `headers`, `allowedOutputFields` | array, optional | 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 | optional | `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.

### delete_custom_action (Delete)

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

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string, required | 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.

## 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_calls (Read)

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

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

### get_call_by_id (Read)

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

| Parameter | Type | Description |
| --- | --- | --- |
| `callId` | string, required | Numeric call id from `list_calls`. |

Returns: timing, outcome, caller and 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.

### get_call_transcript (Read)

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

| Parameter | Type | Description |
| --- | --- | --- |
| `callId` | string, required | Numeric call id from `list_calls`. |
| `offset`, `limit` | number, optional | 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
https://help.upfirst.ai/en/articles/10318231-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, ChatGPT, 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.
