Documentation

Bonsai MCP server

The Bonsai MCP server connects your Bonsai account to AI clients that support the Model Context Protocol, including Claude, Cursor, Codex, and n8n. Once connected, your assistant can read and act on your Bonsai data in plain language. It can pull your tasks, summarize a project, create tasks from meeting notes, and update your deal pipeline, all without leaving the conversation.

The server is live in beta at https://mcp.hellobonsai.com/mcp. It is the only way to build on Bonsai today.

On this page: why use it · what you can do · how it works · connecting · tool reference · example prompts · authentication · security · rate limits

Why use it

  • Versus the app. Say what you want instead of clicking through screens. Your assistant can pull context and take action across tasks, projects, deals, and CRM in one conversation.
  • Versus Zapier or fixed automations. There are no rigid trigger-and-action rules. The assistant works out what to do from what you ask, and can chain steps across different parts of Bonsai.
  • It respects your permissions. The server only exposes what your account can already access. It can never do more in Bonsai than you can.

What you can do today

The server exposes 16 tools across these groups:

  • Tasks. Read and create tasks.
  • Projects. List and create projects.
  • Team. Look up team members and their workload.
  • Deals. List, create, and update deals, and browse your pipeline stages.
  • Contacts and companies. List, create, and update your CRM records.

More tools are planned for later milestones, including invoices, payments, time entries, and reports. The full list is in the tool reference below.

How it works

Your AI client talks to the Bonsai MCP server, which passes requests to Bonsai and returns your data.

┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐     ┌──────────────┐
│   AI client     │────▶│  Bonsai MCP      │────▶│   Bonsai    │────▶│  Your Bonsai │
│ (Claude, Cursor,│◀────│  server          │◀────│             │◀────│  data        │
│  Codex, …)      │     │  (stateless)     │     │             │     │              │
└─────────────────┘     └──────────────────┘     └─────────────┘     └──────────────┘

The server is a stateless relay. Your AI client handles the OAuth login directly with Bonsai, so the server never stores your credentials. When you connect, it checks your permissions and only shows the tools you are allowed to use.

For the full login flow, see authentication and permissions.

Connecting

Connect the Bonsai MCP server to your AI client and you can manage your Bonsai data in conversation. Most clients are working in three steps: install the server, log in, and run a first prompt.

Beta access

Pick your client below.

Claude / Claude Code

1. Add the server.

claude mcp add bonsai --transport http https://mcp.hellobonsai.com/mcp

2. Log in. The first time Claude calls the server, it opens a browser window to log in to Bonsai. There are no API keys to copy. Approve the access and you are connected.

3. Try it. Ask:

Show me my tasks for today and anything overdue.

To remove the server later, run claude mcp remove bonsai.

Cursor

1. Add the server. Open your mcp.json and add the Bonsai entry:

{
  "mcpServers": {
    "bonsai": { "url": "https://mcp.hellobonsai.com/mcp" }
  }
}

2. Log in. Cursor prompts you to authenticate the first time it reaches the server. Complete the Bonsai login in your browser to connect.

3. Try it. Ask:

Give me an overview of the Acme project: what's done, what's active, and what's due this week.

Codex

1. Add the server and log in.

codex mcp add bonsai --url https://mcp.hellobonsai.com/mcp
codex mcp login bonsai

The login command opens a browser window to authenticate with Bonsai.

2. Try it. Ask:

Create a high-priority task "Send revised SOW to client" for me, due tomorrow.

Other clients

Any client that supports remote MCP servers over HTTP can connect. Point it at:

https://mcp.hellobonsai.com/mcp

The server uses OAuth, so your client needs to support an OAuth login flow for MCP. On first use it sends you to Bonsai to log in and approve access. After that, your assistant can call any tool your account has permission for. See authentication and permissions for the full flow.

Tool reference

These are the tools the Bonsai MCP server exposes today, grouped by what they work with. You never call them by name. Your AI client picks the right tool from what you ask, so the example prompts show the kind of request that triggers each one.

You only see the tools your Bonsai permissions allow, so your list may be shorter than what's below.

Parameter-level detail (every field, type, and filter) will live in the REST API reference once the public API ships. This page is the working list of capabilities.

Tasks

Tool What it does Example prompt
list_tasks List tasks, with filters for assignee, status, due date, priority, project, and tag "Show me my tasks due today and anything overdue."
get_task Fetch one task by its ID "Pull up the full details of that task."
create_task Create a task with a title, project, assignee, priority, and due date "Create a high-priority task 'Send revised SOW' for me, due tomorrow."

Projects

Tool What it does Example prompt
list_projects List active projects, with a title search "Which projects do I have running right now?"
create_project Create a project for a company, with its billing setup "Start a fixed-fee project 'Website Redesign' for Acme at $5,000."

Team

Tool What it does Example prompt
list_team_members List the people in your company, with their roles "Who's on my team, and how many open tasks does each person have?"

Deals and pipeline

Tool What it does Example prompt
list_deals List deals, with filters for title, number, and assignee "What deals are open and who owns each one?"
create_deal Create a deal for a company, with a value and pipeline stage "Add a new deal 'Acme retainer' worth $12,000 to my pipeline."
update_deal Update a deal's value, stage, owner, probability, or close date "Move the Acme deal to Proposal Sent and set it to 60%."
list_board_groups List your pipeline stages and project groups "What stages does my deal pipeline have?"

