---
canonical_url: "https://docs.composio.dev/toolkits/common_room_mcp"
markdown_url: "https://docs.composio.dev/toolkits/common_room_mcp.md"
product: "platform"
version: null
last_updated: null
---

# Common Room MCP

Common Room MCP connects agents to an authorized Common Room instance for catalog and go-to-market community intelligence workflows.

- **Category:** model context protocol
- **Auth:** DCR_OAUTH
- **Composio-managed OAuth available?** No
- **Tools:** 5
- **Triggers:** 0
- **Slug:** `COMMON_ROOM_MCP`
- **Version:** 20260910_00

## Tools

### Commonroom create object

**Slug:** `COMMON_ROOM_MCP_COMMONROOM_CREATE_OBJECT`

Writes a new contact, organization, segment, activity, note or tag to Common Room. Contacts and organizations are upserts, so this both creates and merges into an existing record; use commonroom_update_object instead when editing a record you have already identified. Look up the IDs and existing values it needs with commonroom_list_objects, and the writable fields for each type with commonroom_get_catalog.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Segment name (when objectType is "Segment"), organization name (when objectType is "Organization"), or tag name (when objectType is "Tag"). Required for "Segment" and "Tag". |
| `note` | string | No | Text content of the note. Required when objectType is "Note". |
| `email` | string | No | Email address, the strongest dedup key. Creating a Contact needs at least one identifier — email, githubUsername, twitterHandle, linkedInUrl or prospectorContactId; commonroom_get_catalog documents how each one deduplicates. |
| `title` | string | No | Job title |
| `domain` | string | No | Company domain, e.g. "acme.com". Required when objectType is "Organization" unless prospectorCompanyId is given. |
| `fullName` | string | No | Full name |
| `contactId` | string | No | Contact ID (c_-prefixed). Required when objectType is "Activity" or "Note" (provide exactly one of contactId or organizationId for Note). |
| `segmentId` | string | No | Segment ID to assign the new contact or organization to (e.g. s_123). The segment entity type must match the object being created. Use commonroom_list_objects with objectType "Segment" to find segment IDs. |
| `entityType` | string ("contact" | "organization" | "activity") | No | What the segment contains (when objectType is "Segment": "contact" or "organization", defaults to "contact"), or what the tag can be applied to (when objectType is "Tag", where it is required). |
| `objectType` | string ("Contact" | "Segment" | "Activity" | "Note" | "Organization" | "Tag") | Yes | The type of object to create. "Contact" and "Organization" upsert: a match on the identifiers given updates the existing record instead of adding one. "Segment" creates a static segment. "Tag" returns the existing tag when one of that name already covers the requested entity type, so retrying is safe. "Activity" and "Note" always add a new record. |
| `occurredAt` | string | No | ISO 8601 timestamp for when the activity happened, e.g. "2026-01-15T10:30:00Z". Defaults to now. |
| `communityId` | string | No | Optional community ID (com_-prefixed, e.g. "com_12345") to scope this request. Overrides the default community context. |
| `companyName` | string | No | Company name. Like "companyDomain", this resolves an organization and links the contact to it, creating one if no match exists — pass the domain too when you have it, so the match is not made on name alone. |
| `description` | string | No | Description of the segment or tag. |
| `linkedInUrl` | string | No | Full LinkedIn profile URL, e.g. "https://linkedin.com/in/jane-doe" |
| `tagIdsToAdd` | array | No | Tag IDs (l_-prefixed) to add. Existing tags are left alone. Use commonroom_list_objects with objectType "Tag" to find IDs, or create one first with objectType "Tag". |
| `activityBody` | string | No | Free-text content of the activity. Required when objectType is "Activity". |
| `activityType` | string ("UserInputAcceptedMeetingAdded" | "UserInputActivityFeatureIdeaAdded" | "UserInputAnsweredCallAdded" | "UserInputAnsweredFormSurveyAdded" | "UserInputAppliedChampionProgramAdded" | "UserInputArticleAdded" | "UserInputAttendedDemoAdded" | "UserInputAttendedGatheringAdded" | "UserInputAttendedMeetingAdded" | "UserInputAttendedProductDiscoveryCallAdded" | "UserInputAttendedRoadmapCallAdded" | "UserInputAttendedWebinarAdded" | "UserInputBookedMeetingAdded" | "UserInputCalledInAdded" | "UserInputCommentedRepliedAdded" | "UserInputCommentedTicketAdded" | "UserInputCompletedOnboardingAdded" | "UserInputCompletedTrainingAdded" | "UserInputCompletedTransactionAdded" | "UserInputCreatedAnAccountAdded" | "UserInputCreatedTicketAdded" | "UserInputCreatedTrainingMaterialAdded" | "UserInputDealClosedAdded" | "UserInputDealCreatedAdded" | "UserInputDeclinedRewardAdded" | "UserInputEligibleRewardAdded" | "UserInputEnrolledInChampionProgramAdded" | "UserInputEnrolledInTrainingAdded" | "UserInputGraduatedFromChampionProgramAdded" | "UserInputHostedGatheringAdded" | "UserInputHostedMeetingAdded" | "UserInputHostedWebinarAdded" | "UserInputIdentifiedPowerUserAdded" | "ApiUserImported" | "UserInputJoined" | "UserInputJoinedAdvisoryBoardAdded" | "UserInputJoinedGroupAdded" | "UserInputLikedReactedAdded" | "UserInputLinkAdded" | "UserInputLoggedInAdded" | "UserInputMadeCommitAdded" | "UserInputMadeMergeRequestAdded" | "UserInputMadePostTopicAdded" | "UserInputMadeReferralAdded" | "UserInputMergeRequestMerged" | "UserInputOtherAdded" | "UserInputParticipatedEarlyAccessProgramAdded" | "UserInputPresentedAtGatheringAdded" | "UserInputPresentedAtWebinarAdded" | "UserInputProvidedCaseStudyAdded" | "UserInputProvidedProductFeedbackAdded" | "UserInputReceivedAMessageAdded" | "UserInputReceivedCallNoAnswerAdded" | "UserInputReceivedEmailAdded" | "UserInputReceivedFormSurveyAdded" | "UserInputReceivedGiftAdded" | "UserInputReceivedLiMessageAdded" | "UserInputReceivedSmsAdded" | "UserInputReceivedTagBadgeAdded" | "UserInputReceivedWhatsappAdded" | "UserInputRedeemedRewardAdded" | "UserInputRegisteredForGatheringAdded" | "UserInputRegisteredForWebinarAdded" | "UserInputRegisteredSpeakerForGatheringAdded" | "UserInputRequestedDemoAdded" | "UserInputRequestedEarlyAccessProgramAdded" | "UserInputSentAMessageAdded" | "UserInputSentEmailAdded" | "UserInputSentGiftAdded" | "UserInputSentLiMessageAdded" | "UserInputSentSmsAdded" | "UserInputSentWhatsappAdded" | "UserInputSignedUpForProductAdded" | "UserInputSignedUpForTrialAdded" | "UserInputStartedGroupChatAdded" | "UserInputStartedSession" | "UserInputStartedTrainingAdded" | "UserInputStickerOrderAdded" | "UserInputStickerReceivedAdded" | "UserInputStickerRequestAdded" | "UserInputSubmittedFeatureRequestAdded" | "UserInputSubmittedFormAdded" | "UserInputSubmittedIdeaAdded" | "UserInputSubscribedNewsletterAdded" | "UserInputSwagOrderAdded" | "UserInputSwagReceivedAdded" | "UserInputSwagRequestAdded" | "UserInputTaggedInMediaAdded" | "UserInputUpdatedTicketAdded" | "UserInputUploadedPhotoAdded" | "UserInputUploadedVideoAdded" | "UserInputViewedPageAdded") | No | Kind of activity to record. Required when objectType is "Activity". Only the values in this enum are accepted; commonroom_list_objects with objectType "ActivityType" shows which kinds the community already records, but it also reports provider activity types that are not creatable here. |
| `customFields` | array | No | Custom fields to set on the contact or organization. Use commonroom_get_catalog and commonroom_list_objects with objectType "CustomField" to discover available fields and their cf_-prefixed IDs. |
| `companyDomain` | string | No | Organization domain to link the contact to (e.g. "acme.com"). Creates the org if it doesn't exist. |
| `twitterHandle` | string | No | Twitter/X handle, without the @ prefix |
| `githubUsername` | string | No | GitHub username, without the @ prefix |
| `organizationId` | string | No | Organization ID (o_-prefixed) to attach the note to. Required when objectType is "Note" and no contactId is given. |
| `prospectorCompanyId` | string | No | ID of a ProspectorCompany to create from. When provided, the API will auto-populate organization fields from the prospect company. |
| `prospectorContactId` | string | No | ID of a ProspectorContact to create from. When provided, the API will auto-populate contact fields from the prospect. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | ID of the created record, prefixed by type: s_ for a segment, l_ for a tag (pass it to "tagIdsToAdd" to apply the tag), o_ for an organization. |
| `name` | string | No | Name of the created record. |
| `contactId` | string | No | Contact the new record belongs to, or the upserted contact. |
| `organizationId` | string | No | Organization the new record belongs to, or the upserted organization. |

