> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nuvia.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Nuvia MCP
> Connect AI assistants (Claude, ChatGPT, Cursor) to your company's data in Nuvia via 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](/en/autenticacao) |
| 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**:
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.
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](https://docs.nuvia.ai/pt-BR/articles/15422389-como-conectar-o-mcp-da-nuvia).
## 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](https://docs.nuvia.ai/pt-BR/articles/15422389-como-conectar-o-mcp-da-nuvia).
## 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.
## Next steps
Official article with all the details and usage examples.
For programmatic integration via API key, see the domain map.