// connections

Intercom

Manage Intercom contacts, companies, conversations, tickets, tags and Help Center articles, and reply to and route conversations. Connects with OAuth.

28 mcp tools64 operations
rest
https://api.superagnt.com/v1/connections/intercom plus the vendor's own path, with your superagnt_ API key as Authorization: Bearer.
mcp
Tools named connection_intercom_* on https://mcp.superagnt.com/mcp, served once the account is connected.
billing
Intercom bills your own account. Calls cost no superagnt_ data credits.
rate limit
10 requests a second, 600 a minute: the vendor's ceiling as the registry records it, for sizing bursts. Your plan's own limit is on Connections.
vendor docs
https://developers.intercom.com/docs/references/rest-api/api.intercom.io

The Intercom connection lets an agent run support in your Intercom workspace: manage contacts (users and leads) and companies, search, reply to, assign, snooze and close conversations, open and update tickets, tag records, and write Help Center articles and collections. It also reads teammates, teams, segments, data attributes and ticket types.

01

Setup

  1. Start the install. In the superagnt app open Integrations, pick Intercom and click Connect with Intercom.
  2. Approve it in Intercom. In the window Intercom opens, approve access for the Intercom workspace your agents should work in. There are no scopes to pick: the permissions are set on superagnt_'s Intercom app.
  3. Call Intercom. Intercom moves to Enabled: its REST route answers and its tools appear on your MCP server.

Intercom tokens do not expire. If access is removed on Intercom's side, calls fail until you reconnect.

02

Things to know

  • superagnt_ sends Intercom-Version: 2.11 on every call.
  • Most lists return { type, data, pages, total_count }. Contacts and conversations page with per_page (up to 150) and starting_after, from pages.next.starting_after; companies and articles page with per_page and page.
  • Search on contacts, conversations and tickets takes a nested query: a { field, operator, value } filter, or { operator: "AND", value: [...] } (or "OR") around several. Operators are =, !=, IN, NIN, <, >, ~ (contains), ^ (starts with) and $ (ends with). Search pages with pagination: { per_page, starting_after } in the body.
  • A reply as a teammate (type admin) and every call to manage a conversation need an admin_id: connection_intercom_admins_read action me returns the teammate the connection acts as.
  • By default a superagnt_ agent runs reads and searches without asking and asks before every write, replies included. Deleting, archiving or unarchiving a contact, and deleting a company, tag, article or collection, always ask a person first (Permissions).

03

Examples

Reply to a conversation

reply as a teammatebash
curl -X POST "https://api.superagnt.com/v1/connections/intercom/conversations/$CONVERSATION_ID/reply" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_type":"comment","type":"admin","admin_id":"'"$ADMIN_ID"'","body":"Thanks for reaching out. Taking a look now."}'

A comment reaches the contact. Send "message_type":"note" for an internal note only teammates see.

Assign a conversation

assign to a teammatebash
curl -X POST "https://api.superagnt.com/v1/connections/intercom/conversations/$CONVERSATION_ID/parts" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_type":"assignment","admin_id":"'"$ADMIN_ID"'","assignee_id":"'"$ASSIGNEE_ID"'"}'

The same call opens, closes or snoozes a conversation (message_type open, close or snoozed with snoozed_until).

Create a contact

create a userbash
curl -X POST "https://api.superagnt.com/v1/connections/intercom/contacts" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"user","email":"jane@example.com","name":"Jane Doe"}'

Find a contact by email

search contactsbash
curl -X POST "https://api.superagnt.com/v1/connections/intercom/contacts/search" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":{"field":"email","operator":"=","value":"jane@example.com"}}'
04// mcp tools

28 tools, one per resource and risk

MCP servers and agents on the grouped surface list Intercom as these tools. Each takes an action, and the ones that work across record types an object. Every operation also keeps its own per-operation name, in the next table, which works on every server. How grouping works: Grouped tools.

ToolRiskActions
connection_intercom_contacts_read

Read Intercom contacts

List, get or search contacts (users and leads), or list a contact's notes. Search matches are case-sensitive and emails are stored lowercased, so lowercase an email before searching for it.

read
listgetsearchlist_notes
connection_intercom_contacts_write

Create and update Intercom contacts

Create, update or unarchive a contact (a user or a lead), add a note to it, or attach it to a company. Custom attributes must exist first (connection_intercom_data_attributes_write).