Contacts and companies

Tool What it does Example prompt
list_contacts List CRM contacts, with name, email, and company filters "Find the contact for Alex at BrightTech."
create_contact Create a contact, optionally linked to a company "Add Alex Rivera, alex@brighttech.com, as a contact at BrightTech."
update_contact Update a contact's name, email, job title, or phone "Update Alex's job title to VP of Marketing."
list_companies List CRM companies, with a name search "Do we already have BrightTech in our CRM?"
create_company Create a company, with domains and a primary contact "Create a company BrightTech with the domain brighttech.com."
update_company Update a company's name, domains, or primary contact "Add the domain brighttech.io to BrightTech."

Invoices, payments, time entries, and reports are planned for upcoming milestones and will appear here when they ship.

Example prompts

A starting point if you're staring at a blank chat. These are grouped by what you're trying to get done. Swap in your own project, client, and people names. Your assistant works out which tools to use, so you can phrase things however feels natural.

Morning digest

  1. "Show me my tasks for today and anything overdue this week."
  2. "Build me a morning digest of my open tasks, grouped by project, with urgent and high-priority items at the top."
  3. "Summarize everything I owe today, with the project and due date for each task."

Task creation

  1. "Create a high-priority task 'Send revised SOW to client' for me, due tomorrow."
  2. "From the action items above, create one task per item under the Acme Website project and assign each to the right person."
  3. "Capture the action items from this meeting transcript as tasks in the right project, and confirm each one with me before creating it."

Project status

  1. "Give me an overview of the Acme project: how many tasks are done, who's active, and what's due this week."
  2. "Summarize Project Apollo for a client update email."
  3. "Group every task in the Acme Website project by status and tell me who owns each one."

Pipeline and deals

  1. "What deals are open right now, and who owns each one?"
  2. "Add a new deal 'Acme retainer' worth $12,000 to my pipeline."
  3. "Move the BrightTech deal to Proposal Sent and set the probability to 60%."

Post-meeting CRM

  1. "Create a contact for Alex Rivera, alex@brighttech.com, at BrightTech."
  2. "Do we already have BrightTech in the CRM? If not, create it with the domain brighttech.com."
  3. "From this call, create the company and its main contact, then add a follow-up task to send a proposal."

Authentication and permissions

The MCP server uses OAuth. There are no API keys to create, copy, or paste. Your AI client handles the login for you, and the server only ever acts as you, within your existing Bonsai permissions.

How login works

Bonsai's authorization server runs OAuth 2.1 with the authorization code flow and PKCE. In practice:

  1. The first time your client calls the server, it sends you to Bonsai to log in.
  2. You approve access in the browser. Bonsai hands your client a token; the MCP server never sees your password.
  3. Your client uses that token on every call. The MCP server passes it straight through to Bonsai and never stores it.

Most clients register themselves automatically the first time you connect (Bonsai supports dynamic client registration), which is why the setup is just one command or a small config snippet with no developer portal step.

Access tokens are short-lived (15 minutes) and your client refreshes them in the background, so you stay connected without logging in again each time.

What it can access

There are no scopes to pick. The token inherits your role in the company you logged into, and every call is checked against your Bonsai permissions on the server. The MCP can never do more than you can do in the app. If your role can't create deals, neither can your assistant, and the tool simply won't appear for you.

When you connect, the server reads your permissions once and only shows the tools you're allowed to use. Every tool call is also re-checked at request time, so a tool you aren't permitted to use returns a permission error rather than acting.

Checking what you can access

Your access through the MCP mirrors your role in Bonsai, so the tools you see match what you can already do in the app. To review or change what you can do, open your role and permission settings in your Bonsai account, or ask your company owner or admin.

Disconnecting

To stop the connection, remove the Bonsai server from your AI client (for example, claude mcp remove bonsai). That stops it from making any further calls on your behalf. Your client can also revoke its token through Bonsai's OAuth revocation endpoint.

Security best practices

The MCP server acts as you. It can read and change your Bonsai data on your behalf, so a few habits keep that safe:

  • Connect only AI clients you trust. Treat the MCP like any app you would grant access to your account, and add it only in clients you know and control.
  • Your data goes to your AI provider. When you use the MCP, the Bonsai data you ask about is sent to whichever AI client and model you have chosen. Review that provider's data handling before connecting a sensitive account.
  • Access follows your Bonsai role. The server can never do more than your account can. If you want to limit what is reachable, connect from an account with the right permission level rather than an owner account.
  • Review actions before confirming, especially writes. Creating and updating tasks, deals, contacts, and companies changes real data. Ask your assistant to confirm before it creates or edits anything, and check the result.
  • Mind shared environments. In a shared or team AI workspace, your conversation history, and the Bonsai data in it, may be visible to others.
  • Disconnect when you're done. If you no longer need the connection, remove the server from your client. See disconnecting.

Rate limits

Bonsai allows up to 10,000 requests every 10 minutes per IP address. Normal use through an AI assistant stays well within this, so you shouldn't run into the limit in everyday work. If a burst of automated activity gets throttled, ease off for a moment and try again.