Nuvia MCP

AI assistants like Claude and ChatGPT are great at conversation, but they can’t see your company’s data. MCP (Model Context Protocol) is an open standard that bridges that gap: with Nuvia’s MCP server, your assistant gains access to your account’s contacts, lists, conversations, and campaigns as tools it decides when to call during the conversation. You ask in natural language, for example “create a list with technology leads in São Paulo”, and it searches, creates, or updates the information for you, without writing code. The tools respect your account’s permissions and credit consumption, exactly like actions taken through the interface.

MCP or REST API?

These are two different paths, for different uses:

	MCP	REST API
For	Use via an AI assistant, in natural language	Programmatic integration (servers, scripts)
Authentication	OAuth 2.1 (login + authorization in the client)	API key (Bearer), see Authentication
Scope	`mcp:tools`	API key scopes (`agents`, `contacts`, …)

MCP doesn’t use the REST API key. MCP authentication is OAuth 2.1, with the mcp:tools scope: a system separate from API key scopes. Don’t try to authenticate to MCP with an API key, nor reuse REST scopes here.

Nuvia’s MCP server lives at https://api.nuvia.ai/mcp (Streamable HTTP transport). This is the URL you add as a connector in your AI assistant.

How to connect

Only users with a User or Admin profile can use MCP. The flow is the same across compatible clients such as claude.ai, Claude Desktop, and Cursor:

Add the connector

In your AI assistant, add an MCP connector with the URL https://api.nuvia.ai/mcp.

The client opens Nuvia’s OAuth flow. Sign in and click Authorize to grant access.

Start using it

Ask in natural language, mentioning the Nuvia connector when needed.

The detailed step-by-step guide per app (with screenshots) changes frequently and lives in the official article: How to connect Nuvia’s MCP.

Available tools

The tools cover actions equivalent to the platform’s, organized into six groups.

Search

Prospecting on the global base and the Brazil base (CNPJ), and filter value resolution.

Tool	What it does
`search_businesses`	Searches companies in the global base, by size, country, industry, revenue, technology used, etc.
`search_prospects`	Searches people/decision-makers in the global base, by title, seniority, location, and firmographics.
`search_brazil_companies`	Searches Brazilian companies in the CNPJ base, by state, CNAE, registration status, size, partner, etc.
`lookup_filter_values`	Resolves a free-text term (e.g., “software”) into the exact value accepted by global search filters.
`lookup_brazil_filter_values`	Same function, for the Brazilian base’s filters (CNAE, legal nature, city, state, etc.).
`link_brazil_to_global`	Cross-references a Brazilian company (by CNPJ) with the global base, to later search its decision-makers.
`link_global_to_brazil`	The reverse path: from a global company’s domain, brings back its Brazilian registration data.

Lists and records

Manage CRM lists and the records inside them.

Tool	What it does
`list_lists`	Lists the company’s CRM lists, with name, type (Contact/Company), columns, and record count.
`get_list`	Brings a list’s metadata and detailed columns: a step used before adding or updating records.
`create_list`	Creates a list, of type Contact or Company (the type doesn’t change after creation). Doesn’t check for name duplicates.
`add_list_column`	Adds new columns to an existing list, preserving the current ones.
`list_records`	Lists the records (rows) of a list, organized by column name.
`add_records`	Adds contacts or companies already existing in the CRM to a list.
`update_record`	Updates a list row, merging with what already exists (doesn’t erase the other columns).
`update_records`	Same as above, in bulk (up to 100 rows per call).
`save_search_results`	Saves the results of a global search as contacts/companies in the CRM, optionally already in a list. Asynchronous.
`get_save_status`	Checks the saving progress until it completes.

create_list doesn’t check for name duplicates: asking to create the same list twice creates two separate lists. Since a natural-language request makes it easy to duplicate unintentionally, confirm whether the list already exists before creating one.

Global search results don’t go directly into a list: first materialize them as CRM records with save_search_results, then reference them with add_records.

Contacts

Works with the account’s contact base as a whole (not just within one list).

Tool	What it does
`list_contacts`	Lists/searches CRM contacts, by name, email, or phone.
`find_contacts_by_phone`	Resolves a list of phone numbers to the corresponding contacts, useful for checking duplicates.
`create_contact`	Creates a contact (name, country code, and phone are required; email, title, and others are optional).
`create_contacts`	Creates contacts in bulk (up to 100 per call).
`update_contact`	Updates an existing contact (only the fields sent are changed).
`update_contacts`	Updates contacts in bulk (up to 100 per call).
`add_contact_note`	Adds a note to a contact (up to 5000 characters).
`list_contact_notes`	Lists a contact’s notes, from most recent to oldest.

Bulk operations don’t stop if one item fails: the failure is isolated and the other items are processed normally.

Conversations

Tool	What it does
`list_conversations`	Lists customer support conversations, with contact, inbox, agent, status, and a summary of the last message.
`list_messages`	Lists a conversation’s content (text, type, sender, date, and attachments).

The Conversations tools are read-only. Sending messages is not exposed via MCP. To reply to or start a conversation, use the platform.

Campaigns

Tool	What it does
`list_campaigns`	Lists the company’s campaigns (archived ones don’t appear), with status, channel, metrics, and senders.
`get_campaign`	Brings a campaign’s details: status, channel, trigger, and metrics.

The Campaigns tools are read-only. Creating, editing, or activating campaigns is still done on the platform.

Enrichment

Tool	What it does
`enrich_list`	Triggers email and/or phone enrichment for the eligible contacts of a list, whether the whole list or a subset (view/filters). Asynchronous.
`get_enrich_status`	Checks enrichment progress (0 to 100%).

Credits: searching and cross-referencing data never consumes credits. The only tool that consumes credits is enrich_list: email = 1 credit/contact and phone = 10 credits/contact. The cost is proportional to the number of eligible contacts in the target, which can be the whole list or a subset (view/filters), so the assistant confirms the size before triggering it; pay attention with large lists.

Usage examples

Ask in natural language. Some examples:

“Use the Nuvia connector to search for contacts with the title ‘Marketing Director’ at technology companies in Brazil.”
“Use the Nuvia connector to create a list called ‘Enterprise Leads SP’ of type Contact.”
“Use the Nuvia connector to enrich the email and phone of the contacts in the ‘Enterprise Leads SP’ list.”

Depending on the assistant, you may need to repeat “use the Nuvia connector” on each request, especially if you have other active connectors with similar actions.

Troubleshooting

If the connector appears inactive, ask the assistant to call the whoami tool. If the response doesn’t come back or doesn’t include your company’s name, redo the authorization (sign in + Authorize) on the MCP client screen. The step-by-step guide is at How to connect Nuvia’s MCP.

Auditing

All calls to MCP are audited. In the platform, go to Settings → MCP Audit to see authentications, sessions, and tool calls made by your company.

MCP or REST API?

How to connect

Available tools

Search

Lists and records

Contacts

Conversations

Campaigns

Enrichment

Usage examples

Troubleshooting

Auditing

Next steps

Complete MCP guide

API sections

​MCP or REST API?

​How to connect

​Available tools

​Search

​Lists and records

​Contacts

​Conversations

​Campaigns

​Enrichment

​Usage examples

​Troubleshooting

​Auditing

​Next steps

Complete MCP guide

API sections

MCP or REST API?

How to connect

Available tools

Search

Lists and records

Contacts

Conversations

Campaigns

Enrichment

Usage examples

Troubleshooting

Auditing

Next steps