### Commonroom get catalog

**Slug:** `COMMON_ROOM_MCP_COMMONROOM_GET_CATALOG`

Reports which object types this workspace exposes and, for each, the fields it can be filtered by, the properties it can return, the fields it can be sorted by, and the other objects it is associated with. Call it before commonroom_list_objects, commonroom_create_object or commonroom_update_object: field names vary by workspace, so building a filter or a write from guessed names fails.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `communityId` | string | No | Optional community ID (com_-prefixed, e.g. "com_12345") to scope this request. Overrides the default community context. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `count` | integer | Yes | Number of object types returned. |
| `objects` | array | Yes | One entry per object type, carrying its filterable fields, allowed properties and sort fields. An entry may also carry an "assocs" array describing the objects it connects to: each assoc has "targetEntity" (display name), "targetObjectTypeId" (null for Contact and Organization, "cot_"-prefixed for a custom object), "objectAssocType" (e.g. "default" or a smart account link type), and sometimes a "description" saying when to use that link — for example current versus previous employment. Pass the chosen "objectAssocType" as a filter's targetAssocPaths to direct which association a cross-object filter traverses. |

### Commonroom list objects

**Slug:** `COMMON_ROOM_MCP_COMMONROOM_LIST_OBJECTS`

Reads Common Room records — contacts, organizations, activities, segments and custom objects — as a filtered, sorted, paginated list, or fetches one record by ID. Call commonroom_get_catalog first: it reports which object types exist and which fields each one can be filtered, sorted and returned by. Also use this tool to look up the values other filters expect, such as role names, Bombora topics and location IDs. Use commonroom_create_object or commonroom_update_object to write records; this tool only reads.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | Fetch one object by ID instead of listing; filter, sort, limit and cursor are then ignored. |
| `sort` | string | No | Field to sort results by, e.g. "member_count". Use commonroom_get_catalog to discover valid sort fields (allowedSorts) for each object type. |
| `limit` | integer | No | Number of records to return per page. Do not set above 50 unless the user explicitly requests more records. |
| `cursor` | string | No | Pagination cursor from a previous response's "nextCursor". Pass it to fetch the next page. |
| `filter` | object | No | Filter over the objectType's fields from commonroom_get_catalog. Nested groups: a group inside another group's "clauses" must carry "target", "objectConfigId" and "targetAssocPaths" — all three null for a plain same-object group. Cross-object: set "target" on a nested group to filter on a related type's fields, with objectConfigId and targetAssocPaths null. Legal targets: "Organization" and "Contact" either way; "Activity" on Contact; "ProspectorCompany" on ProspectorContact; "ProspectorContact" on ProspectorCompany; "JobOpening" and "NewsItem" on Organization. Clauses in one "JobOpening" or "NewsItem" group match the same posting or article, so keep conditions about a single posting in one group and split ones that may match different postings. Exact for jobOpeningStatus and jobOpeningSeniority, day-granular for jobOpeningFirstSeen; two title, keyword or location clauses can still be satisfied by two postings sharing those attributes, so query objectType "JobOpening" directly when that matters. Custom objects: target "Object" with the type's objectConfigId. Leave targetAssocPaths null to auto-resolve the path, including multi-hop through junction objects in the catalog "assocs"; set it only to choose among several advertised associations to one target. Teammates are in scope by default — never add a teammate filter to a plain list or count. Only for community-facing metrics such as sentiment or engagement, exclude them with a booleanFilter on activityIsTeamMember (Activity) or isTeamMember (Contact) set to false. Examples as <objectType>: <filter>. Contact: {"type":"and","clauses":[{"type":"booleanFilter","field":"memberHasEmail","params":{"op":"eq","value":true}},{"type":"or","target":null,"objectConfigId":null,"targetAssocPaths":null,"clauses":[{"type":"stringFilter","field":"title","params":{"op":"like","value":"Engineer"}},{"type":"stringFilter","field":"title","params":{"op":"like","value":"Manager"}}]}]} Contact: {"type":"and","clauses":[{"type":"and","target":"Organization","objectConfigId":null,"targetAssocPaths":null,"clauses":[{"type":"numberFilter","field":"groupRevenue","params":{"op":"gte","value":1000000}}]}]} Contact: {"type":"and","clauses":[{"type":"and","target":"Object","objectConfigId":"cot_5","targetAssocPaths":null,"clauses":[{"type":"and","target":"Object","objectConfigId":"cot_8","targetAssocPaths":null,"clauses":[{"type":"stringFilter","field":"objectName","params":{"op":"like","value":"Open"}}]}]}]} Organization: {"type":"and","clauses":[{"type":"and","target":"JobOpening","objectConfigId":null,"targetAssocPaths":null,"clauses":[{"type":"stringListFilter","field":"jobOpeningTitle","params":{"op":"any","value":["Account Executive"]}},{"type":"stringFilter","field":"jobOpeningStatus","params":{"op":"eq","value":"open"}}]}]} Contact: {"type":"and","clauses":[{"type":"webVisitPages","field":"memberWebVisitPagesViewed","params":{"op":"any","pages":[{"match":"contains","value":"/pricing"}],"interval":"P30D","minimumPageViews":null}}]} |
| `direction` | string ("asc" | "desc") | No | Sort order for "sort". Omitting it sorts ascending for most object types, but descending for JobOpening and NewsItem — pass it explicitly when the order matters. |
| `objectType` | string | Yes | Object type to query. Call commonroom_get_catalog to discover available types. Some types exist to look up values that filters on other types expect: "MemberRole" (set limit, e.g. 100) returns the community's commonest roles ranked by contact count, for memberRole; "BomboraTopic" the subscribed topic names, for surgingTopics; "Location" the loc_-prefixed IDs, for locationId. When the user says "account", prefer a custom object type named "Account" from commonroom_get_catalog over "Organization". |
| `properties` | array | No | Field names to return on each record, e.g. ["primaryEmail", "title"]. Use commonroom_get_catalog to discover valid names for the objectType. Omit for the default fields. Add "recordCount" only when a total was asked for — it costs an extra count query and returns the total in the response "total" field; drop it on follow-up pages. |
| `communityId` | string | No | Optional community ID (com_-prefixed, e.g. "com_12345") to scope this request. Overrides the default community context. |
| `objectTypeId` | string | No | Custom object type ID (cot_-prefixed, e.g. "cot_5") from commonroom_get_catalog. Required when objectType is "Object"; ignored otherwise. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `count` | integer | Yes |  |
| `total` | string | Yes |  |
| `records` | array | Yes |  |
| `has_more` | boolean | Yes |  |
| `nextCursor` | string | Yes |  |
| `objectType` | string | Yes |  |