write
createupdateunarchiveadd_noteattach_company
connection_intercom_contacts_delete

Delete, archive and merge Intercom contacts

Permanently delete a contact, archive one, merge a lead into a user, or detach a contact from a company. Deletes and merges cannot be undone.

destructive
deletearchivemerge_leaddetach_company
connection_intercom_companies_read

Read Intercom companies

List or get companies, or list a company's contacts.

read
listgetlist_contacts
connection_intercom_companies_write

Create and update Intercom companies

Create or update a company keyed by your own company_id.

write
upsert
connection_intercom_companies_delete

Delete an Intercom company

Permanently delete a company by its Intercom id (not your company_id).

destructive
delete
connection_intercom_conversations_read

Read Intercom conversations

List, get or search conversations; a conversation comes with its message parts.

read
listgetsearch
connection_intercom_conversations_send

Reply in Intercom conversations

Reply in a conversation as a teammate (message_type comment, which the contact receives) or as the contact, or leave an internal note (message_type note) that only teammates see. Admin ids come from connection_intercom_admins_read.

write
reply
connection_intercom_conversations_write

Start and route Intercom conversations

Start a conversation from a contact, assign, open, close or snooze a conversation, add a participant, or run the assignment rules. A body given with manage (on close or assignment) is posted in the conversation, where the contact sees it. Replies and internal notes: connection_intercom_conversations_send. Admin and team ids come from connection_intercom_admins_read and connection_intercom_teams_read.

write
createmanageadd_participantrun_assignment_rules
connection_intercom_conversations_delete

Remove an Intercom conversation participant

Remove a contact from a conversation.

destructive
remove_participant
connection_intercom_tickets_read

Read Intercom tickets

Get a ticket, or search tickets.

read
getsearch
connection_intercom_tickets_write

Create and update Intercom tickets

Create a ticket of a ticket type (connection_intercom_ticket_types_read lists them) for one or more contacts, or update a ticket's state, assignee or attributes.

write
createupdate
connection_intercom_ticket_types_read

List Intercom ticket types

List the ticket types a ticket can be created as.

read
list
connection_intercom_admins_read

Read Intercom teammates

Get the teammate the connection acts as (me), or list and get teammates (admins). Replies, assignments and notes take their ids.

read
melistget
connection_intercom_teams_read

List Intercom teams

List the teams of the workspace; assignments take their ids.

read
list
connection_intercom_segments_read

Read Intercom segments

List or get segments of contacts.

read
listget
connection_intercom_tags_read

Read Intercom tags

List or get tags; tagging takes their ids.

read
listget
connection_intercom_tags_write

Create tags and tag Intercom records

Create a tag (or rename one by its id), or apply a tag to a contact, company or conversation.

write
upserttag_contacttag_companytag_conversation
connection_intercom_tags_delete

Delete and remove Intercom tags

Permanently delete a tag, or remove a tag from a contact, company or conversation.

destructive
deleteuntag_contactuntag_companyuntag_conversation
connection_intercom_data_attributes_read

List Intercom data attributes

List the data attributes of contacts, companies or conversations, optionally of one model.

read
list
connection_intercom_data_attributes_write

Define Intercom data attributes

Create a custom data attribute on contacts, companies or conversations, or update its description, options or archived flag.

write
createupdate
connection_intercom_articles_read

Read Intercom Help Center articles

List or get Help Center articles, or search published articles by phrase (drafts are not searchable).

read
listgetsearch
connection_intercom_articles_write

Write Intercom Help Center articles

Create or update a Help Center article (draft or published, placed in a collection). A new article needs a title and a real teammate's admin id as author_id, and an Intercom plan with Articles.

write
createupdate
connection_intercom_articles_delete

Delete an Intercom Help Center article

Permanently delete an article.

destructive
delete
connection_intercom_collections_read

Read Intercom Help Center collections

List or get Help Center collections.

read
listget
connection_intercom_collections_write

Write Intercom Help Center collections

Create or update a Help Center collection; a new collection needs a name.

write
createupdate
connection_intercom_collections_delete

Delete an Intercom Help Center collection

Permanently delete a collection.

destructive
delete
connection_intercom_help_centers_read

Read Intercom help centers

List or get the help centers of the workspace.

read
listget
05// operations

All 64 operations

