Front MCP

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'frontmcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Front MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'frontmcp_get_my_identity',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "frontmcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Front MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="frontmcp_get_my_identity",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Update draft, conversation status — Update the body, subject, or recipients of an existing draft
• Conversation tag, move, assign — Add or remove tags on a conversation
• Send message — Send a draft message created via create_draft (queues it for delivery)
• Search conversations, contacts, accounts — Search conversations by query and/or filters
• Read message, conversation, contact — Fetch a single message by ID with full content
• List teams, teammates, tags — List teams in the workspace

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

frontmcp_add_comment#Add an internal comment to a conversation.2 params▾

Add an internal comment to a conversation.

NameTypeRequiredDescription

bodystringrequiredComment body text. Teammate @mentions in the body are resolved automatically.

conversationIdstringrequiredPublic conversation ID (cnv_xxx) to comment on.

frontmcp_assign_conversation#Assign a conversation to a teammate or team.2 params▾

Assign a conversation to a teammate or team.

NameTypeRequiredDescription

assigneeIdstringrequiredPublic teammate ID (tea_xxx) to assign to, or null to unassign.

conversationIdstringrequiredPublic conversation ID (cnv_xxx) to assign.

frontmcp_create_draft#Create a draft for an existing conversation or a new outbound conversation. Provide conversationId to draft a reply on an existing conversation. Omit conversationId and provide channelId to create a draft for a new outbound conversation; to[] and subject are optional. The body is HTML by default; set bodyFormat to send markdown or plain text instead.11 params▾

Create a draft for an existing conversation or a new outbound conversation. Provide conversationId to draft a reply on an existing conversation. Omit conversationId and provide channelId to create a draft for a new outbound conversation; to[] and subject are optional. The body is HTML by default; set bodyFormat to send markdown or plain text instead.

NameTypeRequiredDescription

bodystringrequiredDraft body. Interpreted per bodyFormat — HTML by default (use <br> or <p> tags for line breaks).

bccarrayoptionalBCC recipients for a new outbound conversation (email channels).

bodyFormatstringoptionalHow body is interpreted (default html): "html" is used as-is; "markdown" and "plain" are converted to HTML for you ("plain" preserves line breaks and escapes HTML characters).

ccarrayoptionalCC recipients for a new outbound conversation (email channels).

channelIdstringoptionalChannel to draft from (cha_xxx). Required for a new conversation (conversationId omitted); optional when replying to an existing conversation, where it overrides the conversation's default channel. If the user has not specified a channel for a new conversation, ask which to send from before choosing; prefer a personal channel. Use list_channels to discover available channels.

conversationIdstringoptionalPublic conversation ID (cnv_xxx) to draft a reply for. Omit to create a draft for a new outbound conversation (requires channelId).

inReplyToMessageIdstringoptionalMessage ID to draft a reply to; defaults to the latest message.

replyAllbooleanoptionalReply to all original recipients (default true).

sharedbooleanoptionalShare the draft with all conversation participants after creation. AI teammates must share drafts — the draft is always shared and passing false is rejected. For human callers it defaults to false (a private draft).

subjectstringoptionalSubject line for a new outbound conversation (email channels). Optional.

toarrayoptionalRecipients for a new outbound conversation, as the channel's handle type (email address, phone number, etc.). Optional — the draft can be addressed later.

frontmcp_delete_draft#Discard an unsent draft owned by the authenticated teammate. Pass the version from read_message for conflict detection — the call fails if the draft changed since you read it. Owner-only: the call returns an error if the draft belongs to another teammate.2 params▾

Discard an unsent draft owned by the authenticated teammate. Pass the version from read_message for conflict detection — the call fails if the draft changed since you read it. Owner-only: the call returns an error if the draft belongs to another teammate.

NameTypeRequiredDescription

draftIdstringrequiredPublic draft message ID (msg_xxx) to delete, from list_drafts or read_message.

versionstringrequiredOpaque version token from read_message.draftVersion. Used for conflict detection; the call fails with a conflict error if the draft changed since you read it.

frontmcp_get_attachment#Get a specific attachment on a message or comment. Returns attachment metadata (filename, contentType, size) plus a short-lived downloadUrl.1 param▾

Get a specific attachment on a message or comment. Returns attachment metadata (filename, contentType, size) plus a short-lived downloadUrl.

NameTypeRequiredDescription

attachmentIdstringrequiredPublic attachment link ID (fil_xxx), as returned by read_message.

frontmcp_get_my_identity#Get the calling agent's own identity: public ID, name, alias, and whether the caller is human. Takes no arguments.0 params▾

