Referência da ferramenta MCP do Work IQ

O servidor MCP do Work IQ expõe 10 ferramentas por meio do MCP (Model Context Protocol). Este artigo fornece uma referência para cada ferramenta, incluindo sua finalidade, parâmetros e exemplos de uso.

O Work IQ MCP usa a autenticação do Microsoft Entra e as permissões do usuário conectado do Microsoft 365 quando suas ferramentas acessam caminhos de recursos do Microsoft Graph. Uma camada de política de locatário separada avalia cada solicitação de ferramenta e bloqueia as operações de mutação por padrão. Os administradores podem habilitar solicitações de criação, atualização, exclusão e ação compatíveis por meio da política de locatário. Para obter detalhes, consulte Governança de políticas para o Work IQ MCP.

Ferramentas de entidade

As ferramentas de entidade fornecem operações e ações CRUD em recursos do Microsoft 365. Essas ferramentas operam em caminhos de recursos relativos que são mapeados para pontos de extremidade do Microsoft Graph .

Efetuar fetch

Lê uma ou mais entidades por caminho de recurso. Suporta a busca de vários caminhos em paralelo.

Parâmetros

Resposta

Uma resposta bem-sucedida contém uma results propriedade que é uma matriz de objetos com as propriedades a seguir. Há um objeto para cada caminho de recurso no entityUrls parâmetro da solicitação.

Exemplo

Solicitação

▶ Abra este exemplo na Demonstração Interativa

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

Resposta

{
  "results": [
    {
      "data": {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('0c6bc4a2-337b-4672-9bcd-6aa53af1b02a')/messages(id,subject,from,receivedDateTime,isRead,importance)",
        "value": [
          {
            "@odata.etag": "W/\"CQAAABYAAADltuSvpI1YRKDFG38ihSmWAABepTg8\"",
            "id": "AAMkADk0...",
            "receivedDateTime": "2026-05-31T15:40:44Z",
            "subject": "Your weekly PIM digest for Contoso",
            "importance": "normal",
            "isRead": false,
            "from": {
              "emailAddress": {
                "name": "Microsoft Security",
                "address": "MSSecurity-noreply@microsoft.com"
              }
            }
          },
          {
            "@odata.etag": "W/\"CQAAABYAAADltuSvpI1YRKDFG38ihSmWAAA/eZg0\"",
            "id": "AAMkADk0...",
            "receivedDateTime": "2026-05-26T07:39:09Z",
            "subject": "Microsoft Entra ID Protection Weekly Digest",
            "importance": "normal",
            "isRead": false,
            "from": {
              "emailAddress": {
                "name": "Microsoft Security",
                "address": "MSSecurity-noreply@microsoft.com"
              }
            }
          }
        ],
        "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?%24select=id%2csubject%2cfrom%2creceivedDateTime%2cisRead%2cimportance&%24top=10&%24skip=10"
      },
      "statusCode": 200
    }
  ]
}

fetch_blob

Busca conteúdo binário, como documentos, imagens e arquivos do Office de um caminho relativo do Work IQ. O conteúdo é retornado como uma cadeia de caracteres codificada em Base64 com metadados.

Parâmetros

Resposta

Uma resposta bem-sucedida expõe as propriedades a seguir por meio do campo MCP structuredContent .

Exemplo

Solicitação

▶ Abra este exemplo na Demonstração Interativa

{
  "method": "tools/call",
  "params": {
    "name": "fetch_blob",
    "arguments": {
      "path": "/me/drive/items/01ABCDEF/content"
    }
  }
}

Resposta

{
  "structuredContent": {
    "statusCode": 200,
    "contentType": "text/plain",
    "blobName": "notes.txt",
    "sizeBytes": 14,
    "base64Content": "SGVsbG8sIFdvcmtJUSE="
  }
}

create_entity

Cria uma nova entidade em uma coleção.

Parâmetros

Resposta

Uma resposta bem-sucedida contém um objeto na structuredContent propriedade com as propriedades a seguir.

