Microsoft Perception MCP tools reference

This article describes the tools, parameters, and response objects available in the Microsoft Perception Model Context Protocol (MCP) server.

Typical workflow

Because playbook sessions run asynchronously, a complete run uses the following tool sequence:

  1. Discover a playbook: Call list_playbooks to get the target playbook's id and triggers[].inputs definitions.
  2. Start a session: Call start_session with the playbook id and inputs, and save the returned session id.
  3. Monitor status: Poll get_session until status is "succeeded" or "failed". To inspect agent activity, use list_agent_runs, get_agent_run, and get_agent_run_messages.
  4. Read results: Call get_session_summary for the session summary, or call list_outputs and read_output for text-readable outputs.

To list existing sessions without a session ID, use list_sessions. To cancel a running session, use stop_session.

Playbook tools

list_playbooks

Lists available security playbooks, their input definitions, and associated agents and permissions.

Parameters: None ({}).

Response: { value: Playbook[] }

See Playbook. Use each playbook's id, not uniqueName, when calling start_session. Input definitions appear under triggers[].inputs.

Session tools

start_session

Starts a playbook session asynchronously and returns the new session and its initial agent runs.

Parameter Type Required Description
playbookId string (GUID) Yes Playbook id returned by list_playbooks. Use id, not uniqueName.
inputs array of objects Yes Input groups matching the playbook's triggers[].inputs definitions. Pass [] when the playbook requires no inputs.
inputs[].key string Yes Case-sensitive input key from the playbook definition.
inputs[].type string Yes Input type from the playbook input's acceptedInputTypes.
inputs[].values array of strings Yes Input values matching the playbook input's format and item limits.
inputs[].displayName string Conditional Display label for the entity. Required when displayNameRequired is true.
inputs[].entityUrl string No HTTPS URL for a single entity. Omit when passing multiple values.
method string No Initiation method: "manual" (default), "automatic", or "scheduled".

Example arguments:

{
  "playbookId": "00000000-0000-0000-0000-000000000000",
  "inputs": [
    {
      "key": "incidentId",
      "type": "incident",
      "values": ["12345"]
    }
  ]
}

Response: { ...Session, agentRuns: AgentRun[], playbookId?: string }

Returns a Session object with initial AgentRun items and the selected playbookId.

list_sessions

Lists sessions, ordered from newest to oldest.

Parameter Type Required Description
continuationToken string No Token from the previous response to retrieve the next page. Omit for the first page.
pageSize integer No Number of sessions per page (1–100). Defaults to 15.
filter string No Filter expression on status or statusDetail using lifecycle values. Supported patterns: status eq 'running', status in ('running','succeeded'), status equality comparisons joined by or, or statusDetail eq 'waitingForInput'.

Response: { value: Session[], continuationToken?: string }

See Session. Keep the same pageSize and filter across pages, and continue paging until continuationToken is omitted.

get_session

Retrieves the current status and metadata for a session.

Parameter Type Required Description
sessionId string Yes Session identifier.

Response: Session

stop_session

Cancels a session.

Parameter Type Required Description
sessionId string Yes Session identifier.

Response: Session

Returns the session with status: "failed" and statusDetail: "stopped".

Agent run and message tools

list_agent_runs

Lists agent runs in a session.

Parameter Type Required Description
sessionId string Yes Parent session identifier.
continuationToken string No Token from the previous response to retrieve the next page. Omit for the first page.

Response: { value: AgentRun[], continuationToken?: string }

See AgentRun. Keep the same sessionId across pages, and continue paging until continuationToken is omitted.

get_agent_run

Retrieves the status, agent identity, and metadata for an agent run.

Parameter Type Required Description
sessionId string Yes Parent session identifier.
agentRunId string Yes Agent run id returned by start_session or list_agent_runs.

Response: AgentRun

get_agent_run_messages

Retrieves messages for an agent run, ordered from newest to oldest.

Parameter Type Required Description
sessionId string Yes Parent session identifier.
agentRunId string Yes Agent run identifier.
continuationToken string No Token from the previous response to retrieve the next page. Omit for the first page.
pageSize integer No Number of messages per page. Defaults to 200.

Response: { value: Message[], continuationToken?: string }

See Message. Keep the same sessionId, agentRunId, and pageSize across pages, and continue paging until continuationToken is omitted.

Output and summary tools

list_outputs

Lists the outputs generated for a session.

Parameter Type Required Description
sessionId string Yes Session identifier.

Response: { value: Output[] }