Get the calling agent's own identity: public ID, name, alias, and whether the caller is human. Takes no arguments.

frontmcp_list_channels#List channels accessible to the authenticated user. Filter by name, address, type, or inbox. Use this tool to discover channels before calling tools that require a channel ID.6 params▾

List channels accessible to the authenticated user. Filter by name, address, type, or inbox. Use this tool to discover channels before calling tools that require a channel ID.

NameTypeRequiredDescription

account_statusesstringoptionalOptional filter by channel account status.

inbox_idsstringoptionalOptional filter by inbox IDs. Prefer this instead of putting inbox names in name_query.

limitstringoptionalMaximum number of results (default 25, max 50)

name_querystringoptionalOptional channel display name or address keywords. Use this only for the channel identity itself.

offsetstringoptionalOffset for pagination (default 0). Use with limit to paginate through results.

typesstringoptionalOptional filter by channel type (for example email, chat, sms).

frontmcp_list_drafts#List in-flight draft messages authored by the authenticated teammate.1 param▾

List in-flight draft messages authored by the authenticated teammate.

NameTypeRequiredDescription

limitintegeroptionalMaximum number of drafts to return (default 50, max 200).

frontmcp_list_inboxes#List inboxes accessible to the authenticated user.10 params▾

List inboxes accessible to the authenticated user.

NameTypeRequiredDescription

access_modestringoptionalOptional filter by inbox access mode.

ai_enabledstringoptionalOptional filter by Front AI status.

business_hours_enabledstringoptionalOptional filter by business hours status.

circle_idsstringoptionalOptional filter by teammate group IDs who have access to the inbox.

global_rules_enabledstringoptionalOptional filter by company rules status.

limitstringoptionalMaximum number of results (default 25, max 50)

name_querystringoptionalOptional inbox name keywords. Use this only for the inbox name itself.

offsetstringoptionalOffset for pagination (default 0). Use with limit to paginate through results.

teammate_idsstringoptionalOptional filter by teammate IDs who have access to the inbox.

ticketing_enabledstringoptionalOptional filter by ticketing status.

frontmcp_list_statuses#List the company's ticket statuses. Returns an empty list when ticketing is not enabled for the company.3 params▾

List the company's ticket statuses. Returns an empty list when ticketing is not enabled for the company.

NameTypeRequiredDescription

limitstringoptionalMaximum number of results (default 50, max 100)

name_querystringoptionalOptional ticket status name keywords. Use this only for the status name itself.

offsetstringoptionalOffset for pagination (default 0). Use with limit to paginate through results.

frontmcp_list_tags#List tags in the workspace.7 params▾

List tags in the workspace.

NameTypeRequiredDescription

all_inboxesstringoptionalOptional filter by whether the tag applies to all inboxes.

inbox_idsstringoptionalOptional filter by inbox IDs this tag applies to.

is_visible_in_conversation_listsstringoptionalOptional filter by visibility in conversation lists.

limitstringoptionalMaximum number of results (default 50, max 100)

name_querystringoptionalOptional tag name keywords. Use this only for the tag name itself.

offsetstringoptionalOffset for pagination (default 0). Use with limit to paginate through results.

parent_tag_idstringoptionalOptional filter by parent tag ID.

frontmcp_list_teammates#List teammates in the workspace.4 params▾

List teammates in the workspace.

NameTypeRequiredDescription

limitstringoptionalMaximum number of results (default 10, max 25)

name_querystringoptionalName or email keywords to search for (for example "alex" or "alex@"). Use this only for teammate identity, not for workspace, status, or relationship intent.

offsetstringoptionalOffset for pagination (default 0). Use with limit to paginate through results.

statusesstringoptionalFilter by account status. Defaults to active statuses (active, pending, pending_email). Include "blocked" to see deactivated teammates.

frontmcp_list_teams#List teams in the workspace.3 params▾

List teams in the workspace.

NameTypeRequiredDescription

limitstringoptionalMaximum number of results (default 10, max 25)

name_querystringoptionalOptional team name or alias keywords. Use this only for the team name or alias.

offsetstringoptionalOffset for pagination (default 0). Use with limit to paginate through results.

frontmcp_move_conversation#Move a conversation to a different inbox. Replaces the conversation's current inbox association with the destination inbox — this is not additive. Provide the destination inbox ID (inb_xxx) from list_inboxes.2 params▾

Move a conversation to a different inbox. Replaces the conversation's current inbox association with the destination inbox — this is not additive. Provide the destination inbox ID (inb_xxx) from list_inboxes.

NameTypeRequiredDescription

