Plain MCP

Vendor MCP63 toolsOAuth 2.1/DCRCustomer SupportProductivity

Connect to Plain MCP. Manage customer support threads, labels, tenants, Help Center articles, and thread field schemas directly from your AI workflows.

Plain MCP connector

Install the SDK
Section titled “Install the SDK”
- Node.js
- Python
Terminal window
1 npm install @scalekit-sdk/node
Terminal window
1 pip install scalekit
Full SDK reference: Node.js | Python
Set your credentials
Section titled “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>
```

1
import { ScalekitClient } from '@scalekit-sdk/node'
2
import 'dotenv/config'
3

4
const scalekit = new ScalekitClient(
5
  process.env.SCALEKIT_ENV_URL,
6
  process.env.SCALEKIT_CLIENT_ID,
7
  process.env.SCALEKIT_CLIENT_SECRET,
8
)
9
const actions = scalekit.actions
10

11
const connector = 'plainmcp'
12
const identifier = 'user_123'
13

14
// Generate an authorization link for the user
15
const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
16
console.log('Authorize Plain MCP:', link)
17
process.stdout.write('Press Enter after authorizing...')
18
await new Promise(r => process.stdin.once('data', r))
19

20
// Make your first call
21
const result = await actions.executeTool({
22
  connector,
23
  identifier,
24
  toolName: 'plainmcp_getcustomers',
25
  toolInput: {},
26
})
27
console.log(result)

1
import os
2
from scalekit.client import ScalekitClient
3
from dotenv import load_dotenv
4
load_dotenv()
5

6
scalekit_client = ScalekitClient(
7
    env_url=os.getenv("SCALEKIT_ENV_URL"),
8
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
9
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
10
)
11
actions = scalekit_client.actions
12

13
connection_name = "plainmcp"
14
identifier = "user_123"
15

16
# Generate an authorization link for the user
17
link_response = actions.get_authorization_link(
18
    connection_name=connection_name,
19
    identifier=identifier,
20
)
21
print("Authorize Plain MCP:", link_response.link)
22
input("Press Enter after authorizing...")
23

24
# Make your first call
25
result = actions.execute_tool(
26
    tool_input={},
27
    tool_name="plainmcp_getcustomers",
28
    connection_name=connection_name,
29
    identifier=identifier,
30
)
31
print(result)

What you can do

Connect this agent connector to let your agent:

Startsidekicksession records — Start a new Sidekick (Plain’s AI agent) session and return the handle used by every other Sidekick tool
Sendsidekickmessage records — Send a follow-up message into an existing Sidekick session
Searchthreadlinkcandidates records — Search a connected issue tracker for external entities that can be linked to a thread via createThreadLink
Resolvesidekickapproval records — Approve or deny a Sidekick tool-call approval request
Mergethread records — Merge one Plain thread into another (a MERGED_INTO native thread link)
Listsidekicksessions records — List Sidekick sessions in the workspace, most recent activity first

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.

plainmcp_addgeneratedreply#Add an AI-generated reply to a thread in Plain.1 param

Add an AI-generated reply to a thread in Plain.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_addlabels#Add one or more labels to a thread.1 param

Add one or more labels to a thread.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_archivelabeltype#Archive a label type so it can no longer be applied to threads.1 param

Archive a label type so it can no longer be applied to threads.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_assignthread#Assign a thread to a user or machine user.1 param

Assign a thread to a user or machine user.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_bulkupsertthreadfields#Create or update multiple thread field values in a single call.1 param

Create or update multiple thread field values in a single call.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_changethreadpriority#Update the priority of a thread. Valid priorities are 0 (urgent) through 3 (low).1 param

Update the priority of a thread. Valid priorities are 0 (urgent) through 3 (low).

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_createlabeltype#Create a new label type that can be applied to threads.1 param

Create a new label type that can be applied to threads.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_createnote#Add an internal note to a thread, visible only to workspace members.1 param

Add an internal note to a thread, visible only to workspace members.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_createsnippet#Create a new snippet (reusable reply template) in the workspace. name is what agents search for when inserting the snippet; text is the plain-text body (required). Optionally provide markdown for rich-text channels, and path (alphanumeric only) to place the snippet in a folder in the Plain app. Snippet bodies may include template variables such as {{ customer.email }}, {{ customer.fullName }}, {{ user.publicName }}, {{ thread.ref }}.1 param

Create a new snippet (reusable reply template) in the workspace. name is what agents search for when inserting the snippet; text is the plain-text body (required). Optionally provide markdown for rich-text channels, and path (alphanumeric only) to place the snippet in a folder in the Plain app. Snippet bodies may include template variables such as {{ customer.email }}, {{ customer.fullName }}, {{ user.publicName }}, {{ thread.ref }}.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_createthread#Open a new support thread for an existing customer. Does not send a message — follow up with replyToThread if needed.1 param

Open a new support thread for an existing customer. Does not send a message — follow up with replyToThread if needed.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_createthreadfieldschema#Create a new custom thread field schema for the workspace.1 param

Create a new custom thread field schema for the workspace.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_createthreadlink#Link a thread to an external entity (e.g. a Linear issue, Jira issue, incident.io incident, or another Plain thread/task). Provide threadId plus exactly one way to identify the link target: linearIssue, jiraIssue, plainThread, plainTask, or sourceId+sourceType (use searchThreadLinkCandidates to discover sourceId for a given sourceType).1 param

Link a thread to an external entity (e.g. a Linear issue, Jira issue, incident.io incident, or another Plain thread/task). Provide threadId plus exactly one way to identify the link target: linearIssue, jiraIssue, plainThread, plainTask, or sourceId+sourceType (use searchThreadLinkCandidates to discover sourceId for a given sourceType).

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_deletethreadfieldschema#Permanently delete a custom thread field schema by key.1 param

Permanently delete a custom thread field schema by key.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_deletethreadlink#Remove a link between a thread and an external entity. Pass the threadLinkId of the link to delete (the id returned by createThreadLink or listed under a thread's links in getThreadDetails).1 param

Remove a link between a thread and an external entity. Pass the threadLinkId of the link to delete (the id returned by createThreadLink or listed under a thread's links in getThreadDetails).

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_getattachmentdownloadurl#Generate a short-lived download URL for an attachment on a thread. Use attachment IDs returned by getThreadDetails. The returned downloadUrl expires after 3 minutes. Requires the attachment:download permission.1 param

Generate a short-lived download URL for an attachment on a thread. Use attachment IDs returned by getThreadDetails. The returned downloadUrl expires after 3 minutes. Requires the attachment:download permission.

NameTypeRequiredDescription

attachmentIdstringrequiredAttachment ID from a thread's timeline entries (e.g. NoteEntry, ChatEntry, EmailEntry), returned by getThreadDetails.

plainmcp_getcustomerdetails#Fetch a customer's full profile including email, assignment, company, and timestamps.1 param

Fetch a customer's full profile including email, assignment, company, and timestamps.

NameTypeRequiredDescription

customerIdstringrequiredPlain customer ID (starts with c_). Get it from getCustomers or getCustomerDetails.

plainmcp_getcustomers#Return a paginated list of all customers in the workspace.2 params

Return a paginated list of all customers in the workspace.

NameTypeRequiredDescription

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

firstnumberoptionalNumber of results to return per page. Defaults to 10.

plainmcp_getcustomerthreads#Return all threads belonging to a specific customer, with optional status filtering.5 params

Return all threads belonging to a specific customer, with optional status filtering.

NameTypeRequiredDescription

customerIdstringrequiredPlain customer ID (starts with c_). Get it from getCustomers or getCustomerDetails.

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

firstnumberoptionalNumber of results to return per page. Defaults to 10.

statusDetailsarrayoptionalFilter by status detail. Accepted values: CREATED, NEW_REPLY, WAITING_FOR_CUSTOMER, IN_PROGRESS.

statusesarrayoptionalFilter by thread status. Accepted values: TODO, SNOOZED, DONE.

plainmcp_gethelpcenterarticle#Fetch a single Help Center article by its ID.1 param

Fetch a single Help Center article by its ID.

NameTypeRequiredDescription

idstringrequiredUnique identifier of the resource.

plainmcp_gethelpcenterarticlebyslug#Fetch a Help Center article by its URL slug.2 params

Fetch a Help Center article by its URL slug.

NameTypeRequiredDescription

helpCenterIdstringrequiredPlain Help Center ID (starts with hc_). Get it from getHelpCenters.

slugstringrequiredURL slug of the Help Center article.

plainmcp_gethelpcenterarticlegroups#Return all article groups for a Help Center.3 params

Return all article groups for a Help Center.

NameTypeRequiredDescription

helpCenterIdstringrequiredPlain Help Center ID (starts with hc_). Get it from getHelpCenters.

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

firstnumberoptionalNumber of results to return per page. Defaults to 10.

plainmcp_gethelpcenterarticles#Return a paginated list of articles in a Help Center.3 params

Return a paginated list of articles in a Help Center.

NameTypeRequiredDescription

helpCenterIdstringrequiredPlain Help Center ID (starts with hc_). Get it from getHelpCenters.

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

firstnumberoptionalNumber of results to return per page. Defaults to 10.

plainmcp_gethelpcenters#Return all Help Centers in the workspace.2 params

Return all Help Centers in the workspace.

NameTypeRequiredDescription

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

firstnumberoptionalNumber of results to return per page. Defaults to 10.

plainmcp_getlabels#Return all label types available in the workspace.2 params

Return all label types available in the workspace.

NameTypeRequiredDescription

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

firstnumberoptionalNumber of results to return per page. Defaults to 10.

plainmcp_getmyassignedthreads#Return threads assigned to the authenticated user, with optional status and priority filters.6 params

Return threads assigned to the authenticated user, with optional status and priority filters.

NameTypeRequiredDescription

userIdstringrequiredPlain user ID (starts with u_). Get it from getUserByEmail or getMyUser.

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

firstnumberoptionalNumber of results to return per page. Defaults to 10.

prioritiesarrayoptionalFilter by priority: 0 = urgent, 1 = high, 2 = normal, 3 = low.

statusDetailsarrayoptionalFilter by status detail. Accepted values: CREATED, NEW_REPLY, WAITING_FOR_CUSTOMER, IN_PROGRESS.

statusesarrayoptionalFilter by thread status. Accepted values: TODO, SNOOZED, DONE.

plainmcp_getmyuser#Return the profile of the currently authenticated workspace user.0 params

Return the profile of the currently authenticated workspace user.

plainmcp_getmyworkspace#Return details about the current workspace including its ID and name.0 params

Return details about the current workspace including its ID and name.

plainmcp_getsidekicksession#Poll a Sidekick session: read its status, its newest messages, and any approval it is blocked on. Call this repeatedly after startSidekickSession or sendSidekickMessage.3 params

Poll a Sidekick session: read its status, its newest messages, and any approval it is blocked on. Call this repeatedly after startSidekickSession or sendSidekickMessage.

NameTypeRequiredDescription

discussionIdstringrequiredSidekick session handle (starts with thdis_) returned by startSidekickSession.

beforestringoptionalPagination cursor to page backwards through older messages. Use pageInfo.startCursor from a previous response.

lastnumberoptionalNumber of newest messages to return. Defaults to 10.

plainmcp_getsnippet#Fetch a single snippet by ID, including soft-deleted snippets (where isDeleted is true). Use this when you already have a snippet ID from getSnippets or another tool.1 param

Fetch a single snippet by ID, including soft-deleted snippets (where isDeleted is true). Use this when you already have a snippet ID from getSnippets or another tool.

NameTypeRequiredDescription

snippetIdstringrequiredSnippet ID (starts with sn_), from getSnippets or another tool.

plainmcp_getsnippets#Fetch a paginated list of snippets from the workspace. Snippets are reusable reply templates that agents insert when composing replies. Soft-deleted snippets are excluded from this list.2 params

Fetch a paginated list of snippets from the workspace. Snippets are reusable reply templates that agents insert when composing replies. Soft-deleted snippets are excluded from this list.

NameTypeRequiredDescription

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

firstnumberoptionalNumber of results to return per page. Defaults to 50.

plainmcp_gettenantdetails#Fetch full details for a specific tenant by its ID.1 param

Fetch full details for a specific tenant by its ID.

NameTypeRequiredDescription

tenantIdstringrequiredPlain tenant ID (starts with t_). Get it from getCustomers.

plainmcp_gettenants#Return a paginated list of all tenants in the workspace.2 params

Return a paginated list of all tenants in the workspace.

NameTypeRequiredDescription

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

firstnumberoptionalNumber of results to return per page. Defaults to 10.

plainmcp_getthreaddetails#Fetch a thread's full details and timeline entries by thread ID.3 params

Fetch a thread's full details and timeline entries by thread ID.

NameTypeRequiredDescription

threadIdstringrequiredPlain thread ID (starts with th_). Get it from getThreads or searchThreads.

timelineCursorstringoptionalPagination cursor for the thread timeline from the previous pageInfo.endCursor.

timelineFirstnumberoptionalNumber of timeline entries to return per page.

plainmcp_getthreadfieldschemas#Return all custom thread field schemas defined in the workspace.2 params

Return all custom thread field schemas defined in the workspace.

NameTypeRequiredDescription

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

firstnumberoptionalNumber of results to return per page. Defaults to 10.

plainmcp_getthreadknowledgesourcecitations#Fetch the knowledge sources cited by AI agent replies on a thread. Currently only Ari, Plain's AI support agent, produces citations. Correlate timelineEntryId with the timeline entry id values from getThreadDetails to see which reply cited which source. Returns an empty list when the thread has no citations.1 param

Fetch the knowledge sources cited by AI agent replies on a thread. Currently only Ari, Plain's AI support agent, produces citations. Correlate timelineEntryId with the timeline entry id values from getThreadDetails to see which reply cited which source. Returns an empty list when the thread has no citations.

NameTypeRequiredDescription

threadIdstringrequiredPlain thread ID (starts with th_) to fetch citations for.

plainmcp_getthreads#Return threads with flexible filtering by status, priority, assignee, customer, labels, or date range.11 params

Return threads with flexible filtering by status, priority, assignee, customer, labels, or date range.

NameTypeRequiredDescription

assignedToUserarrayoptionalFilter threads assigned to these user IDs (start with u_).

createdAtAfterstringoptionalReturn only threads created after this ISO 8601 timestamp.

createdAtBeforestringoptionalReturn only threads created before this ISO 8601 timestamp.

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

customerIdsarrayoptionalFilter by these Plain customer IDs (start with c_).

firstnumberoptionalNumber of results to return per page. Defaults to 10.

isAssignedbooleanoptionalPass true for assigned threads, false for unassigned, or omit for all.

labelTypeIdsarrayoptionalFilter by these label type IDs (start with lt_). Get them from getLabels.

prioritiesarrayoptionalFilter by priority: 0 = urgent, 1 = high, 2 = normal, 3 = low.

statusDetailsarrayoptionalFilter by status detail. Accepted values: CREATED, NEW_REPLY, WAITING_FOR_CUSTOMER, IN_PROGRESS.

statusesarrayoptionalFilter by thread status. Accepted values: TODO, SNOOZED, DONE.

plainmcp_getuserbyemail#Look up a workspace user by their email address.1 param

Look up a workspace user by their email address.

NameTypeRequiredDescription

emailstringrequiredEmail address of the user.

plainmcp_listsidekicksessions#List Sidekick sessions in the workspace, most recent activity first. Use this to resume a session from an earlier conversation, check whether a session landed after a timeout, or find sessions that need attention. Pass agentStatuses: [NEEDS_INPUT] for sessions blocked on a human approval decision, or agentStatuses: [IN_PROGRESS] for ones still working. statuses is the session's own lifecycle (OPEN/RESOLVED) and does not overlap with agentStatuses.5 params

List Sidekick sessions in the workspace, most recent activity first. Use this to resume a session from an earlier conversation, check whether a session landed after a timeout, or find sessions that need attention. Pass agentStatuses: [NEEDS_INPUT] for sessions blocked on a human approval decision, or agentStatuses: [IN_PROGRESS] for ones still working. statuses is the session's own lifecycle (OPEN/RESOLVED) and does not overlap with agentStatuses.

NameTypeRequiredDescription

afterstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

agentStatusesarrayoptionalFilter by agent activity. Known values: NEEDS_INPUT, IN_PROGRESS, IDLE, UNKNOWN.

createdByUserIdsarrayoptionalFilter to sessions created by these Plain user IDs. Use getMyUser to find your own user id.

firstnumberoptionalNumber of results to return per page.

statusesarrayoptionalFilter by session lifecycle status. Accepted values: IN_PROGRESS, IDLE, RESOLVED, APPROVAL_REQUESTED.

plainmcp_markthreadasdone#Mark a thread as done, moving it out of the active queue.1 param

Mark a thread as done, moving it out of the active queue.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_markthreadastodo#Mark a thread as todo, returning it to the active queue.1 param

Mark a thread as todo, returning it to the active queue.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_mergethread#Merge one Plain thread into another (a MERGED_INTO native thread link). The child thread is merged into the parent thread; on success the child thread is marked as done. For a non-merging association between threads or to an external entity, use createThreadLink instead.2 params

Merge one Plain thread into another (a MERGED_INTO native thread link). The child thread is merged into the parent thread; on success the child thread is marked as done. For a non-merging association between threads or to an external entity, use createThreadLink instead.

NameTypeRequiredDescription

childThreadIdstringrequiredThread ID (starts with th_) of the thread to merge in. This thread will be marked as done.

parentThreadIdstringrequiredThread ID (starts with th_) of the thread to merge into.

plainmcp_movelabeltype#Reorder a label type within the workspace label list.1 param

Reorder a label type within the workspace label list.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_removelabels#Remove one or more labels from a thread.1 param

Remove one or more labels from a thread.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_reorderthreadfieldschemas#Change the display order of custom thread field schemas.1 param

Change the display order of custom thread field schemas.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_replytothread#Send a reply to the last message in a thread via email, Slack, or chat.1 param

Send a reply to the last message in a thread via email, Slack, or chat.

NameTypeRequiredDescription

inputstringrequiredNo description.

plainmcp_resolvesidekickapproval#Approve or deny a Sidekick tool-call approval request. ASK THE USER BEFORE CALLING THIS - show them the justification and every requested call from getSidekickSession's approval-request entry, and wait for an explicit instruction. Approving authorises Sidekick's own credentials (usually broader than the user's), not the user's own action. Denying is always safe and only reduces what Sidekick may do.3 params

Approve or deny a Sidekick tool-call approval request. ASK THE USER BEFORE CALLING THIS - show them the justification and every requested call from getSidekickSession's approval-request entry, and wait for an explicit instruction. Approving authorises Sidekick's own credentials (usually broader than the user's), not the user's own action. Denying is always safe and only reduces what Sidekick may do.

NameTypeRequiredDescription

decisionstringrequiredApproval decision. APPROVED lets Sidekick run the requested calls; DENIED blocks them.

leaseIdstringrequiredThe leaseId from the pending approval-request entry returned by getSidekickSession.

reviewerNotestringoptionalOptional note explaining the decision, shown alongside the approval record.

plainmcp_searchcustomers#Search customers by name or email and return a paginated list of matches.3 params

Search customers by name or email and return a paginated list of matches.

NameTypeRequiredDescription

searchstringrequiredSearch query to filter results by text.

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

firstnumberoptionalNumber of results to return per page. Defaults to 10.

plainmcp_searchtenants#Search tenants by name and return matching results.3 params

Search tenants by name and return matching results.

NameTypeRequiredDescription

searchTermstringrequiredSearch text to filter tenant results.

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

firstnumberoptionalNumber of results to return per page. Defaults to 10.

plainmcp_searchthreadlinkcandidates#Search a connected issue tracker for external entities that can be linked to a thread via createThreadLink. Scope the search to one issue tracker with sourceType (e.g. jira_issue, incidentio_incident, shortcut_story, rootly_incident, github_issue) and match against issue titles or identifiers with the free-text searchQuery. Requires a connected issue tracker integration for the given sourceType.4 params

Search a connected issue tracker for external entities that can be linked to a thread via createThreadLink. Scope the search to one issue tracker with sourceType (e.g. jira_issue, incidentio_incident, shortcut_story, rootly_incident, github_issue) and match against issue titles or identifiers with the free-text searchQuery. Requires a connected issue tracker integration for the given sourceType.

NameTypeRequiredDescription

searchQuerystringrequiredFree-text search matched against issue titles or identifiers.

sourceTypestringrequiredIssue tracker to search. Accepted values include jira_issue, incidentio_incident, shortcut_story, rootly_incident, github_issue.

cursorstringoptionalPagination cursor from the previous response's pageInfo.endCursor.

firstnumberoptionalNumber of results to return per page.

plainmcp_searchthreads#Search threads by text with optional filters for status, priority, assignee, customer, and labels.9 params

Search threads by text with optional filters for status, priority, assignee, customer, and labels.

NameTypeRequiredDescription

searchQuerystringrequiredSearch text to match against thread title, description, or messages.