Each operation is a REST path under https://api.superagnt.com/v1/connections/intercom and an MCP tool. The per-operation tool name is the one permissions, approvals and usage records use.

OperationMCP tool
GET/contacts

List contacts

connection_intercom_list_contactsgrouped: connection_intercom_contacts_read, action list
POST/contacts

Create a contact

connection_intercom_create_contactgrouped: connection_intercom_contacts_write, action create
GET/contacts/{id}

Get a contact

connection_intercom_get_contactgrouped: connection_intercom_contacts_read, action get
PUT/contacts/{id}

Update a contact

connection_intercom_update_contactgrouped: connection_intercom_contacts_write, action update
DELETE/contacts/{id}

Delete a contact

connection_intercom_delete_contactgrouped: connection_intercom_contacts_delete, action delete
POST/contacts/search

Search contacts

connection_intercom_search_contactsgrouped: connection_intercom_contacts_read, action search
POST/contacts/merge

Merge a lead into a user

connection_intercom_merge_contactgrouped: connection_intercom_contacts_delete, action merge_lead
POST/contacts/{id}/archive

Archive a contact

connection_intercom_archive_contactgrouped: connection_intercom_contacts_delete, action archive
POST/contacts/{id}/unarchive

Unarchive a contact

connection_intercom_unarchive_contactgrouped: connection_intercom_contacts_write, action unarchive
GET/contacts/{id}/notes

List a contact's notes

connection_intercom_list_contact_notesgrouped: connection_intercom_contacts_read, action list_notes
POST/contacts/{id}/notes

Create a note on a contact

connection_intercom_create_contact_notegrouped: connection_intercom_contacts_write, action add_note
GET/companies

List companies

connection_intercom_list_companiesgrouped: connection_intercom_companies_read, action list
POST/companies

Create or update a company

connection_intercom_upsert_companygrouped: connection_intercom_companies_write, action upsert
GET/companies/{id}

Get a company

connection_intercom_get_companygrouped: connection_intercom_companies_read, action get
DELETE/companies/{id}

Delete a company

connection_intercom_delete_companygrouped: connection_intercom_companies_delete, action delete
GET/companies/{id}/contacts

List a company's contacts

connection_intercom_list_company_contactsgrouped: connection_intercom_companies_read, action list_contacts
GET/conversations

List conversations

connection_intercom_list_conversationsgrouped: connection_intercom_conversations_read, action list
POST/conversations

Create a conversation

connection_intercom_create_conversationgrouped: connection_intercom_conversations_write, action create
GET/conversations/{id}

Get a conversation

connection_intercom_get_conversationgrouped: connection_intercom_conversations_read, action get
POST/conversations/{id}/reply

Reply to a conversation

connection_intercom_reply_conversationgrouped: connection_intercom_conversations_send, action reply
POST/conversations/{id}/parts

Manage a conversation

connection_intercom_manage_conversationgrouped: connection_intercom_conversations_write, action manage
POST/conversations/search

Search conversations

connection_intercom_search_conversationsgrouped: connection_intercom_conversations_read, action search
POST/conversations/{id}/customers

Attach a contact to a conversation

connection_intercom_attach_contact_convogrouped: connection_intercom_conversations_write, action add_participant
DELETE/conversations/{id}/customers/{contact_id}

Detach a contact from a conversation

connection_intercom_detach_contact_convogrouped: connection_intercom_conversations_delete, action remove_participant
POST/conversations/{id}/run_assignment_rules

Run assignment rules on a conversation

connection_intercom_run_assignment_rulesgrouped: connection_intercom_conversations_write, action run_assignment_rules
POST/tickets

Create a ticket

connection_intercom_create_ticketgrouped: connection_intercom_tickets_write, action create
GET/tickets/{id}

Get a ticket

connection_intercom_get_ticketgrouped: connection_intercom_tickets_read, action get
PUT/tickets/{id}

Update a ticket

connection_intercom_update_ticketgrouped: connection_intercom_tickets_write, action update
POST/tickets/search

Search tickets

connection_intercom_search_ticketsgrouped: connection_intercom_tickets_read, action search
GET/tags

List tags

connection_intercom_list_tagsgrouped: connection_intercom_tags_read, action list
POST/tags

Create or update a tag

connection_intercom_upsert_taggrouped: connection_intercom_tags_write, action upsert
GET/tags/{id}

Get a tag

