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

What you can do

Connect this agent connector to let your agent:

• Create company, contact, invoice — Create a CRM company in the user’s Bonsai account
• Get task — Fetch a single task from Bonsai by its UUID
• List board groups, companies, contacts — List board groups (pipeline stages for deals, project groups for projects) in the user’s Bonsai company
• Update company, contact — Update an existing CRM company in Bonsai

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.

bonsaimcp_create_company#Create a CRM company in the user's Bonsai account. Requires name. Optionally set a default contact and domains. Search with list_companies first to avoid duplicates.3 params▾

Create a CRM company in the user's Bonsai account. Requires name. Optionally set a default contact and domains. Search with list_companies first to avoid duplicates.

NameTypeRequiredDescription

namestringrequiredThe name of the company to create.

default_contact_idintegeroptionalOptional ID of the default contact for this company.

domainsarrayoptionalOptional list of email domains associated with this company.

bonsaimcp_create_contact#Create a CRM contact in the user's Bonsai account. Requires name and email. Optionally link to a company_id. Search with list_contacts first to avoid duplicates.5 params▾

Create a CRM contact in the user's Bonsai account. Requires name and email. Optionally link to a company_id. Search with list_contacts first to avoid duplicates.

NameTypeRequiredDescription

emailstringrequiredEmail address of the contact.

namestringrequiredFull name of the contact.

company_idintegeroptionalOptional ID of the company to link this contact to.

job_titlestringoptionalOptional job title of the contact.

phone_numberstringoptionalOptional phone number of the contact.

bonsaimcp_create_invoice#Create a one-time invoice in Bonsai. Requires company_id (client company), contact_id (billing contact), and project_id. Optional currency, title, due terms, and invoice_items array (each with name, amount, rate).8 params▾

Create a one-time invoice in Bonsai. Requires company_id (client company), contact_id (billing contact), and project_id. Optional currency, title, due terms, and invoice_items array (each with name, amount, rate).

NameTypeRequiredDescription

company_idintegerrequiredID of the client company to invoice.

contact_idintegerrequiredID of the billing contact for this invoice.

project_idintegerrequiredID of the project this invoice is for.

currencystringoptionalISO 4217 currency code for the invoice.

duestringoptionalDue terms for the invoice.

due_datestringoptionalPayment due date in YYYY-MM-DD format. Required when due is 'custom'.

invoice_itemsarrayoptionalOptional array of line items to add to the invoice.

titlestringoptionalOptional title for the invoice.

bonsaimcp_create_invoice_item#Add a line item to an existing Bonsai invoice. Requires invoice_id, name, amount, and rate (decimal strings). Optional description and unit_type.6 params▾

Add a line item to an existing Bonsai invoice. Requires invoice_id, name, amount, and rate (decimal strings). Optional description and unit_type.

NameTypeRequiredDescription

amountstringrequiredQuantity or amount for this line item as a decimal string.

invoice_idintegerrequiredID of the invoice to add the line item to.

namestringrequiredName or label for the invoice line item.

ratestringrequiredRate per unit for this line item as a decimal string.

descriptionstringoptionalOptional longer description for the line item.

unit_typestringoptionalOptional unit type for the line item.

bonsaimcp_create_project#Create a project for an existing client company in Bonsai. Requires title, company_id (resolve via list_companies), and billing_type (time/fixed_fee/retainer/not_billable). billing_fee required for fixed_fee/retainer; billing_cycle required for retainer.7 params▾

Create a project for an existing client company in Bonsai. Requires title, company_id (resolve via list_companies), and billing_type (time/fixed_fee/retainer/not_billable). billing_fee required for fixed_fee/retainer; billing_cycle required for retainer.

NameTypeRequiredDescription

billing_typestringrequiredBilling type for the project.

company_idintegerrequiredThe ID of the client company this project belongs to.

titlestringrequiredThe title of the project to create.

billing_cyclestringoptionalBilling cycle for retainer projects. Required when billing_type is retainer.

billing_feestringoptionalBilling fee as a decimal string. Required for fixed_fee and retainer billing types.

currencystringoptionalISO 4217 currency code for the project, e.g. USD.

start_datestringoptionalProject start date in YYYY-MM-DD format.

bonsaimcp_create_task#Create a task in the user's Bonsai company. Supports title (required), optional project_id, assignee_member_id (company member id or 'me'), priority (urgent/high/medium/low), and due_date (YYYY-MM-DD).5 params▾

