top of page
Buscar

Conecte o CRM as a Service ao Claude

Foto do escritor: Marc (TeamsWork)
Marc (TeamsWork)
27 de jul.
7 min de leitura

TeamsWork CRM as a Service se conecta a ferramentas de IA por meio de sua REST API aberta, o que significa que você pode trabalhar com os dados do seu CRM diretamente do assistente de IA que sua equipe já usa. Já mostramos como levar o TeamsWork ao Microsoft Copilot em Conectar o Ticketing ao Copilot. Este guia mostra como configurá-lo com o Claude para que você possa pesquisar contatos, resumir leads e atualizar registros em uma única conversa sem escrever nenhum código.

Como funciona

Ferramentas de IA como o Claude Code e o Codex podem se conectar a um aplicativo por meio do MCP (Model Context Protocol), uma forma padronizada de dar ao assistente acesso a um app. Em vez de construir essa conexão manualmente, você fornece ao assistente o arquivo de descrição da API do CRM e pede que ele construa a conexão. Você não escreve nenhum código; o assistente a constrói, precisa apenas da sua chave de API e é executado localmente no seu computador, de modo que seus dados permanecem com você.


Antes de começar

Você vai precisar de:

  • Claude Code instalado e com sessão iniciada (ou o Codex). Ele roda no Windows, macOS e Linux, no terminal ou como a extensão do VS Code ou do JetBrains. Este guia funciona com qualquer um deles, e o caminho principal não exige que você use um terminal.

  • os arquivos OpenAPI do CRM, da Referência da API do CRM TeamsWork

  • sua chave de API do CRM TeamsWork


A conexão é um pequeno programa em Python construído com um auxiliar chamado FastMCP. Você precisa do Python instalado. Você não instala o FastMCP por conta própria: o assistente o adiciona enquanto faz a construção e depois fornece o comando exato para iniciar a conexão.


Configure a pasta do projeto. Crie uma pasta para este trabalho, com uma subpasta chamada api para os quatro arquivos OpenAPI do CRM. Para obter sua chave de API, abra seu app de CRM e vá até Configurações, depois a seção API key. Um layout típico fica assim:


your-project/
└── api/
    ├── crm-cases.openapi.json
    ├── crm-directory.openapi.json
    ├── crm-history.openapi.json
    └── crm-pipeline.openapi.json

Mantenha a chave privada. Você a fornecerá à conexão como um valor de ambiente, e não colando-a no chat.


Escolha sua região antes de executar o prompt. O prompt abaixo usa o endpoint US por padrão. Se o seu CRM estiver na região EU, edite a URL base no primeiro item do prompt (tanto a URL de US quanto a de EU estão escritas ali) antes de enviá-lo.


Passo 1: Abra o Claude Code na pasta do seu projeto

Abra o Claude Code na pasta que contém a sua subpasta api, para que ele possa ler os arquivos de especificação do CRM.


Se você usar o Codex, abra o Codex na mesma pasta. Os passos são os mesmos; muda apenas a forma como o conector é registrado, o que o Passo 3 aborda (o Codex usa seu próprio arquivo de configuração, não o do Claude Code).


Passo 2: Insira o prompt

Um lembrete antes de colar: o prompt usa por padrão a região US. Se o seu CRM estiver na região EU, altere primeiro a URL base no primeiro item.


Read my TeamsWork CRM OpenAPI files in ./api (cases, directory, history, pipeline) and build one local MCP server (FastMCP, Python, stdio) that wraps all four; fix any schema errors first.

- Auth and region from env, never hardcoded: send the key in the `Ocp-Apim-Subscription-Key` header from CRM_API_KEY; use https://crmaas-rest.azure-api.net/v1 by default (EU: https://crmaas-rest-prod-eu.azure-api.net/v1), overridable via CRM_BASE_URL.
- Support read and write (search, read, create, update, status and stage changes) for contacts, organizations, leads, opportunities, cases, and activities. Before any create, update, delete, merge, or bulk action, summarize it and ask me to confirm.
- Make task-oriented tools, not one per endpoint; keep output lean by default with full detail on request, capping large lists and supporting paging; and where the spec has empty descriptions, write clear ones.

Then set up the connection the way you load MCP servers, no terminal needed: for Claude Code write a `.mcp.json` in this folder, for Codex add the server to your config.toml, with a CRM_API_KEY placeholder in the env section. Don't ask for my key or run anything. Then tell me how to finish.

Opcional: experimente primeiro uma demonstração somente leitura

Se você preferir experimentar uma versão menor antes de habilitar o conjunto completo, este prompt cria um servidor somente leitura que cobre as operações de leitura essenciais.


Build a local MCP server (stdio, FastMCP/Python) that wraps my TeamsWork CRM OpenAPI files in ./api. For this demo, expose READ-ONLY tools for the essentials: search and read contacts, organizations, leads, opportunities, and cases, plus recent activities. Send the API key in the `Ocp-Apim-Subscription-Key` header from the CRM_API_KEY environment variable. Use the US base URL by default (CRM_BASE_URL to override). Keep output lean. If a spec file has a schema error, fix it first. Then set it up the way you load MCP servers (a `.mcp.json` for Claude Code, or config.toml for Codex) with a CRM_API_KEY placeholder. Do not ask me for my key or run anything. Then tell me how to finish.

Passo 3: Adicione sua chave e conecte

O Claude já escreveu o conector e o arquivo que o registra; você só adiciona sua chave e reinicia. Sua chave nunca vai para o chat, apenas nesse arquivo, onde o Claude deixou um espaço reservado. Isso funciona da mesma forma no terminal, na extensão do VS Code ou do JetBrains, ou no app de desktop do Claude Code.


