Getting started with Microsoft Sentinel MCP server

2025-10-23

Important

Some information in this article relates to a prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

The agent creation tool collection in the Microsoft Sentinel Model Context Protocol (MCP) server enables developers to use natural language to build Security Copilot agents within an MCP-compatible IDE of choice.

In this getting started, you learn how to:

Set up and authenticate to the MCP server
Enable GitHub Copilot agent mode
Manage context for MCP tools

Prerequisites

To use Microsoft Sentinel MCP Server and access the tools, you must be onboarded to Microsoft Sentinel data lake. For more information, see Onboard to Microsoft Sentinel data lake and Microsoft Sentinel graph (preview).

Supported code editors

Microsoft Sentinel’s support for the Security Copilot agent creation MCP tools is available for the following AI-powered code editors:

Visual Studio Code

Set up and authenticate to the MCP server

The steps to install the MCP server are as follows:

Launch Visual Studio Code (VS Code).
Add the MCP server connection in VS Code. Type Press Ctrl + Shift + P to open Command Palette. Type the symbol >, followed by the text MCP: Add server.
Select HTTP (HTTP or Server-Sent Events).

Type the following server URL and select Enter. This URL is case sensitive.

    https://sentinel.microsoft.com/mcp/security-copilot-agent-creation

Enter a friendly Server ID.
You are prompted to Trust the server.
Select Allow when prompted to authenticate the server definition.
Choose whether to make the server available in all VS Code workspaces or just the current one.
Once authenticated, the server should start Running and you should see a file named mcp.json that checks for MCP Server configurations in VS Code workspace.

Enable GitHub Copilot agent mode

Open VS Code’s chat > View menu > Chat or press CRTL + ALT + I.
Set the chat to Agent mode.
Select the tools icon in the prompt bar.
You can see a list of the tools being used by GitHub Copilot. Expand the row for the MCP server you just added to see the five tools for agent building:

Manage context for MCP tools

By providing the right context, you can get help from AI in VS Code to deliver relevant and accurate responses. This section covers two options to manage context and ensure that the AI assistant uses the MCP tools as intended and with greater consistency.

You can choose from one of the following options to manage context:

Custom instructions
Add context file

Custom instructions

Custom instructions let you define common guidelines or rules in a Markdown file to describe how tasks should be performed. Instead of manually including context in every chat prompt, specify custom instructions in a Markdown file to ensure consistent AI responses that align with your project requirements.

You can configure custom instructions to apply automatically to all chat requests or to specific files only.

Use a custom instructions file

Define your custom instructions in a single .github/copilot-instructions.md Markdown file in the root of your workspace. VS Code applies the instructions in this file automatically to all chat requests within this workspace.

The steps to use a .github/copilot-instructions.md file:

Enable the github.copilot.chat.codeGeneration.useInstructionFiles setting.
Create a .github/copilot-instructions.md file at the root of your workspace. If needed, create a .github directory first.
Describe your instructions by using natural language and in Markdown format.
To get started, copy the contents of the context file scp-mcp-context.md into the copilot-instructions.md file. See MCP context.

Add context file

To help with ensuring that the AI assistant can use the MCP tools as intended and with greater consistency, add this context file to your IDE. Ensure that the AI assistant is referring to this file when you're prompting it.

Add the context scp-mcp-context.md to VS Code or paste it to your workspace directly. Use the context file, see MCP context. Your workspace looks something like this:
Select Add Context in the prompt bar and select the context file.

Context file for MCP tools

Copy the scp-mcp-context.md to use with the quickstart.


# MCP Tools Available for Agent Building
    1. **start_agent_creation**
        - **Purpose**: Creates a new Security Copilot session and starts the agent building process.
        - The userQuery input will be the user's problem statement (what they want the agent to do).
        - The output of the tool should be returned IN FULL WITHOUT EDITS.
        - The tool will return an initial agent YAML definition.
    2. **compose_agent**
        - **Purpose**: Continues the session and agent building process created by *start_agent_creation*. Outputs agent definition YAML or can ask clarifying questions to the user.
        - The sessionId input is obtained from the output of *start_agent_creation*
        - The existingDefinition input is optional. If an agent definition YAML has not been created yet, this should be blank (can be an empty string).
    3. **search_for_tools**
        - **Purpose: Discover relevant skills (tools) based on the user's query
        - This will create a new Security Copilot session, but it should not be included in the start_agent/continue_agent flow.
          - A user might want to know about Security Copilot skills they have access to without wanting to create an agent
          - The session ID created should NOT be reused in any capacity
    4. **get_evaluation**
        - **Purpose: Get the results of the evaluations triggered by each of the above tools. You MUST repeatedly activate this tool until the property of the result "state" is equal to "Completed" in order to get the fully processed result. The "state" may equal "Created" or "Running" but again, you must repeat the process until the state is "Completed". There is NO MAXIMUM amount of times you might call this tool in a row.
    5. **deploy_agent**
        - **Purpose: Deploy an agent to Security Copilot.
        - The user must provide the scope as either "User" or "Workspace".
        - Unless they already have an AGENT definition yaml provided, *start_agent_creation* must be run before to generate an agentDefinition
        - "agentSkillsetName" should be COPIED EXACTLY from the value of "Descriptor: Name:" in the agent definition YAML, including any special characters like ".". This will NOT work if the two do not match EXACTLY.
        - DO NOT use *get_evaluation* after this tool.

