Integração MCP
Para organizações modulares, a organização conectada precisa ter um módulo de CRM ativo, além dos escopos exigidos pela integração. A API subjacente retorna HTTP 403 com module_not_active quando o acesso ao CRM não está disponível. Resolva o acesso ao módulo em Subscription antes de tentar novamente; alterar apenas a chave de API não corrige esse erro.
O Scoutello fornece um servidor remoto do Model Context Protocol (MCP) para acesso controlado aos dados da organização. Ele usa as mesmas integrações, chaves de API, escopos, verificações de tenant, limites de taxa e comportamento de registros da API REST do Scoutello.
Use MCP quando um cliente ou agente de IA precisar descobrir e chamar operações do Scoutello como ferramentas. Use REST quando uma aplicação precisar de endpoints HTTP convencionais ou de um cliente OpenAPI gerado. Ambas as interfaces usam o mesmo contrato de dados subjacente.
Antes de conectar
Uma pessoa administradora da organização precisa criar uma integração em Configurações da organização → Desenvolvedor/API. Ao criar ou alternar a chave:
- Selecione apenas os escopos de leitura e gravação necessários para o cliente MCP.
- Salve a chave
sctl_api_completa quando ela for exibida. O Scoutello a exibe uma única vez. - Armazene a chave no segredo ou na configuração de ambiente do cliente MCP, não no controle de versão.
A mesma chave de integração pode chamar REST e MCP. Não é necessário nem recomendado criar uma chave específica para MCP. As chaves sctl_mcp_ antigas não são aceitas.
Valores de conexão
Configure o cliente com estes valores:
Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY
Substitua YOUR_API_KEY pela chave de integração salva. Os formatos de configuração variam entre clientes, mas o transporte, a URL e o cabeçalho HTTP acima permanecem iguais. Se um cliente não puder definir Authorization, poderá enviar a chave em x-api-key. Não configure os dois cabeçalhos.
A URL legada https://admin.scoutello.com/api/mcp continua disponível como alias de compatibilidade. Novas conexões devem usar o endpoint versionado /api/v1/mcp.
Verificar a conexão
Depois que o cliente se conectar, chame primeiro a ferramenta whoami. Ela retorna a integração e a organização atuais, informações sobre expiração e uso das credenciais, o estado do limite de taxa e os escopos concedidos, sem expor registros da organização.
Se whoami identificar uma organização ou integração inesperada, desconecte o cliente e corrija a chave antes de chamar outra ferramenta.
Ferramentas e escopos
O servidor MCP anuncia apenas as ferramentas concedidas pela chave atual. Um cliente não pode descobrir nem chamar uma ferramenta de gravação usando apenas o escopo de leitura correspondente.
| Escopo da API | Ferramentas MCP |
|---|---|
contacts.read | contacts_list, contacts_get, contacts_get_by_external_id |
contacts.write | contacts_batch_upsert |
tasks.read | tasks_list, tasks_get, tasks_get_by_external_id |
tasks.write | tasks_batch_upsert |
protocols.read | protocols_list, protocols_get, protocols_get_by_external_id |
protocols.write | protocols_batch_upsert |
opportunities.read | opportunities_list, opportunities_get, opportunities_get_by_external_id |
opportunities.write | opportunities_batch_upsert |
projects.read | projects_list, projects_get, projects_get_by_external_id |
projects.write | projects_batch_upsert (incluindo upserts de participantes) |
milestones.read | milestones_list, milestones_get, milestones_get_by_external_id |
milestones.write | milestones_batch_upsert |
members.read | members_list |
events.read | events_list, events_get, events_get_by_external_id |
events.write | events_batch_upsert |
mails.read | mails_list, mails_get |
mail-drafts.read | mail_drafts_list, mail_drafts_get, mail_drafts_get_by_external_id |
mail-drafts.write | mail_drafts_batch_upsert (apenas para preparação de revisão humana) |
tags.read | tags_list |
whoami está sempre disponível para uma conexão autenticada. As entradas e os resultados das ferramentas seguem os mesmos esquemas e envelopes de resposta das operações REST vinculadas.
contacts_list aceita search limitados nos campos de nome, sobrenome e empresa, type, status e tagIds (uma matriz de 1 a 50 IDs, correspondente a qualquer tag selecionada). Todos os tokens de pesquisa precisam corresponder a um campo de nome; todos os filtros são combinados com AND. Mantenha esses filtros em todas as páginas do cursor. Por exemplo, { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } encontra contas existentes correspondentes sem verificar todo o inventário.
Contatos de CRM não membros vinculados a um login do Scoutello podem ser lidos e referenciados, enquanto os campos de associação e conta permanecem ocultos e as edições de contatos continuam protegidas. Um upsert somente com vínculo externo pode registrar um contato legível usando externalId, seu scoutelloId e o externalUpdatedAt opcional; omita todos os campos de CRM. Em novas tentativas ou atualizações de metadados, omita scoutelloId. Consulte as regras de limite e vinculação de contatos.
Gravar com segurança
As ferramentas de inserção ou atualização em lote podem alterar os dados do Scoutello imediatamente. Elas são idempotentes para a mesma integração e os mesmos IDs externos, mas ainda assim é necessário verificar o recurso, a organização e o escopo pretendidos antes de aplicar as alterações.
Defina mode como validate para executar a correspondência e a validação sem gravar dados. Depois de inspecionar os resultados, repita a chamada com mode: "apply" para aceitar os registros válidos. O MCP não disponibiliza operações de exclusão.
Pausar uma integração rejeita solicitações REST e MCP que usem as respetivas chaves. A rotação substitui a credencial, e a revogação desativa permanentemente todas as credenciais pertencentes à integração.
Solução de problemas
| Resultado | O que verificar |
|---|---|
401 erro de autenticação | Confirme que a chave completa está presente e que o cabeçalho usa Bearer, sem aspas em torno da chave. |
403 erro de autorização | Conceda o escopo necessário ao fazer a rotação da chave da integração e, em seguida, atualize o cliente com a chave substituta. |
404 no URL do MCP | Confirme que o URL termina em /api/v1/mcp. O serviço MCP pode ainda não estar ativado nesse ambiente do Scoutello. |
429 erro de limite de taxa | Aguarde até ao horário de reposição retornado antes de tentar novamente. REST e MCP consomem a mesma quota da integração. |
| Ferramenta ausente | Verifique os escopos da chave com whoami; as ferramentas indisponíveis são omitidas intencionalmente da descoberta. |
Para campos de registos, paginação, comportamento em lote e envelopes de erro, consulte a referência da API do Scoutello.
Planeamento de projetos conectados
Crie um projeto, depois os respetivos marcos e, em seguida, tarefas e protocolos usando IDs externos estáveis da integração. O acesso a novos marcos requer milestones.read/milestones.write; conceda members.read para consultar membros atribuíveis. As credenciais existentes não têm os respetivos permissões ampliadas automaticamente. Depois de rodar ou conceder acesso, atualize a descoberta de ferramentas e inspecione whoami.
Use IDs de cliente de membros para assignedContacts de projetos/marcos e IDs de utilizador para assignedScoutelloUserIds de tarefas ou ownerScoutelloUserId de oportunidades. As referências de tarefas/protocolos aceitam projectScoutelloId ou projectExternalId, além dos pares equivalentes de marco/oportunidade. Links apenas para marcos inferem o projeto; incompatibilidades rejeitam o item do lote. Os participantes do projeto são inserções ou atualizações aditivas e preservam as entradas omitidas.
Os protocolos são compatíveis com notas de projeto/marco sem contacto e com o estado draft/final. As importações deste trabalho conectado são silenciosas e nunca enviam comunicações. As ferramentas de listagem expõem os mesmos filtros específicos de entidade para projeto, estado, atribuição e data de vencimento que a REST. Transmita os filtros exatos, incluindo updatedSince, em cada página do cursor. Consulte a referência da API para obter o contrato completo e a semântica de valores nulos/omitidos.
Valide cada lote dependente, aplique-o, inspecione todos os resultados e leia novamente os registos antes de considerar a população concluída. Uma execução experimental não consegue resolver pais que só existem noutra execução experimental. Ao tentar novamente um link inicial ambíguo usando scoutelloId, leia primeiro pelo ID externo; os IDs de bootstrap não podem ser reproduzidos depois de o link existir.
Instruções para agentes de projetos de vendas
Cada contacto criado ou reutilizado para um projeto de vendas deve referenciar explicitamente esse projeto usando projectScoutelloId ou projectExternalId em contacts_batch_upsert. Mencionar um projeto em notas ou num ID externo não constitui uma associação. As gravações de contactos com referências de projeto também requerem projects.write. Leia novamente o contacto com contacts.read e projects.read e verifique projectParticipations; preserve as associações e os grupos existentes. Contactos genéricos fora de um projeto não requerem uma referência de projeto.
Mantenha empresas e pessoas verificadas como contactos separados. Associe uma pessoa à empresa com companyScoutelloId ou companyExternalId, não apenas com companyName. As alterações de contacto, relação com a empresa e associação são atómicas por item do lote; referências inválidas não deixam um contacto parcial. Não invente pessoas nem aplique etiquetas de proveniência.
Prepare emails de saída com mail_drafts_batch_upsert, nunca como corpos de protocolo. Conceda explicitamente os novos escopos mail-drafts.read e mail-drafts.write; a preparação também requer contacts.read e projects.write. As credenciais existentes não recebem novas permissões automaticamente. Use um ID externo estável, expectedVersion: 0 para a criação, referências explícitas ao projeto/contacto, o ID de utilizador de uma pessoa aprovadora aceite e um escopo de remetente organization ou personal configurado. Nunca adivinhe um endereço de destinatário ou uma configuração de remetente.
Mantenha a pesquisa em content.notes; apenas content.subject e content.body são conteúdo de saída. A criação do rascunho garante que o contacto é participante do projeto. As atualizações devem usar a versão devolvida pela leitura mais recente; rascunhos revistos ou enviados rejeitam edições. Tentativas idênticas devolvem o rascunho original sem criar outra revisão. Leia novamente reviewUrl, draftVersion, contentHash, o estado de aprovação/envio e o eventual mailScoutelloId.
Apenas a pessoa responsável pode aprovar e enviar através do ecrã de revisão existente. As integrações não podem aprovar, despachar nem enviar, mesmo com acesso de escrita a rascunhos. Preserve os protocolos originais ao converter rascunhos antigos e faça referência cruzada às substituições. Falhas de entrega em fila ou ambíguas exigem investigação, nunca um reenvio cego.
Preparação de publicações sociais
Conceda social-channels.read, social-posts.read, social-post-drafts.read e
social-post-drafts.write conforme necessário. members_list (members.read) pode descobrir
IDs de utilizador de revisores. As ferramentas sociais só são anunciadas quando o respetivo escopo é concedido:
| Escopo | Ferramentas |
|---|---|
social-channels.read | social_channels_list |
social-posts.read | social_posts_list, social_posts_get |
social-post-drafts.read | social_post_drafts_list, social_post_drafts_get, social_post_drafts_get_by_external_id |
social-post-drafts.write | social_post_drafts_batch_upsert, social_media_create_upload, social_media_finalize_upload |
Leia as capacidades do canal e o histórico criado pelo Scoutello, carregue os recursos e, em seguida, envie
variantes completas do canal com um revisor identificado. As ferramentas de carregamento devolvem instruções HTTP PUT:
transfira os bytes do ficheiro original fora do MCP e, em seguida, finalize o
carregamento com { "assetId": "..." }. Não incorpore ficheiros codificados em base64 nos argumentos das ferramentas.
Use expectedVersion: 0 para novos rascunhos e a versão atual para revisões
pendentes. mode: "validate" não executa gravações. A ferramenta devolve o URL de revisão;
apenas uma pessoa que utilize o painel pode aprovar a publicação ou o agendamento. Não existe
nenhuma ferramenta MCP para aprovar, publicar, cancelar ou eliminar uma publicação. Consulte periodicamente as ferramentas de rascunho/histórico
para verificar a aprovação, os motivos da rejeição e os resultados da entrega por canal. Rascunhos
revistos exigem um novo ID externo para novas propostas.
Consulte publicações sociais para revisão humana para obter exemplos de entrada, limites de carregamento, paginação e comportamento em caso de revisão tardia.