twenty/packages/twenty-docs/l/pt/user-guide/ai/capabilities/mcp.mdx

---
title: Servidor MCP
description: Conecte assistentes de IA ao seu espaço de trabalho do Twenty usando o Model Context Protocol.
---

<Warning>
O MCP está atualmente em **alfa** e está disponível apenas em alguns espaços de trabalho. O MCP pode ainda não estar ativado no seu espaço de trabalho.
</Warning>

O Twenty expõe um servidor [MCP](https://modelcontextprotocol.io/) para que assistentes de IA — Claude Desktop, Claude Code, Cursor, ChatGPT e outros — possam ler e escrever seus dados de CRM por meio de linguagem natural.

Use o **URL do espaço de trabalho** (o URL que você usa para acessar o Twenty) como o endpoint do MCP. Na Twenty Cloud, o URL do seu espaço de trabalho pode ser `https://{mycompany}.twenty.com` ou um domínio personalizado. O servidor está disponível em:

| Ambiente           | Endpoint do MCP                                                                      |
| ------------------ | ------------------------------------------------------------------------------------ |
| **Nuvem**          | `https://{your-workspace-url}/mcp` (por exemplo, `https://mycompany.twenty.com/mcp`) |
| **Auto-hospedado** | `https://{your-domain}/mcp`                                                          |

## Métodos de autenticação

Você tem duas maneiras de autenticar seu cliente MCP: **OAuth** (recomendado) ou **Chave de API**.

### Opção A — OAuth (recomendado)

Com o OAuth, seu cliente MCP abre uma janela do navegador para você fazer login. Nenhum segredo é armazenado em arquivos de configuração, e os tokens são atualizados automaticamente.

<Note>
O OAuth requer um cliente MCP que ofereça suporte à [especificação de Autorização MCP](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor e ChatGPT oferecem suporte.
</Note>

Adicione isto à configuração do seu cliente MCP, substituindo `{your-workspace-url}` pelo host do seu espaço de trabalho (por exemplo, `mycompany.twenty.com`):

```json
{
  "mcpServers": {
    "twenty": {
      "type": "streamable-http",
      "url": "https://{your-workspace-url}/mcp"
    }
  }
}
```

É isso — nenhuma chave de API é necessária. Quando o cliente se conectar pela primeira vez, ele irá:

1. Descobrir os metadados de OAuth do Twenty por meio de `/.well-known/oauth-protected-resource` e `/.well-known/oauth-authorization-server`
2. Registrar-se como um cliente OAuth por meio de registro dinâmico de cliente (RFC 7591)
3. Abrir seu navegador para autorizar o acesso
4. Receber tokens e conectar-se ao servidor MCP

Conexões subsequentes reutilizam os tokens armazenados e os atualizam automaticamente.

### Opção B — Chave de API

Se o seu cliente MCP não oferecer suporte a OAuth, ou se você preferir credenciais estáticas, passe uma chave de API no cabeçalho `Authorization`:

```json
{
  "mcpServers": {
    "twenty": {
      "type": "streamable-http",
      "url": "https://{your-workspace-url}/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

<Warning>
Sua chave de API concede acesso aos dados do espaço de trabalho. Mantenha-a fora do controle de versão e de dotfiles compartilhados.
</Warning>

Para criar uma chave de API, vá em **Settings > APIs & Webhooks > + Create key**. Veja [APIs](/l/pt/developers/extend/api#create-an-api-key) para detalhes.

## Início rápido

### 1. Copie a configuração

Vá até **Settings > AI > More > MCP Server** no Twenty. Escolha seu método de autenticação (OAuth ou Chave de API), copie o trecho de JSON (ele já usará o URL do seu espaço de trabalho) e cole-o no arquivo de configuração do seu cliente MCP.

| Cliente            | Local do arquivo de configuração                                                                                                                                                   |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows)                                               |
| **Claude Code**    | `~/.claude.json` (usuário) ou `.mcp.json` (projeto)                                                                                                                                |
| **Cursor**         | `.cursor/mcp.json` no seu projeto, ou `~/.cursor/mcp.json` globalmente                                                                                                             |
| **ChatGPT**        | Ative o Modo Desenvolvedor em **Settings > Apps & Connectors > Advanced settings** e, em seguida, use **Create** em **Settings > Apps & Connectors** para adicionar o servidor MCP |

### 2. Conectar

Reinicie seu cliente MCP (ou recarregue a configuração). Se estiver usando OAuth, você será redirecionado ao Twenty para autorizar o acesso. Se estiver usando uma chave de API, a conexão é imediata.

### 3. Comece a usá-lo

Peça ao seu assistente de IA para interagir com seu CRM:

* *"Mostre-me as 5 empresas criadas mais recentemente"*
* *"Crie uma nova pessoa chamada Jane Doe na Acme Corp"*
* *"Encontre todas as oportunidades em aberto com valor superior a $10k"*

## Ferramentas disponíveis

Depois de conectado, o servidor MCP expõe ferramentas que refletem a API do Twenty. O fluxo de trabalho recomendado é:

1. **`get_tool_catalog`** — descobrir todas as ferramentas disponíveis
2. **`learn_tools`** — obter o esquema de entrada para ferramentas específicas
3. **`execute_tool`** — executar uma ferramenta

Você não precisa se lembrar dos nomes das ferramentas. Pergunte ao seu assistente de IA o que ele pode fazer e ele chamará `get_tool_catalog` automaticamente.

## Permissões

As conexões MCP herdam as permissões do usuário autenticado (OAuth) ou da função atribuída à chave de API. Para restringir o que o servidor MCP pode fazer:

* **OAuth**: Aplica-se à função do espaço de trabalho do usuário.
* **Chave de API**: Atribua uma função à chave de API em **Settings > Roles**. Veja [Permissões](/l/pt/user-guide/permissions-access/capabilities/permissions).

## Configuração auto-hospedada

Para instâncias auto-hospedadas, substitua `{your-workspace-url}` pelo URL do seu servidor. Certifique-se de que `SERVER_URL` no seu ambiente corresponda ao URL público da sua instância do Twenty — isso é usado para gerar os metadados de descoberta do OAuth.

```bash
SERVER_URL=https://twenty.yourcompany.com
```

O endpoint do MCP, os endpoints de OAuth e os metadados de descoberta derivam todos desse valor.

## Resolução de Problemas

**Erros "Unauthorized" ou 401**

* OAuth: autorize novamente limpando os tokens armazenados no seu cliente MCP e reconectando.
* Chave de API: verifique se a chave é válida e não expirou. Gere-a novamente, se necessário.

**O fluxo do OAuth não abre um navegador**

* Garanta que seu cliente MCP ofereça suporte à Autorização MCP. Se não oferecer, utilize o método de Chave de API.

**Tempo limite de conexão**

* Confirme que o URL do endpoint MCP é acessível a partir da sua máquina. Para instâncias auto-hospedadas, verifique se o servidor está em execução e se `SERVER_URL` está definido corretamente.