See Output. Outputs with readableAsText: true can be read with read_output; outputs with readableAsText: false can be opened in the Microsoft Defender portal.

read_output

Reads the text content of a session output.

Parameter Type Required Description
sessionId string Yes Session identifier.
outputId string Yes Case-sensitive output id returned by list_outputs for an output with readableAsText: true. Use id, not path.

Response: { text: string }

get_session_summary

Reads the Markdown summary for a session.

Parameter Type Required Description
sessionId string Yes Session identifier.

Response: { text: string }

Returns a not-found error if the session doesn't have a summary.

Response objects

The following tables describe the objects and status values returned by Perception MCP tools.

Lifecycle values

Type Values
Status "notStarted", "running", "succeeded", "failed"
StatusDetail "inProgress", "waitingForInput", "completed", "stopped"
MessageRole "user", "agent", "system", "tool"
MessageType "userMessage", "agentMessage", "toolRequest", "toolOutput", "permissionRequest", "permissionResponse"

Playbook

Field Type Description
id string (GUID) Playbook identifier passed to start_session.
uniqueName string Catalog name.
displayName string Playbook display name.
description string Purpose of the playbook.
triggers { inputs: PlaybookInput[] }[] Trigger definitions containing PlaybookInput items ([] when no inputs are required).
webUrl string Optional. Microsoft Defender portal link.
agents PlaybookAgent[] Optional. PlaybookAgent definitions and permission requirements for the playbook.

PlaybookInput

Field Type Description
key string Case-sensitive input key, unique within the playbook.
displayName string Display label for the input.
description string Expected format, restrictions, or default behavior.
acceptedInputTypes string[] Supported input types for this input.
required boolean Whether the input is required.
minItems integer Minimum number of values.
maxItems integer Maximum number of values.
displayNameRequired boolean Optional. Whether start_session requires a displayName for this input.
dependencies { inputKey: string, relation: string, description: string }[] Optional. Relationships to other inputs in the playbook.
allowedValues { value: string, description: string }[] Optional. Allowed choices when restricted; pass value in start_session.

PlaybookAgent

Field Type Description
id string Agent definition identifier.
name string Agent name.
description string Optional. Agent description.
input string Optional. Description of expected agent inputs.
output string Optional. Description of expected agent outputs.
permissions { permission: string, reason: string }[] Optional. Permissions used by the agent.

Session

Field Type Description
id string Session identifier.
status Status Current session status.
createdAt string ISO 8601 creation timestamp.
updatedAt string ISO 8601 last-updated timestamp.
webUrl string Microsoft Defender portal link to the session.
statusDetail StatusDetail Optional. Additional status detail.
displayName string Optional. Session display name.
inputs StoredInput[] Optional. Inputs recorded for the session.
initiatedBy IdentitySet Optional. Identity that started the session.
tags string[] Optional. Session tags.

AgentRun

Field Type Description
id string Agent run identifier.
sessionId string Parent session identifier.
agent { id: string, displayName?: string, agentDefinitionName?: string, agentApplicationId?: string } Agent identity and metadata.
status Status Current run status.
createdAt string ISO 8601 creation timestamp.
updatedAt string ISO 8601 last-updated timestamp.
startedAt string ISO 8601 start timestamp.
webUrl string Microsoft Defender portal link to the session.
tenantId string Optional. Microsoft Entra tenant ID.
statusDetail StatusDetail Optional. Additional status detail.
completedAt string Optional. ISO 8601 completion timestamp.
durationMs integer Optional. Run duration in milliseconds.
sessionInputs StoredInput[] Optional. Inputs recorded for the parent session.
failureInfo { message?: string, errorType?: string } Optional. Failure details when a run fails.
initiatedBy IdentitySet Optional. Identity that started the parent session.

Supporting types

  • StoredInput: { value: string, type: string, displayName?: string, entityUrl?: string }
  • Identity: { id: string, displayName?: string }
  • IdentitySet: { user?: Identity, application?: Identity, agent?: Identity }

Message

Field Type Description
messageId string Message identifier.
role MessageRole Message role.
type MessageType Message category.
author { role: MessageRole, id: string } Message author.
timestamp string ISO 8601 message timestamp.
sequenceId string Optional. Chronological sequence identifier.
turnId string Optional. Agent turn identifier.
content string Optional. Message text or JSON-serialized structured content.

Output

Field Type Description
id string Case-sensitive output identifier passed to read_output.
type "summary" \| "artifact" Output category.
path string Relative file path within the session.
size integer File size in bytes.
readableAsText boolean Whether the output can be read as text with read_output.