# Agent Building Execution Flow

## Step 1: Problem Statement Check
- If the user did **not** provide a problem statement, prompt them to do so.
- If the user **did** provide a problem statement, proceed to Step 2.

## Step 2: Start Agent Creation
- Use the `start_agent_creation` tool with `userQuery = <problem statement>`.
  - **DO NOT** include any quotation marks in the userQuery
- Then, use `get_evaluation` to retrieve the initial response.
  - **DO** repeatedly call `get_evaluation` until the `"state"` property of the result equals `"Completed"`.
  - **DO NOT** require the user to ask again to get the results.
  - **DO NOT** edit or reword the response content.

## Step 2.5: Output Handling
- **DO NOT** reformat, summarize, or describe the YAML output.
- **DO** return the YAML output **verbatim**.
- **DO** return the output in **AGENT FORMAT**.

## Step 3: Agent Refinement
- Ask the user if they would like to edit the agent or if they would like to deploy the agent. If they want to deploy, skip to **Step 4**.
- If the user wants to edit the agent definition:
  - If they respond with edits directly, use `compose_agent` with:
    - `sessionId` from `start_agent_creation`
    - `existingDefinition = <previous AGENT YAML>`
      - `\n` MUST be rewritten as `\\n`
    - `userQuery = <user’s new input>`
      - **DO NOT** include any quotation marks in the userQuery
  - If they attach a manually edited YAML file to the context, use the file content as `existingDefinition`.
    - **DO NOT** edit the file directly, you MUST use `compose_agent`
    - `\n` MUST be rewritten as `\\n`

## Step 4: Agent Deployment
- If the user asks to deploy the agent, use `deploy_agent`.
  - You **must confirm the scope**: either `"User"` or `"Workspace"`.
    - If not provided, ask the user to specify.
  - `agentSkillsetName` must **exactly match** the value of `Descriptor: Name:` in the YAML.
    - This includes any special characters.
  - Leave existing instances of `\n` inside `agentDefinition` as-is
- **DO NOT** run `get_evaluation` after deployment.
- **DO** include all of these things in the tool response to the user:
    1. Confirm successful deployment to the user
    2. Direct the user to the Security Copilot portal to test and view the agent with this link: https://securitycopilot.microsoft.com/agents
    3. Direct the user to read more on how to test their agent in Security Copilot with this link: https://free.blessedness.top/en-us/copilot/security/developer/mcp-quickstart#test-agent

## Step 5: Further Agent Refinement and Redeployment
- After deployment, the user may still want to **edit the agent definition**.
  - If so, you must support calling `compose_agent` again.
  - Follow the same process as described in **Step 3**:
    - If the user asks for edits directly, use the previous AGENT YAML as `existingDefinition`.
    - If the user uploads a manually edited YAML file, use the file content as `existingDefinition`.
- The user may also want to **redeploy the agent** after making refinements.
  - You must run `deploy_agent` again using the updated YAML.
  - Ensure the `agentSkillsetName` matches **exactly** the value of `Descriptor: Name:` in the latest YAML, including any special characters.
  - Leave existing instances of `\n` inside `agentDefinition` as-is
  - Confirm the deployment scope: either `"User"` or `"Workspace"`.
    - If the scope is not provided, prompt the user to specify.
  - Do **not** run `get_evaluation` after deployment.
  - Confirm successful redeployment to the user.
- Alternatively, the user may want to **create a new agent**.
  - Restart the procedure from **Step 1**.
  - When using `start_agent_creation`, a new session ID will be created.
  - **DO** keep track of which session IDs correspond to which problem statements or agents so the user can return to previous sessions if needed.

## Additional Rules
- Only call `compose_agent` **after** the user has provided a response. Do not proceed automatically.
- Agent creation must remain **user-driven**. Do not initiate steps without explicit user input.
- Wait for the user to respond before continuing to the next step.
- Tool responses must be returned **directly to the user** in full.
  - Do **not** alter, reformat, summarize, or reword the content of any tool response.
  - This applies specifically to the `"result": "content"` field in the JSON returned by tool executions.
  - LEAVE OUT any "Grounding Notes"

## Error Handling
- If any tool call fails:
  - Inform the user of the failure.
  - If it is a client error, make an attempt to retry the tools, rewriting inputs based on the error message.
    - Example: If the error indicates invalid JSON characters, escape or remove those characters from the input and retry. Always attempt escaping first.

Next steps

Quickstart

Share via