Exemplo

Solicitação

▶ Abra este exemplo na Demonstração Interativa

{
  "method": "tools/call",
  "params": {
    "name": "create_entity",
    "arguments": {
      "parentUrl": "/me/messages",
      "jsonBody": "{ \"subject\": \"Hello world!\" }"
    }
  }
}

Resposta

{
  "statusCode": 201,
  "data": {
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('0c6bc4a2-337b-4672-9bcd-6aa53af1b02a')/messages/$entity",
    "@odata.etag": "W/\"CQAAABYAAADltuSvpI1YRKDFG38ihSmWAABlFT7g\"",
    "id": "AAMkADk0...",
    "createdDateTime": "2026-06-01T17:32:39Z",
    "lastModifiedDateTime": "2026-06-01T17:32:39Z",
    "changeKey": "CQAAABYAAADltuSvpI1YRKDFG38ihSmWAABlFT7g",
    "categories": [],
    "receivedDateTime": "2026-06-01T17:32:39Z",
    "sentDateTime": "2026-06-01T17:32:39Z",
    "hasAttachments": false,
    "internetMessageId": "<CH7PR03MB79063B75F29F929523CCC68FAE152@CH7PR03MB7906.namprd03.prod.outlook.com>",
    "subject": "Hello world!",
    "bodyPreview": "",
    "importance": "normal",
    "parentFolderId": "AQMkADk0...",
    "conversationId": "AAQkADk0...",
    "conversationIndex": "AQHc8eykdVXKjf4ytUio+dQPqWG95A==",
    "isDeliveryReceiptRequested": false,
    "isReadReceiptRequested": false,
    "isRead": true,
    "isDraft": true,
    "inferenceClassification": "focused",
    "body": {
      "contentType": "text",
      "content": ""
    },
    "toRecipients": [],
    "ccRecipients": [],
    "bccRecipients": [],
    "replyTo": [],
    "flag": {
      "flagStatus": "notFlagged"
    }
  }
}

update_entity

Atualizações uma entidade existente.

Parâmetros

Resposta

Uma resposta bem-sucedida contém um objeto na structuredContent propriedade com as propriedades a seguir.

Exemplo

Solicitação

▶ Abra este exemplo na Demonstração Interativa

{
  "method": "tools/call",
  "params": {
    "name": "update_entity",
    "arguments": {
      "entityUrl": "/me/messages/AAMkADk0...",
      "jsonBody": "{ \"subject\": \"Updated: Hello world!\" }"
    }
  }
}

Resposta

{
  "statusCode": 200,
  "data": {
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('0c6bc4a2-337b-4672-9bcd-6aa53af1b02a')/messages/$entity",
    "@odata.etag": "W/\"CQAAABYAAADltuSvpI1YRKDFG38ihSmWAABlFT7g\"",
    "id": "AAMkADk0...",
    "createdDateTime": "2026-06-01T17:32:39Z",
    "lastModifiedDateTime": "2026-06-01T17:32:39Z",
    "changeKey": "CQAAABYAAADltuSvpI1YRKDFG38ihSmWAABlFT7g",
    "categories": [],
    "receivedDateTime": "2026-06-01T17:32:39Z",
    "sentDateTime": "2026-06-01T17:32:39Z",
    "hasAttachments": false,
    "internetMessageId": "<CH7PR03MB79063B75F29F929523CCC68FAE152@CH7PR03MB7906.namprd03.prod.outlook.com>",
    "subject": "Updated: Hello world!",
    "bodyPreview": "",
    "importance": "normal",
    "parentFolderId": "AQMkADk0...",
    "conversationId": "AAQkADk0...",
    "conversationIndex": "AQHc8eykdVXKjf4ytUio+dQPqWG95A==",
    "isDeliveryReceiptRequested": false,
    "isReadReceiptRequested": false,
    "isRead": true,
    "isDraft": true,
    "inferenceClassification": "focused",
    "body": {
      "contentType": "text",
      "content": ""
    },
    "toRecipients": [],
    "ccRecipients": [],
    "bccRecipients": [],
    "replyTo": [],
    "flag": {
      "flagStatus": "notFlagged"
    }
  }
}

