Read in English: Work IQ MCP: fewer tools, more paths

Um agente conectado ao Microsoft 365 começa buscando e-mails, reuniões e arquivos. O desenho degrada quando cada workload e ação viram uma ferramenta: o catálogo cresce, descrições disputam contexto e o modelo escolhe entre operações semelhantes. O Work IQ MCP propõe outra divisão: selecionar uma operação genérica e apontar para o path do recurso.

Menos superfície

O que é o Work IQ MCP?

O Work IQ MCP expõe capacidades do Microsoft 365 a agentes por meio do Model Context Protocol. Em vez de definir uma ferramenta para cada recurso — mensagens, eventos, chats — o servidor combina ferramentas genéricas com resource paths relativos, como /me/messages e /me/events.

O path identifica o alvo. A ferramenta indica a operação. fetch lê; create_entity cria; update_entity atualiza; delete_entity remove; do_action executa uma ação com efeito colateral; call_function invoca uma função. Outras ferramentas apoiam a conversa com Copilot e a descoberta do catálogo, como ask, search_paths e get_schema.

Não é um catálogo de ações de negócio por aplicação. A descoberta atual cobre Microsoft Graph v1.0, não qualquer endpoint: paths, operações e acesso dependem do serviço e do tenant.

O artigo sobre MCP explicou o protocolo; o de Microsoft Work IQ explicou o acesso ao contexto corporativo. Aqui o recorte é a interação: como escolher operação e recurso sem criar uma tool para cada endpoint.

Leitura das fontes: 09/10/2026. O repositório do CLI e servidor MCP informa Public Preview. Esse aviso é do componente, não uma classificação de todas as APIs do Work IQ.

O problema que resolve

Um catálogo por endpoint acrescenta definições, documentação duplicada e decisões de seleção. O desenho path-based separa a forma da operação do alvo: um path compatível não exige uma ferramenta nova.

Isso não torna a tarefa trivial. fetch /me/messages e do_action /me/sendMail compartilham o padrão de chamada, mas não o impacto. O catálogo encolhe; a decisão sobre recursos e operações aceitáveis continua exigindo desenho.

Como funciona — passo a passo

1. Descubra paths com search_paths; não presuma a mesma superfície em todos os tenants.
2. Inspecione o contrato com get_schema, usando path e operationType: fetch, create ou update. Não prometa introspecção de toda ação.
3. Selecione a operação pela intenção. do_action pode produzir efeitos externos; não é sinônimo de leitura.
4. Chame com path relativo e parâmetros válidos: fetch /me/messages lê; do_action /me/sendMail pode enviar.
5. Interprete resultado, status e recusa sem transformar bloqueio em sucesso vazio.

Arquitetura de referência: do pedido ao resumo

A aplicação controla o que emite; o serviço decide o que executa. No laboratório, cliente e servidor local conversam por stdio. O diagrama não afirma como a Microsoft organiza seus componentes internos.

Primeira fronteira: proposta do modelo → chamada do cliente. Para este caso, recomendo permitir search_paths com o filtro esperado, get_schema somente para /me/messages com fetch, e validar cada entrada de entityUrls antes de fetch. Descobrir um path não o inclui automaticamente na allowlist. Bloqueie qualquer tentativa de envio antes de chamar o servidor.

Segunda fronteira: aplicação → acesso ao recurso. Uma chamada aceita pelo cliente ainda pode ser negada pelo serviço. Preserve usuário e tenant no contexto da execução; não reaproveite dados de outra identidade. A restrição local não amplia acesso nem configura policy por agente.

Terceira fronteira: dados recuperados → contexto do modelo. Minha recomendação é tratar o corpo das mensagens como dados, não instruções novas. Preserve IDs de origem, quantidade aproveitada e falhas. Não deixe uma mensagem recuperada transformar o pedido de resumo em uma ação de escrita.

São controles de aplicação propostos, não funcionalidades automáticas do Work IQ. O critério é verificável: chamada fora do contrato não sai; recusa não vira caixa vazia; resumo parcial não vira cobertura total.

O path não é autorização

Um path não concede permissão. Work IQ usa Microsoft Entra e os direitos do usuário conectado; policy adiciona uma decisão por chamada. Separe quatro perguntas:

• A identidade foi autenticada?
• As permissões OAuth necessárias foram consentidas?
• O usuário já pode acessar esse dado ou executar essa ação no Microsoft 365?
• A policy do tenant permite esta ferramenta, este path e esta operação?

Na configuração inicial, mutações ficam bloqueadas por padrão. O administrador habilita cenários suportados no Microsoft 365 admin center. O controle é do tenant, sem templates iniciais por usuário, aplicação, agente ou cenário. Motor Rego não significa editor de regras arbitrárias disponível ao cliente.

Policy não substitui OAuth nem concede acesso além dos direitos do usuário. Negação é decisão de governança, não falha transitória para retry automático.

Uma allowlist no cliente restringe chamadas emitidas pela aplicação; é recomendação de arquitetura, não recurso de política por agente do serviço.

Schema em runtime: menos contexto, mais uma dependência

get_schema evita pré-carregar milhares de tipos. O contrato atual devolve JSON Schema ou definições TypeScript no campo text de um TextContent; jsonschema é o padrão. Nesse formato, faça o parse JSON do texto antes da validação. Definições TypeScript não são JSON.

São validações distintas: os argumentos da ferramenta (entityUrls no fetch) e o dado do recurso (data.value na coleção). O schema do recurso não substitui o contrato de entrada MCP nem libera acesso.

Informe path ou operationIds, nunca ambos. Nesse contrato, agentId está reservado para uso futuro: não o trate como isolamento ou autorização por agente. Registre path, operação, contrato consultado e versão do cliente; revalide após mudanças da superfície.

A descoberta permanece limitada ao Microsoft Graph v1.0. O overview declara dez ferramentas, mas a referência detalha também fetch_blob: confira o inventário real, não uma quantidade copiada da documentação.

Os nomes também importam: create e update são valores de operationType; create_entity e update_entity são nomes de ferramentas. Misturar os dois produz uma chamada que parece correta e não segue o contrato.

Limites que mudam o desenho da tarefa

As chamadas de leitura não significam leitura ilimitada. A referência documenta um $top padrão de 25 e teto de 100 para resultados de coleção; mensagens de chat têm limite de dez por requisição; $skip e $skiptoken são bloqueados. Para conteúdo binário por fetch_blob, o limite bruto padrão é 4 MB, configurável por path. O cliente recebe conteúdo Base64 em structuredContent e precisa decodificá-lo para recuperar os bytes.

Não prometa “buscar todo o histórico”. Se precisar de paginação não suportada, escolha outro fluxo compatível; não contorne o bloqueio. Valide tamanho e formato antes de recuperar arquivos.

Na prática: um resumo de mensagens sem enviar e-mail

Um analista precisa se preparar para uma reunião: “Resuma as mensagens recuperadas da minha caixa e destaque pendências. Não envie nem altere nada.” O objetivo é produzir um resumo para revisão humana, não disparar uma resposta.

O laboratório requer Node.js 18+, um cliente MCP e consentimento administrativo para o tenant. O repositório oficial documenta a inicialização do servidor local por stdio:

npx -y @microsoft/workiq mcp

Configure esse comando no cliente MCP e conclua a autenticação solicitada. Iniciar o processo não autentica o usuário nem prova que uma operação está liberada. Confira o inventário real de ferramentas da versão usada. Os blocos abaixo mostram método e parâmetros de chamadas documentadas; o cliente cuida da sessão e do envelope JSON-RPC.

1. Descubra o caminho, não invente um endpoint

{
  "method": "tools/call",
  "params": {
    "name": "search_paths",
    "arguments": {
      "filter": "messages"
    }
  }
}

Examine structuredContent.paths. Procure /me/messages e confirme que a lista operations inclui fetch. Se não estiver disponível, interrompa este exemplo. A descoberta pode listar paths que não estão liberados para o usuário; ela não é uma concessão de acesso.

2. Inspecione a operação de leitura

{
  "method": "tools/call",
  "params": {
    "name": "get_schema",
    "arguments": {
      "path": "/me/messages",
      "operationType": "fetch"
    }
  }
}

Leia o schema retornado e as propriedades da coleção. Use operationType: "fetch", não "GET" nem "read". O contrato ajuda a interpretar os registros; não libera outro path nem garante que a consulta terá sucesso.

3. Leia e declare o que foi coberto