### Commonroom submit feedback

**Slug:** `COMMON_ROOM_MCP_COMMONROOM_SUBMIT_FEEDBACK`

Records the user's verdict on results returned by a previous Common Room query. Call it after presenting data, when the user says the results were helpful, says they were wrong or incomplete, or comments on the data quality. It stores feedback only — it neither re-runs the query nor changes any record.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `rating` | string ("helpful" | "not_helpful") | Yes | Whether the results answered the user's question. Use "helpful" when the user confirms the data was what they wanted, "not_helpful" when they say it was wrong, incomplete or not what they asked for. |
| `objectType` | string | No | The objectType that was queried, e.g. "Contact" or "Organization". Send the same value passed to commonroom_list_objects so the feedback can be attributed to that query. |
| `communityId` | string | No | Optional community ID (com_-prefixed, e.g. "com_12345") to scope this request. Overrides the default community context. |
| `feedbackText` | string | No | Verbatim explanation from the user about what was wrong or useful. Leave unset when the user gave no reason beyond the rating. |
| `queryDescription` | string | No | What the user was originally looking for, in their own words where possible. Provides the intent the returned records are being judged against. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `success` | boolean | Yes | True when the feedback was recorded. |

### Commonroom update object

**Slug:** `COMMON_ROOM_MCP_COMMONROOM_UPDATE_OBJECT`

