> For the complete documentation index, see [llms.txt](https://docs.sumble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sumble.com/api/mcp.md). # MCP With Sumble MCP, you can ask questions in natural language and get back structured data about organizations, technologies, job postings, and people - directly inside tools like Claude Desktop, Cursor, ChatGpt, or Gemini CLI. Behind the scenes, your AI assistant calls Sumble's API on your behalf. ## Getting started Sumble is now listed in the [Claude](https://claude.ai/directory/connectors/sumble) and [ChatGPT](https://chatgpt.com/apps/sumble/asdk_app_69d6aed609708191a384fb6b59438690) app directories, so you can install it with one click on those platforms. See this video to see how to find it in Claude {% embed url="" %} ## Compatibility On Claude and ChatGPT you can install Sumble directly from the app directory. Cursor, Claude Code, and Gemini CLI use a custom MCP connection. It is possible in these LLMs | Platform | Base Availability | How to install | Enterprise Requirements | | -------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | Claude | Paid plans only | [Claude directory](https://claude.ai/directory/connectors/sumble) or custom connector — see [Claude setup](/api/mcp/mcp-claude.md) | Admin must enable connectors (Team/Enterprise) | | Cursor | All plans | Custom MCP connection — see [Cursor setup](/api/mcp/mcp-cursor.md) | None (Available on all) | | ChatGPT | Paid plans only | [ChatGPT directory](https://chatgpt.com/apps/sumble/asdk_app_69d6aed609708191a384fb6b59438690) or custom app — see [ChatGPT setup](/api/mcp/mcp-chatgpt.md) | None (Available on all) | | Gemini | Gemini CLI, Gemini Enterprise (beta) | Custom MCP connection — see [Gemini CLI setup](/api/mcp/mcp-gemini-cli.md) or [Gemini Enterprise setup](/api/mcp/mcp-gemini-enterprise.md) | Gemini Enterprise: beta, enabled per account on request | {% hint style="info" %} *Gemini support means the **Gemini CLI**, plus **Gemini Enterprise** in beta — the consumer Gemini web app and mobile apps do not support MCP connectors.* {% endhint %} ## Setup instructions Pick your platform for step-by-step setup: * [Claude](/api/mcp/mcp-claude.md) * [Cursor](/api/mcp/mcp-cursor.md) * [Claude Code](/api/mcp/mcp-claude-code.md) * [ChatGPT](/api/mcp/mcp-chatgpt.md) * [Gemini CLI](/api/mcp/mcp-gemini-cli.md) * [Gemini Enterprise](/api/mcp/mcp-gemini-enterprise.md) — beta, enabled per account on request ## Try it Here are a few prompts to get you started: > * Find all people who could be in the buying committee for Maintain at top facility\ > management companies in CA > * Which WHOOP job posts mention Hex? What teams use it? Who makes buying\ > decisions around BI tools at Whoop? > * Boston tech companies growing 20% YoY using Databricks and Looker, that have\ > a data engineering team of less than 4? ## Available tools ### Organizations | Tool | Description | Credit cost | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `FindMatchAndEnrichOrganizations` | Find, match, and enrich organizations in one call — search by advanced query or resolve a list of names/URLs/IDs; returns selected attributes and per-entity metrics (technology, jobs, teams, people). Search results exclude permanently closed organizations unless `include_closed` is set; match mode always resolves closed organizations. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return a download instead of inline organization rows | 1 credit per matched org + 1 per paid attribute + per-entity metric costs; confirmation required above 500 credits | | `GetIntelligenceBrief` | LLM-generated sales intelligence brief for a target account, synthesized by Google Gemini from Sumble's structured data | 50 credits per completed brief | | `GetOrganizationSignals` | Get recent sales signals (notable changes) for one organization by ID: new hires on tracked technologies, leadership moves, and hiring or technology adoption trends. Optional technology-slug filter. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the signals as a downloadable file instead of including the rows in the MCP response. Each signal includes a deep-link `sumble_url` and, where relevant, a `person_id` or `job_post_id` for follow-up research, plus `person_sumble_url` (the person's Sumble profile, the primary link) and `linkedin_url` | 1 credit per signal returned; confirmation required above 500 credits | | `GetOrganizationTechStack` | Get an organization's CONFIRMED-USED technology stack, grouped by business function and technology category and restricted to technologies Sumble has confirmed are actually in use, not merely mentioned. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the stack as a downloadable file instead of including it in the MCP response; a `.csv` or `.xlsx` has one fixed-width row per confirmed-used evidence technology, a `.json` keeps the grouped structure | 1 credit per technology returned; confirmation required above 500 credits | ### Organization Lists | Tool | Description | Credit cost | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | | `ListOrganizationLists` | List saved organization lists with IDs, web app URLs, organization counts, read-only/deletable flags, deleted status, and Signals inclusion settings. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the lists as a downloadable file instead of including the rows in the MCP response | 1 credit per list | | `GetOrganizationList` | Get one organization list and its organizations. Pass a `.csv`, `.xlsx` or `.json` `file_name` to keep the list metadata and return file shape, size, and an authenticated Sumble download URL while omitting organization rows | 1 credit per organization; confirmation required above 500 credits | | `CreateOrganizationList` | Create a new empty organization list | Free | | `RenameOrganizationList` | Rename an existing organization list, keeping its ID, URL, and organizations | Free | | `AddOrganizationsToList` | Add organizations to an existing list by ID or slug | Free | | `SetOrganizationListDeleted` | Soft-delete an organization list, or restore a deleted one | Free | | `SetOrganizationListSignals` | Include or exclude a list's accounts from future Signals delivery | Free | ### Signals | Tool | Description | Credit cost | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | `SearchSignals` | Search Sumble Signals across available accounts by signal IDs, organization IDs, person IDs, technologies, job functions, priorities, saved organization lists, or signal config IDs. Supports `limit`/`offset` pagination. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the matching signals as a downloadable file instead of including the rows in the MCP response. Nested matched technologies and suggested contacts contain compact JSON text in a `.csv` or `.xlsx`, and stay nested in a `.json` | 1 credit per signal returned | | `SearchPrioritySignals` | Search Priority Signals digest items by source signal IDs, organization IDs, person IDs, job post IDs, or your relevance feedback (`is_relevant`); supports `limit`/`offset` pagination. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the matching items as a downloadable file instead of including the rows in the MCP response. Source ID arrays contain compact JSON text in a `.csv` or `.xlsx`, and stay nested in a `.json` | 1 credit per priority signal returned | | `UpdatePrioritySignalRelevance` | Mark a priority signal (by its `id` from `SearchPrioritySignals`) relevant or not relevant, or clear the feedback | Free | | `ListSignalConfigs` | List the active standing rules that decide which signals you receive: name, type, priority, scope, lookback window, filter definition, recent count, and settings link. Filter active configs by type or priority, or look up config IDs (including authorized deleted configs) as a separate mode. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return configs as a downloadable file; `advanced_query` contains compact JSON text in a `.csv` or `.xlsx`, and stays nested in a `.json`. Read-only | Free | ### Jobs | Tool | Description | Credit cost | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | `FindMatchAndEnrichJobs` | Find, look up, and enrich job postings in one call — search by advanced query (with optional organization scoping) or enrich a list of job IDs; returns selected attributes (title, full description, location, posted date, organization, extracted technologies, teams, job functions, levels, projects) and optional related people (hiring managers and team members). Pass a `.csv`, `.xlsx` or `.json` `file_name` to return one row per job as a downloadable file instead of including the rows in the MCP response; technologies, teams, job functions, levels, projects, and related people contain compact JSON text in a `.csv` or `.xlsx`, and stay nested in a `.json` | 1 credit per job + 1 per paid attribute + 1 per related person returned; confirmation required above 500 credits | | `LookupJobTitles` | Resolve a list of job titles to their canonical job function and level. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the classifications in a downloadable file instead of including the rows in the MCP response | 1 credit per 100 matched titles | ### People | Tool | Description | Credit cost | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `FindMatchAndEnrichPeople` | Find, match, and enrich people in one call — resolve person IDs, LinkedIn URLs, or emails, or search within organizations by advanced query; returns selected attributes (including the person's full experience history and profile summary in match mode), optional related people (inferred managers and direct reports), and optional email/phone contact reveals. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return one row per input or result as a downloadable file instead of inline people; unmatched inputs are retained, and nested technologies, experience, score features, managers, and direct reports contain compact JSON text in a `.csv` or `.xlsx`, and stay nested in a `.json`. Long-running requests may return `status: "running"` with a `request_id`; call the tool again with only that `request_id` to retrieve the result. Credits are charged when the completed result is first returned. | 1 credit per person + 1 per paid attribute + 1 per related person; 10 credits per first email reveal, 80 credits per first phone reveal — free on repeat reveals of the same type, or if the type is unavailable; resolving an input email to a person costs 20 credits per resolved email (emails that don't resolve are free); confirmation required above 500 credits | | `SearchPeople` | Find people by describing in natural language what they do, own, or know, such as responsibilities, projects, expertise, or the tools they use. Search everyone, or only the organizations you name, optionally including former employees. Pass location codes from `SearchLocations` in `locations` to search only people in those places. Results are ranked by relevance and can include partial matches. Set `requested_total` for the total number wanted, up to 1,000; it defaults to the page size, `limit`. Keep it unchanged while paging with `limit` and `offset`. In limited beta: ask Sumble support for access. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return one row per person as a downloadable file instead of inline people | 1 credit per person + 1 per paid attribute; confirmation required above 500 credits | ### Teams | Tool | Description | Credit cost | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `FindMatchAndEnrichTeams` | Get the teams inside a company — the groups Sumble extracts from its job postings — by resolving a list of team IDs or searching within organizations by advanced query; returns selected attributes (owning organization, parent-team breadcrumbs, jobs count, technologies, job functions, locations, first and last activity, ICP team score), optional related people with a person–team confidence breakdown, and optional job postings with composable components. Teams are organization-scoped, so resolve company names to IDs with `FindMatchAndEnrichOrganizations` first; there is no parent/subsidiary roll-up | 1 credit per team + 1 per paid attribute + 1 per related person + 1 per job post returned; confirmation required above 500 credits | ### Contact Lists | Tool | Description | Credit cost | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | `ListContactLists` | List saved contact (people) lists with IDs and people counts. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the lists as a downloadable file instead of including the rows in the MCP response | 1 credit per list | | `GetContactList` | Get one contact list and its people. Pass a `.csv`, `.xlsx` or `.json` `file_name` to keep the list metadata and return file shape, size, and an authenticated Sumble download URL. The file contains the person rows, which are omitted from the MCP response | 1 credit per person; confirmation required above 500 credits | | `CreateContactList` | Create a new empty contact list | Free | | `AddContactsToList` | Add people to an existing contact list by person ID | Free | ### Technologies | Tool | Description | Credit cost | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | `SearchTechnologies` | Look up technology names and slugs. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the matches as a downloadable file instead of including the rows in the MCP response | 1 credit per search | | `LookupTechnologies` | Resolve a list of technology names, slugs, or aliases to canonical IDs, slugs, names, and categories. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the matches as a downloadable file; categories contain compact JSON text in a `.csv` or `.xlsx`, and stay nested in a `.json` | 1 credit per 100 matched technologies | | `LookupTechnologyCategories` | Resolve a list of technology category slugs or names to their canonical categories and constituent technologies. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the matches as a downloadable file; technologies contain compact JSON text in a `.csv` or `.xlsx`, and stay nested in a `.json` | 1 credit per 100 matched categories | ### Projects | Tool | Description | Credit cost | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | `LookupProjects` | Resolve a list of project names or slugs to canonical IDs, slugs, and names. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the matches as a downloadable file instead of including the rows in the MCP response | 1 credit per 100 matched projects | ### Locations | Tool | Description | Credit cost | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `SearchLocations` | Find codes for the `hq_location` and `country` filters. Search names with `query`, list children with `parent`, or omit both fields to list top-level regions and countries. Region codes work only in `hq_location`. | 1 credit for a call with results. No credits for an empty result. | ### Support | Tool | Description | Credit cost | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | | `ReportDataQualityIssue` | Report a data quality or coverage issue — incorrect/missing/stale data, or a missing category, field, filter, project/signal type, taxonomy value, or data limit; routed to the Sumble data team | Free | | `SubmitSupportRequest` | Submit a general account, billing, or access support request (not data or coverage); routed to the Sumble support team | Free | ### Database | Tool | Description | Credit cost | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | `RunSqlQuery` | Run read-only SQL against Sumble's DuckDB (last resort). Set `file_name` to a `.csv`, `.xlsx` or `.json` filename for a download. LIST, STRUCT, and JSON values are compact JSON text in a cell of a `.csv` or `.xlsx`, and stay nested in a `.json`. A query that matches more than 1,000 rows fails: no rows are returned and nothing is charged | 1 credit per 100 bytes of query result data; confirmation required above 500 credits | | `ListTables` | List all tables and columns in the database | Free | ### Account | Tool | Description | Credit cost | | ----------------------- | ------------------------------------------------------------------ | ----------- | | `GetAccountInformation` | Check your credit balance, API key status, and plan info | Free | | `GetMyCompanyProfile` | Get your company's profile and target account intelligence profile | Free | ### Conversation history These tools read your own Ask Sumble conversations. Conversations shared with you are excluded. See [Conversation history](/api/conversations.md) for response details. | Tool | Description | Credit cost | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `ListConversations` | List conversations with titles, dates, and message and turn counts, newest first. Returns 30 per page with pagination | Free | | `GetConversation` | Read a transcript, generated-file download links, attachment names, and available credit charges and refunds. Long transcripts come back in pages | Free | ### Documentation These serve this documentation site and additional product guidance, so your assistant can answer questions about how Sumble works without a web search. Pages outside this site have no URL. | Tool | Description | Credit cost | | ---------------------- | -------------------------------------------------------------------------------------------- | ----------- | | `SearchDocumentation` | Search the documentation and return matching page paths, titles, optional URLs, and excerpts | Free | | `ListDocumentation` | List every documentation page, with its title and where it sits in the navigation | Free | | `GetDocumentationPage` | Read one documentation page, by the path `ListDocumentation` returned | Free | ## Credits MCP calls consume credits from your Sumble account, just like the [REST API](/api/api.md). The structured tools (find, enrich) follow the same pricing as the corresponding API endpoints. SQL queries via the `RunSqlQuery` tool are priced at 1 credit per 100 bytes of query result data, so you pay only for the rows you get back. Pass a `file_name` ending in `.csv`, `.xlsx` for an Excel workbook, or `.json`, to receive those rows as a downloadable file instead of inline data. LIST, STRUCT, and JSON values are stored as compact JSON text in one cell of a `.csv` or `.xlsx`, and stay nested in a `.json`. A query that matches more than 1,000 rows fails without returning rows or charging credits: add a `LIMIT` of 1,000 or less, aggregate in SQL, or narrow the `WHERE` clause. An MCP request that would cost more than 500 credits is refused. Nothing is charged and no data is returned. To go ahead, your assistant passes `allow_expensive_query`, which it should do only after asking you, and only for that one call: the next page, a refined query, or any other request above 500 credits needs your go-ahead again. When it asks, the assistant should also offer a small, cheaper sample so you can check the results before paying for all of them. Assistants that cannot pass the parameter have to narrow the request instead. The REST API is not affected. You can check your balance at any time by asking your assistant, or visit [sumble.com/account](https://sumble.com/account). To purchase additional credits, go to [Account > Purchase](https://sumble.com/account/purchase). See [Credits](/web-app/exports-credits/credits-and-exports.md) for details on monthly allocations and purchasing.