conversationIdstringrequiredPublic conversation ID (cnv_xxx) to move.

inboxIdstringrequiredDestination inbox ID (inb_xxx), as returned by list_inboxes.

frontmcp_read_account#Read an account (company) record.1 param▾

Read an account (company) record.

NameTypeRequiredDescription

account_idstringrequiredThe account to read, identified by its private numeric ID or its public ID (acc_xxx).

frontmcp_read_contact#Read a contact record.1 param▾

Read a contact record.

NameTypeRequiredDescription

contactIdstringrequiredPublic contact card ID (crd_xxx).

frontmcp_read_conversation#Read a conversation: its header (subject, status, assigneeId, assigneeName, assigneeAlias, inboxes (each with id and name), tagIds, ticketIds, ticketStatus, scheduledReminders, updatedAt) plus a paginated, newest-first timeline of messages, comments, and activity entries under `entries`. Pass `entries.nextCursor` back as `cursor` to fetch older entries, and stop when `entries.hasMore` is false. Active drafts and customFields are included on the first page only (both fields are omitted once a `cursor` is supplied).3 params▾

Read a conversation: its header (subject, status, assigneeId, assigneeName, assigneeAlias, inboxes (each with id and name), tagIds, ticketIds, ticketStatus, scheduledReminders, updatedAt) plus a paginated, newest-first timeline of messages, comments, and activity entries under `entries`. Pass `entries.nextCursor` back as `cursor` to fetch older entries, and stop when `entries.hasMore` is false. Active drafts and customFields are included on the first page only (both fields are omitted once a `cursor` is supplied).

NameTypeRequiredDescription

conversationIdstringrequiredPublic conversation ID (cnv_xxx).

cursorstringoptionalPagination cursor for timeline entries.

limitintegeroptionalMaximum entries to return (default 50, max 200).

frontmcp_read_message#Fetch a single message by ID with full content. Returns the message body (quoted replies stripped for clarity), recipients (from/to/cc/bcc), attachments, author, draft status, and delivery error type if applicable.1 param▾

Fetch a single message by ID with full content. Returns the message body (quoted replies stripped for clarity), recipients (from/to/cc/bcc), attachments, author, draft status, and delivery error type if applicable.

NameTypeRequiredDescription

messageIdstringrequiredThe message ID to read (msg_xxx format).

frontmcp_search_accounts#Search accounts (companies) by name.3 params▾

Search accounts (companies) by name.

NameTypeRequiredDescription

limitstringoptionalMaximum number of results (default 10, max 25)

name_querystringoptionalOptional account name keywords. Use this only for the account name itself.

offsetstringoptionalOffset for pagination (default 0). Use with limit to paginate through results.

frontmcp_search_contacts#Search contacts by name or email.2 params▾

Search contacts by name or email.

NameTypeRequiredDescription

querystringrequiredSearch query for contacts (name, email, or handle).

cursorstringoptionalPagination cursor returned by a previous call.

frontmcp_search_conversations#Search conversations by query and/or filters. Use the `filters` object to narrow by inbox, assignee, team, tags, status, or an absolute date range (after/before). `query` is optional when at least one filter is provided, so filters alone can list an inbox or a teammate's conversations.4 params▾

Search conversations by query and/or filters. Use the `filters` object to narrow by inbox, assignee, team, tags, status, or an absolute date range (after/before). `query` is optional when at least one filter is provided, so filters alone can list an inbox or a teammate's conversations.

NameTypeRequiredDescription

cursorstringoptionalPagination cursor returned by a previous call.

filtersobjectoptionalOptional filter set to narrow results.

querystringoptionalFull-text search query for conversations. Optional when at least one filter is provided.

scopestringoptionalRestricts which conversations are searched (default "my_conversations"). "my_conversations": conversations assigned to you, in your private inboxes, or in shared inboxes you participate in. "my_workspace": every conversation in your workspace. "all_inboxes": every conversation you can access (broadest). Results echo the scope actually applied as resolvedScope.

frontmcp_send_message#Send a draft message created via create_draft (queues it for delivery). Works for both reply drafts and new conversation drafts.1 param▾

Send a draft message created via create_draft (queues it for delivery). Works for both reply drafts and new conversation drafts.

NameTypeRequiredDescription

draftIdstringrequiredDraft ID to send (msg_xxx), as returned by create_draft. The draft must be in compose state (not scheduled or already being sent), owned by the authenticated teammate, and have at least one recipient.

frontmcp_tag_conversation#Add or remove tags on a conversation.3 params▾

Add or remove tags on a conversation.