delete_entity

Exclui uma entidade.

Parâmetros

Resposta

Uma resposta bem-sucedida contém uma statusCode propriedade definida como 204 no structuredContent campo.

Exemplo

Solicitação

▶ Abra este exemplo na Demonstração Interativa

{
  "method": "tools/call",
  "params": {
    "name": "delete_entity",
    "arguments": {
      "entityUrl": "/me/messages/AAMkADk0MDkyMzM3LTlmNzAtNDhmM...."
    }
  }
}

Resposta

{
  "statusCode": 204
}

do_action

Executa uma ação de efeito colateral, como enviar email, copiar ou mover itens.

Parâmetros

Resposta

Uma resposta bem-sucedida contém um objeto na structuredContent propriedade com as propriedades a seguir.

Exemplo

Solicitação

▶ Abra este exemplo na Demonstração Interativa

{
  "method": "tools/call",
  "params": {
    "name": "do_action",
    "arguments": {
      "actionUrl": "/me/messages/AAMkADk0.../send"
    }
  }
}

Resposta

{
  "statusCode": 202
}

call_function

Chama uma função do Microsoft Graph para calcular dados derivados, como agendas, deltas ou resultados de pesquisa.

Parâmetros

Resposta

Uma resposta bem-sucedida contém um objeto na structuredContent propriedade com as propriedades a seguir.

Exemplo

Solicitação

▶ Abra este exemplo na Demonstração Interativa

{
  "method": "tools/call",
  "params": {
    "name": "call_function",
    "arguments": {
      "parentUrl": "/me/calendarView?startdatetime=2026-06-01T17:51:49.607Z&enddatetime=2026-06-08T17:51:49.607Z"
    }
  }
}

Resposta

{
  "data": {
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('0c6bc4a2-337b-4672-9bcd-6aa53af1b02a')/calendarView(id,subject,start,end,location,organizer,isAllDay)",
    "value": [
      {
        "@odata.etag": "W/\"5bbkr6SNWESgxRt/IoUplgAAKcCTsQ==\"",
        "id": "AAMkADk0...",
        "subject": "Sales and Marketing Sync",
        "isAllDay": false,
        "start": {
          "dateTime": "2026-06-08T12:30:00.0000000",
          "timeZone": "UTC"
        },
        "end": {
          "dateTime": "2026-06-08T13:00:00.0000000",
          "timeZone": "UTC"
        },
        "location": {
          "displayName": "Sales and Marketing / General",
          "locationType": "default",
          "uniqueId": "Sales and Marketing / General",
          "uniqueIdType": "private"
        },
        "organizer": {
          "emailAddress": {
            "name": "Sales and Marketing",
            "address": "SalesandMarketing@contoso.com"
          }
        }
      }
    ],
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/calendarView?startdatetime=2026-06-01T17%3a51%3a49.607Z&enddatetime=2026-06-08T17%3a51%3a49.607Z&%24select=id%2csubject%2cstart%2cend%2clocation%2corganizer%2cisAllDay&%24top=10&%24skip=10"
  },
  "statusCode": 200
}

Ferramentas do Copilot

As ferramentas do Copilot fornecem inteligência de linguagem natural invocando o Microsoft 365 Copilot e descobrindo os agentes disponíveis.

Perguntar

Faça uma pergunta em linguagem natural ao Microsoft 365 Copilot (ou a um agente específico) sobre os dados do usuário. Quando você fornece um agentId, a solicitação vai para esse agente específico. Quando você omiti-la, a solicitação vai para o agente interno do Microsoft 365 Copilot.

Parâmetros

Resposta

Uma resposta bem-sucedida contém uma cadeia de caracteres JSON na text propriedade de um objeto TextContent . A cadeia de caracteres inclui as propriedades a seguir.