Claude Code usa o .mcp.json na pasta do seu projeto:


{
  "mcpServers": {
    "crm": {
      "command": "python",
      "args": ["/path/to/your-project/server.py"],
      "env": { "CRM_API_KEY": "your-crm-api-key-here" }
    }
  }
}

Codex usa seu próprio config.toml (ele não lê o .mcp.json):


[mcp_servers.crm]
command = "python"
args = ["/path/to/your-project/server.py"]

[mcp_servers.crm.env]
CRM_API_KEY = "your-crm-api-key-here"

Substitua apenas your-crm-api-key-here pela sua chave; todo o resto já está preenchido. (Região EU: adicione uma linha CRM_BASE_URL ao lado de CRM_API_KEY na seção env, definida como https://crmaas-rest-prod-eu.azure-api.net/v1.) Mantenha o arquivo privado. Depois reinicie seu assistente uma vez; na primeira vez, o Claude Code pede que você aprove o conector, então diga sim.


Passo 4: Comece a trabalhar

Essa é toda a configuração. Após o reinício no Passo 3, o conector fica ativo no Claude Code, então você pode trabalhar com seu CRM em linguagem natural aqui mesmo, sem mais nenhum passo. Peça a ele para encontrar leads, resumir um contato, revisar oportunidades em aberto ou atualizar um registro. Para qualquer coisa que altere dados, o assistente primeiro resume a alteração e pede sua confirmação, para que você mantenha o controle.


Opcional: use-o no Claude chat no app de desktop

Opcional, e à parte. Você já terminou após os Passos 1 a 4. Esta parte é só para o caso de você também querer conversar com seu CRM no Claude chat no app de desktop, que é um produto diferente do Claude Code e mantém sua própria lista de conectores. Nada do que foi feito acima é transferido para ele, então você adiciona o mesmo conector ali uma vez, em seu próprio arquivo de configuração. Pule esta parte se você usar apenas o Claude Code. (A imagem 4 abaixo mostra o resultado no Claude chat.)


1. Abra o Claude Desktop, vá até Configurações, depois Desenvolvedor, depois Editar configuração. Isso abre o claude_desktop_config.json (no Windows ele fica em %APPDATA%\Claude\; no macOS em ~/Library/Application Support/Claude/).


Claude Desktop Settings, Developer tab, Edit Config

2. Adicione seu conector em mcpServers. Se o arquivo estiver vazio, o bloco abaixo é o arquivo inteiro. Se ele já tiver outras entradas (como coworkUserFilesPath ou preferences), adicione mcpServers como mais uma entrada, separada por vírgula, e deixe o restante intocado:


{
  "mcpServers": {
    "teamswork-crm": {
      "command": "uv",
      "args": ["run", "--with", "fastmcp", "python", "/path/to/your-project/server.py"],
      "env": { "CRM_API_KEY": "your-crm-api-key-here" }
    }
  }
}

Substitua o caminho pelo caminho completo até o seu server.py, e your-crm-api-key-here pela sua chave (para EU, adicione também "CRM_BASE_URL": "https://crmaas-rest-prod-eu.azure-api.net/v1"). Faça command e args corresponderem ao comando de inicialização que o Claude forneceu: as capturas de tela aqui usam uv, mas se o seu usar python, defina "command": "python" e "args": ["/path/to/your-project/server.py"]. O exemplo abaixo mostra o mcpServers adicionado no topo de uma configuração que já tinha outras definições, com uma vírgula depois dele:


mcpServers added alongside existing config fields

3. Salve e depois saia e reabra completamente o Claude Desktop. Em Configurações, Desenvolvedor seu servidor agora aparece como em execução:


teamswork-crm server running in Developer settings

4. Inicie um novo chat e faça suas perguntas. O Claude usa o conector do CRM e responde a partir dos seus dados:


Claude Desktop answering a CRM question from live data

Um limite a conhecer: o claude.ai em um navegador web e o app móvel do Claude não conseguem usar um conector local como este. Eles precisam de uma versão hospedada, o que é um tópico à parte.


Notas

  • Seus dados permanecem locais. O conector roda no seu computador, e os dados e a chave do seu CRM não são enviados a terceiros.

  • Escolha sua região definindo a URL base no prompt (US por padrão, EU disponível) ou CRM_BASE_URL.

  • Mantenha sua chave de API privada. Forneça-a apenas como o valor de ambiente, nunca em um prompt ou captura de tela.

  • A mesma abordagem funciona para outros apps da TeamsWork. Você pode apontar o Claude para outra API da TeamsWork da mesma forma.


Conclusão

Você deu ao Claude uma forma segura de trabalhar com seu CRM em linguagem natural, configurada pedindo em vez de configurar manualmente. Comece com operações de leitura para se familiarizar, depois permita que o assistente crie e atualize registros, confirmando cada alteração conforme avança.



TeamsWork é membro da Microsoft Partner Network e é especializado no desenvolvimento de Aplicativos de Produtividade que aproveitam o poder da plataforma Microsoft Teams e seu ecossistema dinâmico. Seus produtos SaaS, como CRM as a Service, Ticketing as a Service e Checklist as a Service, são altamente aclamados pelos usuários. Eles são conhecidos pela interface amigável, integração perfeita com o Microsoft Teams e planos de preços acessíveis. O TeamsWork se orgulha de desenvolver soluções de software inovadoras que aumentam a produtividade das empresas, ao mesmo tempo em que permanecem acessíveis para qualquer orçamento.

 
 
 

Comentários

bottom of page