Commonroom MCP connector

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. Set up the connector

   Register your Commonroom MCP credentials with Scalekit so it handles the token lifecycle. You do this once per environment.

   Dashboard setup steps

   Commonroom MCP uses Dynamic Client Registration (DCR) — no client ID or secret is required. The only step is creating a connection in Scalekit and authorizing your Common Room account.

   1. Create a connection in Scalekit

      • In the Scalekit dashboard, go to AgentKit → Connections → Create Connection.
      • Search for Commonroom MCP and click Create.
      • Note the Connection name — use this as connection_name in your code (e.g., commonroommcp).

   2. Authorize your Common Room account

      Generate an authorization link and open it in a browser to complete the Common Room OAuth flow.

      The user is redirected to Common Room to sign in and grant access. Scalekit stores the token and injects it automatically into every tool call — no further configuration is needed.

      Common Room community required

      The user must have an active Common Room account with at least one community. Use get_catalog after connecting to discover the available object types in your community.

4. 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 = 'commonroommcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Commonroom 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: 'commonroommcp_commonroom_get_catalog',
     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 = "commonroommcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Commonroom MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="commonroommcp_commonroom_get_catalog",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Update commonroom — Update fields on an existing Common Room object (contact, organization, etc.) by its ID
• Feedback commonroom submit — Submit feedback on the quality of a query result — use after presenting data to the user
• List commonroom — List Common Room objects (contacts, organizations, segments, etc.) with optional pagination, filtering, and sorting
• Get commonroom — Retrieve the catalog of available object types, their properties, and allowed sort fields in Common Room
• Create commonroom — Create a new object in Common Room — contact, organization, activity, or custom object type

Common workflows

List community members

Use commonroommcp_commonroom_list_objects with objectType set to Contact to retrieve community members with optional filtering and pagination.

Node.js

const result = await actions.executeTool({
  connectionName: 'commonroommcp',
  identifier: 'user_123',
  toolName: 'commonroommcp_commonroom_list_objects',
  toolInput: {
    objectType: 'Contact',
    limit: 20,
  },
});
console.log(result);

Python

result = actions.execute_tool(
    connection_name="commonroommcp",
    identifier="user_123",
    tool_name="commonroommcp_commonroom_list_objects",
    tool_input={
        "objectType": "Contact",
        "limit": 20,
    },
)
print(result)

Create a contact

Use commonroommcp_commonroom_create_object to add a new contact to your Common Room community.

Node.js

const result = await actions.executeTool({
  connectionName: 'commonroommcp',
  identifier: 'user_123',
  toolName: 'commonroommcp_commonroom_create_object',
  toolInput: {
    objectType: 'Contact',
    email: 'alex@example.com',
    fullName: 'Alex Johnson',
    title: 'Senior Engineer',
    companyName: 'Example Corp',
  },
});
console.log(result);

Python

result = actions.execute_tool(
    connection_name="commonroommcp",
    identifier="user_123",
    tool_name="commonroommcp_commonroom_create_object",
    tool_input={
        "objectType": "Contact",
        "email": "alex@example.com",
        "fullName": "Alex Johnson",
        "title": "Senior Engineer",
        "companyName": "Example Corp",
    },
)
print(result)

Discover available object types

Use commonroommcp_commonroom_get_catalog to retrieve the full list of object types, their properties, and allowed sort fields before querying or creating objects.

Node.js

const catalog = await actions.executeTool({
  connectionName: 'commonroommcp',
  identifier: 'user_123',
  toolName: 'commonroommcp_commonroom_get_catalog',
  toolInput: {},
});
console.log(catalog);

Python

catalog = actions.execute_tool(
    connection_name="commonroommcp",
    identifier="user_123",
    tool_name="commonroommcp_commonroom_get_catalog",
    tool_input={},
)
print(catalog)

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.

commonroommcp_commonroom_create_object#Create a new object in Common Room — contact, organization, activity, or custom object type.24 params▾

Create a new object in Common Room — contact, organization, activity, or custom object type.

NameTypeRequiredDescription

objectTypestringrequiredThe Common Room object type to operate on. Use get_catalog to discover all available types.

activityBodystringoptionalBody text content of the activity being recorded.

activityTypestringoptionalActivity type identifier for this engagement signal. Use get_catalog with objectType=ActivityType to see all valid types.

communityIdstringoptionalID of the Common Room community to operate on.

companyDomainstringoptionalDomain of the company (e.g. acme.com). Used to link contacts to organizations.