Exemplo

Solicitação

▶ Abra este exemplo na Demonstração Interativa

{
  "method": "tools/call",
  "params": {
    "name": "ask",
    "arguments": {
      "question": "Do I have any meetings today?"
    }
  }
}

Resposta

{
  "response": "You have **4 meetings scheduled today**. Here\\u2019s a clear view of your day:...",
  "conversationId": "cc7d6f5202cb4c5b814b120440e48ede"
}

list_agents

Lista os agentes disponíveis que você pode usar com a ask ferramenta. Retorna uma matriz JSON de agentes disponíveis e o agente interno do Microsoft 365 Copilot está sempre incluído.

Parâmetros

Essa ferramenta não aceita parâmetros.

Resposta

Uma resposta bem-sucedida contém uma cadeia de caracteres JSON na text propriedade de um objeto TextContent . A cadeia de caracteres inclui as propriedades a seguir.

Exemplo

Solicitação

▶ Abra este exemplo na Demonstração Interativa

{
  "method": "tools/call",
  "params": {
    "name": "list_agent",
    "arguments": {}
  }
}

Resposta

[
  {
    "agentId": "bizchat-as-gpt-scenario",
    "name": "Microsoft Copilot",
    "provider": "Microsoft"
  }
]

Ferramentas de esquema

As ferramentas de esquema permitem a descoberta em tempo de execução de caminhos de API disponíveis e seus esquemas OpenAPI. Essas ferramentas permitem que os agentes descubram quais operações estão disponíveis sem carregar grandes definições de esquema no contexto antecipadamente.

get_schema

Recupera o esquema OpenAPI para uma operação específica, identificada pelo caminho e pelo tipo de operação.

Parâmetros

Resposta

Uma resposta bem-sucedida contém o esquema JSON ou as definições de TypeScript na text propriedade de um objeto TextContent .

Exemplo

Solicitação

▶ Abra este exemplo na Demonstração Interativa

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

Resposta

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "microsoft.graph.messageCollectionResponse",
  "type": "object",
  "properties": {
    "value": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/microsoft.graph.message"
      }
    }
  },
  "$defs": {
    ...
  }
}

search_paths

Pesquisa caminhos de API disponíveis por prefixo ou filtro regex. Use essa ferramenta para descobrir quais caminhos de recursos estão disponíveis antes de chamar outras ferramentas.

Parâmetros

Resposta

Uma resposta bem-sucedida contém uma paths propriedade no structuredContent campo. Esta é uma matriz de objetos com as propriedades a seguir.

Exemplo

Solicitação

▶ Abra este exemplo na Demonstração Interativa

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

Resposta

{
  "paths": [
    {
      "path": "/admin/serviceAnnouncement/messages",
      "operations": [
        "fetch",
        "create"
      ]
    },
    {
      "path": "/admin/serviceAnnouncement/messages/{serviceUpdateMessage-id}",
      "operations": [
        "fetch",
        "create",
        "update"
      ]
    },
    ...
  ]
}

Caminhos de recursos permitidos

As ferramentas de entidade funcionam com caminhos de recursos relativos. Por padrão, os seguintes prefixos de caminho são permitidos:

• /me/
• /users/
• /sites/

Os seguintes segmentos de caminho estão bloqueados:

• /authentication/
• /servicePrincipals/

Tratamento de erros

Quando uma chamada de ferramenta falha, o servidor MCP do Work IQ retorna erros com as seguintes informações:

• Código de status HTTP do serviço downstream
• Retry-After cabeçalhos para respostas de limitação (transmitidos pelo Microsoft Graph)
• Solicitar IDs de correlação para solução de problemas

O servidor não executa novas tentativas automáticas. O cliente MCP recebe erros e toma decisões de repetição do lado do cliente.

Conteúdo relacionado

• Visão geral do MCP de QI de Trabalho
• Visão geral da API de QI de Trabalho
• Referência de permissões da API de QI de Trabalho