The Nuvia MCP server exposes a set of tools that let an AI assistant (such as Claude, ChatGPT, or your own agent) search market data, read and write to your CRM, and follow conversations and campaigns — all within your company's data. This page lists all the tools available today, what each one does, and its main arguments.
Available on: accounts with access to the Nuvia MCP.
Who can do it: any AI assistant authenticated in the Nuvia MCP (User and Company Admin profiles).
Module: Nuvia MCP (accessed through an MCP-compatible AI assistant)
Before you start
To use these tools, you first need to connect an AI assistant to the Nuvia MCP. See How to connect the Nuvia MCP. To follow everything that was run through MCP, see How to use the MCP Audit.
Three concepts apply to all tools:
-
Read vs. Write — Read tools only look up data; Write tools create or change records. The table in each section shows the type.
-
Restricted to your company — all CRM tools operate only on the data of the company authenticated in the token. A tool never accesses another company's data.
-
Credits — searching and cross-referencing databases is free. The only tool that uses credits is enrichment (
enrich_list). All the others have no credit cost.
Session identity
| Tool | Type | What it does |
|---|---|---|
whoami |
Read | Returns the identity authenticated in the current MCP session: user and company IDs and names. |
Search and database cross-referencing
Discovery tools for the global database (Explorium) and the Brazilian CNPJ database. They are all free. The category, location, and job title filters only accept catalog values — so resolve the user's term with a lookup_* tool before searching (the exception is the job title in search_prospects, which accepts free text).
| Tool | Type | What it does | Main arguments |
|---|---|---|---|
search_businesses |
Read | Searches for companies in the global database by firmographic filters (focused outside Brazil). | filters (e.g., country_code, company_size, naics_category), page, page_size |
search_prospects |
Read | Discovers new people/decision-makers in the global database. It does not enrich people already in the CRM — use enrich_list for that. |
filters (job_title accepts free text, job_level, job_department, country_code), page, page_size |
search_brazil_companies |
Read | Searches for Brazilian companies in the national CNPJ database. | filters (e.g., uf, cnae_principal, situacao_cadastral), filter_operator (and/or), page, page_size |
lookup_filter_values |
Read | Resolves a free-text term into the valid values of a search_businesses/search_prospects filter. Call it before searching by category/location/job title. |
field, query, entity_type (businesses or prospects) |
lookup_brazil_filter_values |
Read | Resolves a free-text term into the valid values of a search_brazil_companies filter (CNAE, legal nature, city, etc.). |
field, query |
link_brazil_to_global |
Read | Links a Brazilian company (CNPJ) to the global database, returning the global business_id — useful for prospecting decision-makers and enriching with global data. |
cnpj, domain?, company_name? |
link_global_to_brazil |
Read | Links a global company to the Brazilian database by domain, returning the CNPJ, legal name, partners, registration status, and CNAE. | domain |
Save search results to the CRM
search_* results are global and temporary. These tools turn them into contacts and companies inside your CRM.
| Tool | Type | What it does | Main arguments |
|---|---|---|---|
save_search_results |
Write | Saves the results of a search (prospects, businesses, or Brazilian companies) as CRM records, optionally adding them to a list. It is asynchronous: it queues a job and returns a job_id. |
result_type, ids (up to 2000), save_mode (contacts or list), list_id?/list_name? |
get_save_status |
Read | Checks the status of a save triggered by save_search_results, with the counts of contacts and companies created/updated. The status expires after a few minutes. |
job_id |
Contacts
Read and write contacts in your CRM (native Nuvia records).
| Tool | Type | What it does | Main arguments |
|---|---|---|---|
list_contacts |
Read | Lists and searches contacts already registered in the company. search covers name, email, and phone. Notes and custom attributes are left out. |
search?, filters?, page, page_size (≤20) |
find_contacts_by_phone |
Read | Matches a list of phone numbers with existing contacts, normalizing the country code and format before matching. | phones (up to 50) |
create_contact |
Write | Creates a contact. Required: name, country_code, phone_number. |
name, country_code, phone_number, optional (email, job_title, additional_attributes, etc.) |
create_contacts |
Write | Creates several contacts in a single call (up to 100), with partial failures isolated per item. | contacts (list) |
update_contact |
Write | Updates a contact. Only the fields sent change; additional_attributes is merged (not replaced). |
id, fields to change |
update_contacts |
Write | Updates several contacts in a single call (up to 100), with partial failures isolated per item. | updates (list) |
add_contact_note |
Write | Adds a note to a contact. The author is the authenticated user. | contact_id, content (up to 5000 characters) |
list_contact_notes |
Read | Lists a contact's notes, from newest to oldest. | contact_id |
Lists
Lists group contacts or companies with their own columns, reusable in campaigns and funnels.
| Tool | Type | What it does | Main arguments |
|---|---|---|---|
list_lists |
Read | Lists the company's CRM lists, with name, type, status, and row count. | search?, object_type?, page, page_size |
get_list |
Read | Returns a list's metadata, including its columns (key, name, type, source). Use it before adding or updating records. | id |
create_list |
Write | Creates a list that groups contacts or companies (the type cannot be changed after creation). | name, object_type, description?, columns? |
add_list_column |
Write | Adds one or more columns to an existing list (up to 20), keeping the current ones. | list_id, columns |
Records (list rows)
Each record is a row in a list, linked to exactly one contact or one company.
| Tool | Type | What it does | Main arguments |
|---|---|---|---|
list_records |
Read | Lists the rows of a list in a flat format by column name. Use get_list first to know the columns. |
table_id, filters?, sort?, page, page_size |
add_records |
Write | Adds records to a list (up to 100). Idempotent: rows already present come back in skipped. |
table_id, records (each with contact_id or business_id) |
update_record |
Write | Updates a row, merging by column key (it does not delete the others). | row_id, data |
update_records |
Write | Updates several rows in a single call (up to 100), with partial failures isolated. | updates (list) |
Enrichment
| Tool | Type | What it does | Main arguments |
|---|---|---|---|
enrich_list |
Write | Fills in missing fields (email, phone) for contacts that already exist in a list. It is asynchronous: it queues the batch and returns jobId, estimatedCredits, and contactCount. |
list_id, fields (email/phone_number), view_id?, filters? |
get_enrich_status |
Read | Checks the status of an enrichment. Free. Completed jobs leave the queue (they then return status “unknown”). | job_id |
Conversations
Read support conversations and their messages.
| Tool | Type | What it does | Main arguments |
|---|---|---|---|
list_conversations |
Read | Lists support conversations. Each item includes the contact, inbox, agent, status, and the latest message summary. | search?, status? (OPEN/RESOLVED), channel?, page, page_size |
list_messages |
Read | Lists the messages in a conversation, from newest to oldest, with content, sender, status, and attachments. | conversation_id, page, page_size |
Campaigns
Read the company's prospecting campaigns and create/activate campaigns.
| Tool | Type | What it does | Main arguments |
|---|---|---|---|
list_campaigns |
Read | Lists the company's campaigns (archived ones are left out). Each item includes name, status, channel, trigger type, metrics, and senders. | search?, status?, page, page_size |
get_campaign |
Read | Shows the details of a specific campaign, including its metrics. | id |
create_campaign |
Write | Creates a campaign in your company. It is always created as a draft — it is never activated and does not send messages. It already builds the audience (the contacts join the campaign) and returns the total number of contacts included. | name, channel_type, trigger_type, audience_config |
activate_campaign |
Write | Activates a draft campaign, putting it live, and queues the sends right away. Requires explicit confirmation. | campaign_id, confirmed |
Create a campaign through the AI assistant
create_campaign builds the campaign with the same rules as the platform and leaves it as a draft, so you can review and activate it later. Provide:
-
name— campaign name -
channel_type— sending channel (WhatsApp, LinkedIn, or multichannel) -
trigger_type— how the campaign is triggered (manual, scheduled, recurring, or by external trigger) -
audience_config— who joins the campaign: one or more lists, a funnel (with an optional stage), a static selection of contacts, or dynamic audience criteria
The same validations as on screen apply here: the sender must belong to your company and the chosen channel, campaigns with an external trigger require an external audience type, and the lists and funnels provided must belong to your company — otherwise creation is refused with the reason for the error.
The audience comes already built. When it creates the campaign, the tool also adds the contacts to the campaign and returns how many joined. This applies to list, funnel, and static selection audiences. Dynamic and external trigger audiences work differently by nature: contacts join later, as the trigger happens — so the total starts at zero, and that is expected.
If something fails after the campaign has already been created, the response always includes the draft's name and ID — use them to find it on the platform and pick up where you left off, instead of creating another one.
Activate a campaign through the AI assistant
For activation to work, the campaign must be ready and in an activatable state:
-
Have at least one step with an active Smart Funnel
-
Not be archived, already active, or a manual campaign that has already been completed
If any of these points fails, the tool returns the reason and the campaign stays as it is.
Sends are queued right away. When you activate, the tool already puts the audience's contacts in the sending queue and returns how many were queued — the same thing that happens when you activate on screen. Previously you had to wait for the next automatic processing for sends to start.
If activation succeeds but queuing fails, the response explicitly says the campaign is active, but the sends were not queued, and includes its ID. In that case, trigger or reactivate it on the platform.
Agent Builder — create and edit Smart Funnels
Besides data and CRM, the Nuvia MCP exposes Agent Builder: tools to read, test, and — for admins — create and edit Smart Funnels by chatting with the AI, without clicking screen by screen. For the step by step, see How to create and edit Smart Funnels through MCP (Agent Builder).
Read and simulation (any user)
| Tool | Type | What it does |
|---|---|---|
builder_list_agents |
Read | Lists the company's agents (Smart Funnels). |
builder_get_agent |
Read | Opens an agent's full configuration. |
builder_list_agent_flows |
Read | Lists the funnels and their stages. |
builder_list_teams |
Read | Lists the company's teams. |
builder_list_users |
Read | Lists the company's users. |
builder_list_skills |
Read | Lists the available reusable skills. |
builder_get_skill |
Read | Opens the details of a reusable skill. |
builder_list_custom_fields |
Read | Lists the custom fields. |
builder_list_integrations |
Read | Lists the integrations connected in the company. |
builder_list_businesses |
Read | Lists the account's companies (records). |
builder_agent_quality_stats |
Read | Shows an agent's qualification rate over a period (default 60 days). Use it as a comparative floor, not as an exact number. |
builder_simulate_conversation |
Read | Rehearses a conversation with the agent (up to 10 messages) without talking to the lead or creating a real conversation. It does not run external skills. |
builder_hubspot_get_settings |
Read | Reads the current configuration of the HubSpot integration. |
builder_hubspot_list_pipelines |
Read | Lists the HubSpot Deals pipelines. |
builder_hubspot_list_owners |
Read | Lists the HubSpot owners. |
builder_hubspot_list_properties |
Read | Lists the HubSpot properties. |
Creation and editing (Company Admin only)
| Tool | Type | What it does |
|---|---|---|
builder_push_agent |
Write | Creates or rewrites an agent — always as a draft, never activating anything on its own. Runs the quality check. |
builder_edit_agent |
Write | Edits an existing agent, keeping the actions and transitions already published and preserving its status (editing an active agent does not take it offline). If the agent is active, it requires explicit confirmation before changing anything. |
builder_dump_agent |
Write | Exports an entire funnel (agents, stages, follow-ups, fields, tables, skills, and media) to a file valid for 24 hours. |
builder_load_agent |
Write | Recreates an exported funnel within the same company, reconnecting everything automatically. |
builder_create_custom_field |
Write | Creates a custom field. Through conversation, it only accepts the text, date, and number types. |
builder_hubspot_set_field_mappings |
Write | Sets the field mapping between Nuvia and HubSpot. |
builder_hubspot_set_deal_stage_mappings |
Write | Sets the mapping of funnel stages to HubSpot deal stages. |
builder_hubspot_set_owner_mappings |
Write | Sets the owner mapping. |
builder_hubspot_set_sync_settings |
Write | Sets the sync rules (create contacts automatically, name template, owner source, etc.). |