Edits an existing contact, organization, custom-object record or segment, identified by its ID. Every change is a partial update: omitted fields keep their current values and tag changes apply only to the tags listed. Use commonroom_create_object when the record may not exist yet, since that upserts contacts and organizations; use commonroom_list_objects to find the ID to pass here and commonroom_get_catalog for which fields are mutable.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | The new name. Mutable for Organization and Segment; required when objectType is "Segment". See commonroom_get_catalog for mutable fields. |
| `email` | string | No | Email address |
| `title` | string | No | Job title |
| `fullName` | string | No | Full name |
| `objectId` | string | No | Custom-object record ID (co_-prefixed). Required when objectType is "Object". Use commonroom_list_objects to find it. |
| `contactId` | string | No | Contact ID (c_-prefixed) of the contact to update. Required when objectType is "Contact". |
| `segmentId` | string | No | For Contact or Organization, the segment ID to add the record to. For Segment, the ID of the segment to rename — required when objectType is "Segment". |
| `objectType` | string ("Contact" | "Organization" | "Segment" | "Object") | Yes | The type of object to update. "Segment" renames the segment only, preserving its entity type and memberships. "Object" edits a custom-object record and needs "customFields". Unlike commonroom_create_object, no type accepts the prospectorContactId or prospectorCompanyId creation shortcuts. |
| `communityId` | string | No | Optional community ID (com_-prefixed, e.g. "com_12345") to scope this request. Overrides the default community context. |
| `companyName` | string | No | Company name. Like "companyDomain", this resolves an organization and links the contact to it, creating one if no match exists — pass the domain too when you have it, so the match is not made on name alone. |
| `linkedInUrl` | string | No | Full LinkedIn profile URL, e.g. "https://linkedin.com/in/jane-doe" |
| `tagIdsToAdd` | array | No | Tag IDs (l_-prefixed) to add. Existing tags are left alone. Use commonroom_list_objects with objectType "Tag" to find IDs, or create one first with objectType "Tag". |
| `customFields` | array | No | Custom fields to set on the contact, organization, or custom object. Required when objectType is "Object". Use commonroom_get_catalog and commonroom_list_objects with objectType "CustomField" to discover available fields and their cf_-prefixed IDs. |
| `companyDomain` | string | No | Organization domain to link the contact to (e.g. "acme.com"). Creates the org if it doesn't exist. |
| `twitterHandle` | string | No | Twitter/X handle, without the @ prefix |
| `githubUsername` | string | No | GitHub username, without the @ prefix |
| `organizationId` | string | No | Organization ID (o_-prefixed) of the organization to update. Required when objectType is "Organization". |
| `tagIdsToRemove` | array | No | Tag IDs (l_-prefixed) to remove. Tags not listed here are left alone. An ID must not appear in both "tagIdsToAdd" and "tagIdsToRemove". |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | ID of the updated record. |