connection_intercom_get_taggrouped: connection_intercom_tags_read, action get
DELETE/tags/{id}

Delete a tag

connection_intercom_delete_taggrouped: connection_intercom_tags_delete, action delete
GET/admins

List admins

connection_intercom_list_adminsgrouped: connection_intercom_admins_read, action list
GET/admins/{id}

Get an admin

connection_intercom_get_admingrouped: connection_intercom_admins_read, action get
GET/me

Get the current admin

connection_intercom_get_current_admingrouped: connection_intercom_admins_read, action me
GET/data_attributes

List data attributes

connection_intercom_list_data_attributesgrouped: connection_intercom_data_attributes_read, action list
POST/data_attributes

Create a data attribute

connection_intercom_create_data_attributegrouped: connection_intercom_data_attributes_write, action create
PUT/data_attributes/{id}

Update a data attribute

connection_intercom_update_data_attributegrouped: connection_intercom_data_attributes_write, action update
GET/segments

List segments

connection_intercom_list_segmentsgrouped: connection_intercom_segments_read, action list
GET/segments/{id}

Get a segment

connection_intercom_get_segmentgrouped: connection_intercom_segments_read, action get
GET/articles

List articles

connection_intercom_list_articlesgrouped: connection_intercom_articles_read, action list
POST/articles

Create an article

connection_intercom_create_articlegrouped: connection_intercom_articles_write, action create
GET/articles/{id}

Get an article

connection_intercom_get_articlegrouped: connection_intercom_articles_read, action get
PUT/articles/{id}

Update an article

connection_intercom_update_articlegrouped: connection_intercom_articles_write, action update
DELETE/articles/{id}

Delete an article

connection_intercom_delete_articlegrouped: connection_intercom_articles_delete, action delete
GET/articles/search

Search articles

connection_intercom_search_articlesgrouped: connection_intercom_articles_read, action search
POST/contacts/{contact_id}/companies

Attach a contact to a company

connection_intercom_attach_contact_companygrouped: connection_intercom_contacts_write, action attach_company
DELETE/contacts/{contact_id}/companies/{company_id}

Detach a contact from a company

connection_intercom_detach_contact_companygrouped: connection_intercom_contacts_delete, action detach_company
GET/help_center/collections

List collections

connection_intercom_list_collectionsgrouped: connection_intercom_collections_read, action list
POST/help_center/collections

Create a collection

connection_intercom_create_collectiongrouped: connection_intercom_collections_write, action create
GET/help_center/collections/{id}

Get a collection

connection_intercom_get_collectiongrouped: connection_intercom_collections_read, action get
PUT/help_center/collections/{id}

Update a collection

connection_intercom_update_collectiongrouped: connection_intercom_collections_write, action update
DELETE/help_center/collections/{id}

Delete a collection

connection_intercom_delete_collectiongrouped: connection_intercom_collections_delete, action delete
GET/help_center/help_centers

List help centers

connection_intercom_list_help_centersgrouped: connection_intercom_help_centers_read, action list
GET/help_center/help_centers/{id}

Get a help center

connection_intercom_get_help_centergrouped: connection_intercom_help_centers_read, action get
POST/contacts/{contact_id}/tags

Tag a contact

connection_intercom_tag_contactgrouped: connection_intercom_tags_write, action tag_contact
POST/companies/{company_id}/tags

Tag a company

connection_intercom_tag_companygrouped: connection_intercom_tags_write, action tag_company
POST/conversations/{conversation_id}/tags

Tag a conversation

connection_intercom_tag_conversationgrouped: connection_intercom_tags_write, action tag_conversation
GET/ticket_types

List ticket types

connection_intercom_list_ticket_typesgrouped: connection_intercom_ticket_types_read, action list
GET/teams

List teams

connection_intercom_list_teamsgrouped: connection_intercom_teams_read, action list
DELETE/contacts/{contact_id}/tags/{tag_id}

Untag a contact

connection_intercom_untag_contactgrouped: connection_intercom_tags_delete, action untag_contact
DELETE/companies/{company_id}/tags/{tag_id}

Untag a company

connection_intercom_untag_companygrouped: connection_intercom_tags_delete, action untag_company
DELETE/conversations/{conversation_id}/tags/{tag_id}

Untag a conversation

connection_intercom_untag_conversationgrouped: connection_intercom_tags_delete, action untag_conversation