{
  "method": "tools/call",
  "params": {
    "name": "fetch",
    "arguments": {
      "entityUrls": ["/me/messages"]
    }
  }
}

Verifique o erro MCP e o statusCode de cada item em results; valide data.value antes do resumo. Chamadas com vários paths podem ter resultados diferentes. Neste exemplo, um path por chamada mantém a origem inequívoca.

Sem $top explícito, aplica-se o padrão de 25. Isso não prova cobertura total nem ordem temporal. Não siga @odata.nextLink com $skip ou $skiptoken: são bloqueados. Declare a amostra e preserve os IDs de origem.

O retorno precisa distinguir sucesso vazio de leitura negada. Se um resultado falhar, declare a falha e a cobertura parcial; não o omita do resumo. Para throttling, a referência informa Retry-After e IDs de correlação. O servidor não faz retries automáticos: o cliente decide, com orçamento limitado para leitura e sem retry de negação por policy.

Como saída da aplicação, recomendo informar path consultado, quantidade de registros válidos, fontes e limitações. “Resumo das mensagens recuperadas” é honesto; “todas as pendências da caixa” não é. Antes de homologar, teste path fora da allowlist, schema incompatível, recusa e resposta parcial.

Este exemplo não chama do_action. “Prepare o resumo” não autoriza enviar e-mail. Num teste de aceitação separado, confirme que o cliente rejeita uma tentativa de mutação fora da allowlist e que a policy configurada mantém as mutações bloqueadas. Não habilite envio para demonstrar uma recusa.

Os exemplos foram conferidos contra a documentação, não executados em um tenant. Não há resultado de caixa postal real neste artigo. O critério de aceite é leitura autorizada, cobertura explícita e ausência de escrita — não apenas uma resposta que parece boa.

Boas práticas para produção

• Valide antes de emitir. Controle ferramenta, cada path e parâmetros; prompt não é autorização.
• Separe leitura e escrita. Exija justificativa e confirmação para mutações relevantes; o caso proposto não as habilita.
• Teste as quatro camadas de acesso. Um 200 em outro ambiente não comprova acesso neste tenant.
• Declare cobertura e recusa. Limites, erros e amostras fazem parte do contrato do resumo.
• Registre sem vazar. Correlacione intenção, identidade, tenant, tool, path e resultado; não grave tokens nem conteúdo sensível desnecessário.
• Homologue a versão. Fixe o cliente usado em produção e revalide contratos antes de upgrades.

Perguntas frequentes (FAQ)

Menos ferramentas significa menos risco?

Não por si só. O modelo reduz duplicação na definição das ferramentas, mas ainda existe risco de seleção errada de path, operação excessiva ou acesso permitido em contexto inadequado. A autorização e a policy continuam fundamentais.

get_schema permite chamar qualquer endpoint do Graph?

Não. A referência informa que a descoberta atual cobre paths e schemas do Microsoft Graph v1.0, e a superfície depende dos recursos expostos pelo Work IQ e das políticas do tenant.

Posso habilitar envio de e-mail para um agente?

Somente se o cenário for necessário e estiver coberto pelas permissões e policy do tenant. A documentação declara mutações bloqueadas por padrão no controle inicial. do_action pode produzir efeitos externos; trate envio como ação de escrita, não como uma consulta.

O Work IQ MCP está pronto para assumir uma API própria?

Não é essa a afirmação deste artigo. Ele é uma interface para recursos compatíveis do Microsoft 365. Para entender seu lugar entre as camadas, veja o mapa do Microsoft IQ. Valide o componente e a versão antes de assumir estabilidade.

Conclusão

O valor do Work IQ MCP é separar o que fazer de onde fazer. O ganho só chega à produção quando o cliente restringe o que emite, o serviço preserva autorização e o resumo declara fontes, falhas e cobertura. Menos tools simplifica o catálogo, não elimina responsabilidade.

Referências oficiais

• Work IQ MCP overview
• Work IQ MCP tool reference
• Work IQ MCP entity model
• Policy governance for Work IQ MCP
• Repositório oficial Microsoft Work IQ

👉 Se você está conectando agentes ao Microsoft 365 — especialmente quando eles podem ler e também alterar dados, este é o momento de separar ferramenta, path e autorização.
Quer trocar ideia sobre Work IQ MCP em produção? Me chama no LinkedIn.