Create a task in the user's Bonsai company. Supports title (required), optional project_id, assignee_member_id (company member id or 'me'), priority (urgent/high/medium/low), and due_date (YYYY-MM-DD).

NameTypeRequiredDescription

titlestringrequiredThe title of the task to create.

assignee_member_idstringoptionalCompany member ID to assign the task to, or 'me' for the authenticated user.

due_datestringoptionalDue date for the task in YYYY-MM-DD format.

prioritystringoptionalPriority level for the task.

project_idintegeroptionalOptional ID of the project to associate this task with.

bonsaimcp_create_time_entry#Log a time entry in the user's Bonsai company. Requires seconds (duration) and date (YYYY-MM-DD). Optionally attach to a project_id or task_uuid. Each call creates a new entry.8 params▾

Log a time entry in the user's Bonsai company. Requires seconds (duration) and date (YYYY-MM-DD). Optionally attach to a project_id or task_uuid. Each call creates a new entry.

NameTypeRequiredDescription

datestringrequiredDate of the time entry in YYYY-MM-DD format.

secondsintegerrequiredDuration of the time entry in seconds.

non_billablebooleanoptionalIf true, marks this time entry as non-billable.

notesstringoptionalOptional notes or description for the time entry.

owner_member_idstringoptionalCompany member ID who owns this time entry, or 'me' for the authenticated user.

project_idintegeroptionalOptional project ID to associate this time entry with.

ratestringoptionalOptional billing rate for this time entry as a decimal string.

task_uuidstringoptionalOptional UUID of the task to associate this time entry with.

bonsaimcp_get_task#Fetch a single task from Bonsai by its UUID.1 param▾

Fetch a single task from Bonsai by its UUID.

NameTypeRequiredDescription

uuidstringrequiredUUID of the task to fetch.

bonsaimcp_list_board_groups#List board groups (pipeline stages for deals, project groups for projects) in the user's Bonsai company. Use to resolve group names to UUIDs for filtering deals and projects.4 params▾

List board groups (pipeline stages for deals, project groups for projects) in the user's Bonsai company. Use to resolve group names to UUIDs for filtering deals and projects.

NameTypeRequiredDescription

namestringoptionalSubstring match on board group name.

pageintegeroptionalPage number to retrieve (1-based).

page_sizeintegeroptionalNumber of board groups per page. Maximum 100.

resource_typestringoptionalFilter by resource type: Deal (pipeline stages) or Project (project groups).

bonsaimcp_list_companies#List CRM companies in the user's Bonsai account. Use to find existing companies before creating new ones or when resolving company_id for projects and invoices.3 params▾

List CRM companies in the user's Bonsai account. Use to find existing companies before creating new ones or when resolving company_id for projects and invoices.

NameTypeRequiredDescription

namestringoptionalFree-text search on company name.

pageintegeroptionalPage number to retrieve (1-based).

page_sizeintegeroptionalNumber of companies per page. Maximum 100.

bonsaimcp_list_contacts#List CRM contacts in the user's Bonsai account. Supports filtering by name, email, and company.5 params▾

List CRM contacts in the user's Bonsai account. Supports filtering by name, email, and company.

NameTypeRequiredDescription

company_idintegeroptionalFilter contacts by company ID.

emailstringoptionalFree-text search on contact email address.

namestringoptionalFree-text search on contact name.

pageintegeroptionalPage number to retrieve (1-based).

page_sizeintegeroptionalNumber of contacts per page. Maximum 100.

bonsaimcp_list_deals#List deals in the user's Bonsai company, paginated. Each deal includes id, title, deal_value, currency, probability, close_date, status, pipeline stage, and assignee info.6 params▾

List deals in the user's Bonsai company, paginated. Each deal includes id, title, deal_value, currency, probability, close_date, status, pipeline stage, and assignee info.

NameTypeRequiredDescription

assignee_member_idstringoptionalFilter by assignee company member ID (as a string) or the literal value "me".

board_group_idstringoptionalUUID of the pipeline stage to filter deals by.

deal_numberstringoptionalFree-text search on deal number.

pageintegeroptionalPage number to retrieve (1-based).

page_sizeintegeroptionalNumber of deals per page. Maximum 100.

