Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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:
- Discover a playbook: Call
list_playbooksto get the target playbook'sidandtriggers[].inputsdefinitions. - Start a session: Call
start_sessionwith the playbookidandinputs, and save the returned sessionid. - Monitor status: Poll
get_sessionuntilstatusis"succeeded"or"failed". To inspect agent activity, uselist_agent_runs,get_agent_run, andget_agent_run_messages. - Read results: Call
get_session_summaryfor the session summary, or calllist_outputsandread_outputfor 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. |