NameTypeRequiredDescription

conversationIdstringrequiredPublic conversation ID (cnv_xxx).

addTagsarrayoptionalTag IDs (tag_xxx) to add.

removeTagsarrayoptionalTag IDs (tag_xxx) to remove.

frontmcp_update_conversation_status#Update a conversation's status. Provide exactly one of `status`, `statusId`, or `snoozeUntil`. Use `status` ("archived" / "open") to archive or reopen from the requester's point of view, matching the Front "Archive" / "Move to inbox" buttons: if the requester is the conversation's assignee (or it lives in their private inbox), the change is global — everyone with access sees the new status; if the requester is not the assignee on a shared conversation, only their personal view changes. Setting `status: "open"` on a snoozed conversation cancels its reminder. Use `statusId` (a ticket-status, sts_xxx, from list_statuses) to set the ticket status on a ticketing-enabled inbox — this also updates the conversation's open/archived state to match the status category. Setting a ticket status requires ticketing to be enabled. Use `snoozeUntil` (ISO-8601) to snooze the conversation until a given time; all snoozes also auto-cancel when an inbound message arrives.4 params▾

Update a conversation's status. Provide exactly one of `status`, `statusId`, or `snoozeUntil`. Use `status` ("archived" / "open") to archive or reopen from the requester's point of view, matching the Front "Archive" / "Move to inbox" buttons: if the requester is the conversation's assignee (or it lives in their private inbox), the change is global — everyone with access sees the new status; if the requester is not the assignee on a shared conversation, only their personal view changes. Setting `status: "open"` on a snoozed conversation cancels its reminder. Use `statusId` (a ticket-status, sts_xxx, from list_statuses) to set the ticket status on a ticketing-enabled inbox — this also updates the conversation's open/archived state to match the status category. Setting a ticket status requires ticketing to be enabled. Use `snoozeUntil` (ISO-8601) to snooze the conversation until a given time; all snoozes also auto-cancel when an inbound message arrives.

NameTypeRequiredDescription

conversationIdstringrequiredPublic conversation ID (cnv_xxx).

snoozeUntilstringoptionalISO-8601 timestamp to snooze the conversation until (e.g. 2024-01-15T09:00:00Z): it archives now and reopens then. A snooze auto-cancels when an inbound message arrives. Provide exactly one of status, statusId, or snoozeUntil.

statusstringoptional"archived" removes the conversation from the requester's open inbox; "open" returns it. Whether other teammates see the change depends on whether the requester is the assignee — see the tool description. Provide either status or statusId, not both.

statusIdstringoptionalTicket-status ID (sts_xxx), as returned by list_statuses. Sets the ticket status; the conversation's open/archived state follows the status category. Requires ticketing to be enabled for the company. Provide exactly one of status, statusId, or snoozeUntil.

frontmcp_update_draft#Update the body, subject, or recipients of an existing draft. Pass the version from read_message for conflict detection — the call fails if the draft changed since you read it. Omitted fields are left unchanged; providing to/cc/bcc replaces that recipient list. Use takeOver:true to claim a draft you do not own.10 params▾

Update the body, subject, or recipients of an existing draft. Pass the version from read_message for conflict detection — the call fails if the draft changed since you read it. Omitted fields are left unchanged; providing to/cc/bcc replaces that recipient list. Use takeOver:true to claim a draft you do not own.

NameTypeRequiredDescription

draftIdstringrequiredPublic draft message ID (msg_xxx) to update, from list_drafts or read_message.

versionstringrequiredOpaque version token from read_message.draftVersion. Used for conflict detection; the call fails with a conflict error if the draft changed since you read it.

bccarrayoptionalReplace the BCC recipients. Omit to leave BCC unchanged; pass [] to clear it.

bodystringoptionalNew draft body (interpreted per bodyFormat; HTML by default). Omit to leave the body unchanged.

bodyFormatstringoptionalHow body is interpreted (default html): "html" is used as-is; "markdown" and "plain" are converted to HTML.

ccarrayoptionalReplace the CC recipients. Omit to leave CC unchanged; pass [] to clear it.

channelIdstringoptionalOverride the sending channel (cha_xxx). Omit to keep the draft's current channel.

subjectstringoptionalNew subject (email channels). Omit to leave the subject unchanged.

takeOverbooleanoptionalIf true and you are not the draft owner, claim authorship before editing. Omit (or set false) to enforce owner-only access — the call returns an error if you are not the current owner. No-op if you already own the draft.

toarrayoptionalReplace the TO recipients (channel handles). Omit to leave TO unchanged; pass [] to clear it.