Getting started with Nutshell’s MCP server
The Nutshell MCP (Model Context Protocol) server connects your LLM (such as Claude or ChatGPT) to your Nutshell account. Your assistant can pull data from Nutshell to answer key questions about your CRM sales data, summarize information, and take action, like logging a note, creating a task, or updating a lead, so you can streamline your workflow and get more done.
Looking for an API key? You won’t need one here. The MCP server doesn’t use API keys. Your AI assistant connects by signing in to Nutshell and being granted permission.
For example, prompts like "Which sales rep had the most sales in September? What was their biggest sale?" and "Summarize our history with this Lead, then provide suggestions for the sales rep on what action to take next" can help your team quickly make data-driven decisions.
Where can I create and update records?
Claude: Search, view, create, and update all work when you connect using the steps below.
ChatGPT: Install the Nutshell CRM plugin from ChatGPT’s Plugins directory to search, view, create, and update records. You can also add the Nutshell MCP server manually.
GitHub Copilot, Microsoft Copilot Studio, and other approved assistants: See the list in the FAQs below.
Connect to Claude
Connect to Claude
Connecting to Claude is simple and gives you a direct way to interact with your Nutshell data using natural language.
Connecting through Claude requires a paid Claude account.
Step 1: Open Claude and access settings
In Claude Desktop or the Claude web app, open the sidebar and click on your avatar menu in the bottom left.
Navigate to Settings, then go to Connectors.
Step 2: Add the Nutshell connector
Click Add Custom Connector and enter the following:
Name: Nutshell
If the Nutshell connector doesn’t appear immediately, try restarting Claude Desktop and returning to the Connectors page.
Step 3: Log in and authorize
Click Connect. If you’re not logged in to Nutshell, you’ll be prompted to do so.
After logging in, take a quick look at the permissions on the consent page, then approve access. To let Claude create and update records as well as read them, make sure create and update access is included.
Step 4: Verify the connection
Use the Connections button in Claude to confirm that the Nutshell MCP server is enabled. Once verified, Claude is ready to interact with your data.
Step 5: Ask questions and explore your data
You’re all set! You can now ask Claude about leads, companies, activities, and more in Nutshell. You can also ask Claude to make updates, like adding a note or creating a task. Claude will automatically choose the right tools to find and summarize the information you need.
Connect to ChatGPT
Connect to ChatGPT
Connect Nutshell to ChatGPT to explore and update your Nutshell data using natural language.
Option 1: Install the Nutshell CRM plugin
Plugin availability depends on your ChatGPT plan and your workspace’s settings, and OpenAI may change it. If you don’t see Nutshell CRM, ask your workspace admin to check that plugins are turned on for you.
Step 1: Find Nutshell CRM
In ChatGPT on the web, open Plugins and search for Nutshell.
Step 2: Install the plugin
Click the + next to Nutshell CRM, or open it and click Install plugin.
Step 3: Log in and authorize
Sign in to Nutshell when prompted. Take a quick look at the permissions on the consent screen, then approve access. To let ChatGPT create and update records as well as read them, make sure create and update access is included.
Step 4: Ask questions and take action
Start a new chat, type @, and select Nutshell CRM. Then ask about your data or ask for updates. ChatGPT may ask you to confirm before it creates or updates a record. Please use a regular chat for this: ChatGPT’s agent mode doesn’t use custom apps, and deep research can only read.
Option 2: Add the MCP server manually
Use this option if you’d like to set up the connection for your workspace yourself.
Before you start: Creating and updating Nutshell records through a custom MCP server requires a ChatGPT Business, Enterprise, or Edu plan, on ChatGPT web. ChatGPT Pro can connect custom MCP servers for search and view only, and ChatGPT’s mobile apps aren’t supported. These requirements are set by OpenAI and may change; see OpenAI’s guide to custom MCP apps for the latest updates.
Who can set it up: On ChatGPT Business, only workspace admins and owners can create and publish custom MCP apps. On Enterprise and Edu, admins and owners can publish them, and admins can allow other members to create them. If you’re not an admin, no problem. Just ask yours to add Nutshell for you.
Step 1: Open Plugins
In ChatGPT on the web, open Plugins. In the top right of the Plugins page, click Add, then choose Add custom MCP server.
Step 2: Enter the connection details
Give it a name, such as Nutshell. Under Connection, enter the server URL https://app.nutshell.com/mcp. Set Authentication to OAuth, check the box acknowledging the warning, and click Create as a plugin.
Step 3: Log in and authorize
Sign in to Nutshell when prompted. On the consent screen, check that it includes wording similar to “Use app features on your behalf, such as creating, updating, or retrieving information.” If it only lists read-style access, the connection will stay read-only. When you’re happy with it, click Authorize.
Step 4: Ask questions and explore your data
After you authorize, ChatGPT opens your new Nutshell plugin page. Click Try in chat to start a chat with Nutshell ready to go, then ask about your data or ask it to make updates. You can also start any new chat, type @, and select the Nutshell plugin. ChatGPT may ask you to confirm before it creates or updates a record. Please use a regular chat for this: ChatGPT’s agent mode doesn’t use custom apps, and deep research can only read.
Menu names may differ slightly depending on your version of ChatGPT. If you connected before, disconnect first so ChatGPT asks you to authorize again. You only need one of these options. If you’ve set up both, you can remove either one.
Example MCP server prompts
So what can Nutshell's MCP server help you do with your Nutshell data? The following example prompts are a good starting place:
Show me contact information and a quick digest for my most recently created leads
Which leads should I reach out to first today?
Break down our sales by pipeline for this month
What was our biggest competitor that we lost to this month?
Out of all the lost leads this year, what % did we contact?
Which sales rep had the most sales in September? What was their biggest sale?
Tell me about our 10 most recent sales. How much revenue did each rep close?
How does lead volume look over the course of this year?
Log a note on [lead name] summarizing our call today
Create a task for me to follow up with [lead name] next Tuesday
Mark [lead name] as lost and note that we lost to [competitor]
Create a new lead for [company] and add [person] as the contact
FAQs
Can the MCP server make changes in my Nutshell account?
Yes! In addition to reading your data, the MCP server can create and update records when you ask it to: leads, companies, people, activities, notes, and tasks. It can also close leads as won, lost, or cancelled. Changes are made as the person who connected it, so your Nutshell role and permissions apply. The MCP server can’t delete records. Your assistant will typically confirm the details with you before it makes a change, but it’s always a good idea to review what it’s about to do before you approve it. Closing a lead changes its outcome, so take a moment to check it before you approve.
Does the MCP server respect my Nutshell permissions?
Yes. The MCP server acts as the person who connected it. Their sign-in is tied to their Nutshell user, so their role’s permissions apply. Whether your assistant can only read or can also create and update depends on the permission you approved when you signed in.
Lists, search, and reports follow the same rules as the Nutshell web app. “View own” and “view team” restrictions and pipeline visibility all apply, so a user who is restricted to their own records will only see their own records through MCP.
What can I do with the MCP server?
Nutshell’s MCP server can search and report on your data, and create and update records on your behalf. Here’s everything it can do with the right prompt:
Search and reporting:
Search leads: Find a lead or list of leads
Search Companies: Find an account or list of accounts
Search People: Find a person or list of people
Search Users: Find a user or list of users
Pipelines: View or list pipelines
Stages: View or list all pipeline stages
Outcomes: List your configured lead outcomes
Activity types: List available activity types
Channels and sources: List your sources / channels
Industries: List industry types
Markets, territories: View or list markets and territories
Tags: Get all tags used in the system
Products: View/list available products
Competitors: List competitors
Lead reports: Fetch summary or detailed lead reports
Timeline Information: Fetch timeline information for leads, companies, and people
Saved lists: Get user's or team's saved filters
Custom fields: View custom field values on a lead, company, or person
Create and update
Leads: Create or update a lead
People and companies: Create or update a person or company
Notes: Add a note to a lead, person, company, or activity
Activities: Create or update activities (meetings, calls, emails, etc.)
Tasks: Create or update tasks, including marking them complete
Close leads: Mark a lead won, lost, or cancelled
What can’t the MCP server do?
There are a few things the MCP server can’t do yet. It can’t create tags or apply tags to leads, create saved lead lists, share saved lists with other users, edit existing notes, or delete records.
The good news: you can build and share saved lists right in Nutshell. Filter your Leads list (for example, by assignee and open status), save it, then use Share to choose who can see it. See CRM Records: Working with lists of contacts and CRM Records: Filter your companies, people, and leads. If you need to create or apply tags in bulk, the Nutshell REST API can help, and API access is included on all plans. See API keys: Create API keys for 3rd-party apps and our developer documentation.
How do I troubleshoot connection issues between my AI assistant and Nutshell's MCP server?
This is almost always a quick fix. Here’s what to check, in order:
Check your ChatGPT plan. If you added Nutshell as a custom MCP server, creating and updating records requires ChatGPT Business, Enterprise, or Edu on the web. On ChatGPT Pro, a custom MCP connection is limited to search and view.
Check how you connected. If you can only see search and view tools, you may have installed the Nutshell CRM plugin before the write version was available. Disconnect it, then install it again and approve the new permissions. If that doesn’t help, you can add Nutshell manually (see option 2 above).
Ask your ChatGPT workspace admin. Ask them to check that Nutshell is set up for your workspace and that its create and update actions are turned on. If actions are missing, they can open the plugin’s Manage page and click Refresh tools. New actions are off by default.
Reconnect. If your assistant only shows search and view tools, your connection has read-only permission. Disconnect, then connect again and complete the sign-in, making sure create and update access is granted.
Use a regular chat. ChatGPT’s agent mode doesn’t use custom apps, and deep research can only read. If you need further assistance, contact the Nutshell Support team.
Why can my AI assistant read my Nutshell data but not create or update anything, or return a 403 Forbidden error?
Automated browsers, like the cloud browser ChatGPT’s agent mode uses, can’t open the Nutshell sign-in page. Sign in with your regular browser and connect through the MCP connector instead. The connector gives your assistant only the data you authorize.
Can I use MCP to automate lead assignment and follow-up tasks based on AI insights?
Your AI tool can analyze lead, sale, marketing, custom field, and website data, and it can take actions like creating follow-up tasks, logging notes and activities, and updating leads when you ask. It only acts when you prompt it.
Records created or updated through MCP are saved like any other change in Nutshell, so your existing automations can run on them. An automation only runs if its conditions match. Records created through MCP have the source “Nutshell MCP,” so an automation limited to a different source won’t run on them.
What's the difference between using MCP and Nutshell's API for AI integration?
MCP is purpose-built for AI conversations—it handles context, maintains session history, and translates natural language into actions. APIs require technical setup and coding for each integration. Think of MCP as plug-and-play for AI, while APIs offer more control but need developer resources. MCP connects through a sign-in with permissions you approve, while the API uses an API key.
Which AI assistants can I connect to the MCP server?
Nutshell’s MCP server works with a set of approved AI assistants. These are currently approved:
ChatGPT
Claude
Cursor (desktop app and website)
VS Code (including GitHub Copilot)
Grok
Microsoft Copilot Studio
Zendesk and RingCentral
Tools running on your own computer (
localhostand127.0.0.1)
Step-by-step setup guides are available above for Claude and ChatGPT. GitHub Copilot in VS Code and Microsoft Copilot Studio are also supported.
This list may change as we add more assistants. If you try a different assistant and see an “invalid_redirect_uri” error, it isn’t on the approved list yet. Contact our Support team to ask about it.
How much does the MCP server integration impact my Nutshell subscription costs?
Good news: MCP server integration is included with all Nutshell plans at no extra cost, including trials. You’ll only pay for your AI assistant subscription (for example, ChatGPT Business or Claude Pro). MCP actions don’t count toward your AI assists or AI outcomes, and there are no usage limits or hidden fees for MCP queries within Nutshell. That includes create and update actions.
Do I need to upgrade my Nutshell plan to use create and update actions?
No upgrade needed! MCP is available on every Nutshell plan, including Foundation and trials, for both search and create and update actions. Any requirements for creating and updating through ChatGPT come from your ChatGPT plan, not your Nutshell plan.
Can I create custom AI prompts and save them as templates for my team?
While Nutshell doesn't currently offer built-in prompt templates, you can standardize team prompts by documenting them in shared resources. Save effective queries like "Show this week's pipeline by stage" or "List stalled deals over 30 days" for consistent team usage across AI assistants.