titlestringoptionalFree-text search on deal title.

bonsaimcp_list_invoices#List invoices in the user's Bonsai company, newest first. Each invoice includes invoice_number, title, status, total_amount, due_date, client info, and line items.5 params▾

List invoices in the user's Bonsai company, newest first. Each invoice includes invoice_number, title, status, total_amount, due_date, client info, and line items.

NameTypeRequiredDescription

company_idintegeroptionalFilter invoices by client company ID.

invoice_numberstringoptionalExact invoice number lookup.

pageintegeroptionalPage number to retrieve (1-based).

page_sizeintegeroptionalNumber of invoices per page. Maximum 100.

project_idintegeroptionalFilter invoices by project ID.

bonsaimcp_list_projects#List active projects in the user's Bonsai company, paginated. Supports filtering by title (free-text), public_url_token, and board_group_id (Project Group UUID).5 params▾

List active projects in the user's Bonsai company, paginated. Supports filtering by title (free-text), public_url_token, and board_group_id (Project Group UUID).

NameTypeRequiredDescription

board_group_idstringoptionalUUID of the Project Group to filter by.

pageintegeroptionalPage number to retrieve (1-based).

page_sizeintegeroptionalNumber of projects per page. Maximum 100.

public_url_tokenstringoptionalExact public URL token lookup for a project.

titlestringoptionalFree-text search on project title.

bonsaimcp_list_tasks#List tasks in the user's current Bonsai company, paginated and ordered by creation date (newest first). Supports filtering by assignee, scope, due-date window, priority, project, and tag.10 params▾

List tasks in the user's current Bonsai company, paginated and ordered by creation date (newest first). Supports filtering by assignee, scope, due-date window, priority, project, and tag.

NameTypeRequiredDescription

assignee_idstringoptionalFilter by assignee. Pass an integer user ID as a string or the literal value "me" to filter by the current user.

duestringoptionalFilter by a named due-date window. Mutually exclusive with due_from/due_to.

due_fromstringoptionalFilter tasks due on or after this date (YYYY-MM-DD). Mutually exclusive with due.

due_tostringoptionalFilter tasks due on or before this date (YYYY-MM-DD). Mutually exclusive with due.

pageintegeroptionalPage number to retrieve (1-based).

page_sizeintegeroptionalNumber of tasks per page. Maximum 100.

prioritystringoptionalFilter by task priority.

project_idintegeroptionalFilter tasks by project ID.

scopestringoptionalScope of tasks to return.

tag_idintegeroptionalFilter tasks by tag ID.

bonsaimcp_list_team_members#List team members in the user's current Bonsai company. Returns company_member_id (for task assignment), role, permission_profile, and lifecycle timestamps.3 params▾

List team members in the user's current Bonsai company. Returns company_member_id (for task assignment), role, permission_profile, and lifecycle timestamps.

NameTypeRequiredDescription

namestringoptionalFree-text search on team member name.

pageintegeroptionalPage number to retrieve (1-based).

page_sizeintegeroptionalNumber of team members per page. Maximum 100.

bonsaimcp_update_company#Update an existing CRM company in Bonsai. Requires id (resolve via list_companies). All other fields optional — only supplied fields are changed. Passing domains=[] removes all domains.4 params▾

Update an existing CRM company in Bonsai. Requires id (resolve via list_companies). All other fields optional — only supplied fields are changed. Passing domains=[] removes all domains.

NameTypeRequiredDescription

idintegerrequiredID of the company to update.

default_contact_idintegeroptionalUpdated default contact ID for the company.

domainsarrayoptionalUpdated list of domains for the company. Pass an empty array to remove all domains.

namestringoptionalUpdated name for the company.

bonsaimcp_update_contact#Update an existing CRM contact in Bonsai. Requires id (resolve via list_contacts). All other fields optional. Pass null for job_title or phone_number to clear them.5 params▾

Update an existing CRM contact in Bonsai. Requires id (resolve via list_contacts). All other fields optional. Pass null for job_title or phone_number to clear them.

NameTypeRequiredDescription

idintegerrequiredID of the contact to update.

emailstringoptionalUpdated email address for the contact.

job_titlestringoptionalUpdated job title for the contact. Pass null to clear.

namestringoptionalUpdated full name for the contact.

phone_numberstringoptionalUpdated phone number for the contact. Pass null to clear.