companyNamestringoptionalName of the company the contact belongs to.

contactIdstringoptionalThe unique ID of an existing Contact in Common Room.

customFieldsarrayoptionalCustom field values to set on the object.

descriptionstringoptionalOptional description or notes about the object.

domainstringoptionalDomain of the organization (e.g. acme.com).

emailstringoptionalEmail address of the contact. Used as the unique identifier for Contact objects.

entityTypestringoptionalThe entity type associated with the activity.

fullNamestringoptionalFull name of the contact.

githubUsernamestringoptionalGitHub username of the contact.

linkedInUrlstringoptionalFull LinkedIn profile URL of the contact.

namestringoptionalName of the organization or custom object.

notestringoptionalA note to attach to this contact or organization.

occurredAtstringoptionalISO 8601 timestamp for when the activity occurred.

organizationIdstringoptionalThe unique ID of an existing Organization in Common Room.

prospectorCompanyIdstringoptionalThe Prospector company ID to associate with this record.

prospectorContactIdstringoptionalThe Prospector contact ID to associate with this record.

segmentIdstringoptionalThe ID of a Segment to assign this contact or organization to.

titlestringoptionalJob title of the contact.

twitterHandlestringoptionalTwitter/X handle of the contact (without @).

commonroommcp_commonroom_get_catalog#Retrieve the catalog of available object types, their properties, and allowed sort fields in Common Room.1 param▾

Retrieve the catalog of available object types, their properties, and allowed sort fields in Common Room.

NameTypeRequiredDescription

communityIdstringoptionalID of the Common Room community to operate on.

commonroommcp_commonroom_list_objects#List Common Room objects (contacts, organizations, segments, etc.) with optional pagination, filtering, and sorting.10 params▾

List Common Room objects (contacts, organizations, segments, etc.) with optional pagination, filtering, and sorting.

NameTypeRequiredDescription

objectTypestringrequiredThe Common Room object type to operate on. Use get_catalog to discover all available types.

communityIdstringoptionalID of the Common Room community to operate on.

cursorstringoptionalPagination cursor returned by a previous response.

directionstringoptionalSort direction for the results.

filterobjectoptionalFilter criteria as a JSON object to narrow results.

idstringoptionalThe unique ID of the object to retrieve.

limitintegeroptionalMaximum number of objects to return per page.

objectTypeIdstringoptionalThe ID of a custom object type to query.

propertiesarrayoptionalList of property names to include in the response.

sortstringoptionalField name to sort results by.

commonroommcp_commonroom_submit_feedback#Submit feedback on the quality of a query result — use after presenting data to the user.5 params▾

Submit feedback on the quality of a query result — use after presenting data to the user.

NameTypeRequiredDescription

ratingstringrequiredYour rating for the quality of the query result.

communityIdstringoptionalID of the Common Room community to operate on.

feedbackTextstringoptionalOptional text explaining your feedback.

objectTypestringoptionalThe Common Room object type to operate on. Use get_catalog to discover all available types.

queryDescriptionstringoptionalDescription of the query you are rating.

commonroommcp_commonroom_update_object#Update fields on an existing Common Room object (contact, organization, etc.) by its ID.16 params▾

Update fields on an existing Common Room object (contact, organization, etc.) by its ID.

NameTypeRequiredDescription

objectTypestringrequiredThe Common Room object type to operate on. Use get_catalog to discover all available types.

communityIdstringoptionalID of the Common Room community to operate on.

companyDomainstringoptionalDomain of the company (e.g. acme.com). Used to link contacts to organizations.

companyNamestringoptionalName of the company the contact belongs to.

contactIdstringoptionalThe unique ID of an existing Contact in Common Room.

customFieldsarrayoptionalCustom field values to set on the object.

emailstringoptionalEmail address of the contact. Used as the unique identifier for Contact objects.

fullNamestringoptionalFull name of the contact.

githubUsernamestringoptionalGitHub username of the contact.

linkedInUrlstringoptionalFull LinkedIn profile URL of the contact.

organizationIdstringoptionalThe unique ID of an existing Organization in Common Room.

prospectorCompanyIdstringoptionalThe Prospector company ID to associate with this record.

prospectorContactIdstringoptionalThe Prospector contact ID to associate with this record.

segmentIdstringoptionalThe ID of a Segment to assign this contact or organization to.

titlestringoptionalJob title of the contact.

twitterHandlestringoptionalTwitter/X handle of the contact (without @).