Condividi tramite

Introduzione al server MCP di Microsoft Sentinel

Importante

Alcune informazioni in questo articolo fanno riferimento alle caratteristiche di un prodotto prima del rilascio, che possono essere modificate sostanzialmente prima della distribuzione al pubblico. Microsoft non fornisce alcuna garanzia, esplicita o implicita, in relazione alle informazioni contenute in questo documento.

La raccolta di strumenti per la creazione di agenti nel server MCP (Model Context Protocol) di Microsoft Sentinel consente agli sviluppatori di usare il linguaggio naturale per creare agenti Security Copilot all'interno di un IDE compatibile con MCP.

In questa guida introduttiva si apprenderà come:

  • Configurare e autenticare il server MCP

  • Abilitare GitHub Copilot modalità agente

  • Gestire il contesto per gli strumenti MCP

Prerequisiti

Per usare Microsoft Sentinel MCP Server e accedere agli strumenti, è necessario eseguire l'onboarding in data lake di Microsoft Sentinel. Per altre informazioni, vedere Onboard to data lake di Microsoft Sentinel e Microsoft Sentinel graph (anteprima).

Editor di codice supportati

Il supporto di Microsoft Sentinel per gli strumenti MCP per la creazione di agenti Security Copilot è disponibile per gli editor di codice basati su intelligenza artificiale seguenti:

Configurare e autenticare il server MCP

I passaggi per installare il server MCP sono i seguenti:

  1. Avviare Visual Studio Code (VS Code).

  2. Aggiungere la connessione al server MCP in VS Code. Digitare Premere Ctrl + Shift + P per aprire il riquadro comandi. Digitare il simbolo >, seguito dal testo MCP: Add server.

    Immagine per aggiungere il server MCP nel codice di Visual Studio

  3. Selezionare HTTP (HTTP or Server-Sent Events).

    Immagine per selezionare l'opzione http SSE nel codice vs

  4. Digitare l'URL del server seguente e selezionare INVIO. Questo URL fa distinzione tra maiuscole e minuscole.

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

  5. Immettere un ID server descrittivo.

    Immagine per aggiungere un ID server personalizzato nel codice vs

  6. Viene richiesto di considerare attendibile il server.

    Immagine per selezionare Trust server in VS code

  7. Selezionare Consenti quando viene richiesto di autenticare la definizione del server.

    Immagine per selezionare consenti al server di eseguire l'autenticazione in Security Copilot

  8. Scegliere se rendere il server disponibile in tutte le aree di lavoro di VS Code o solo in quella corrente.

    Immagine per selezionare le aree di lavoro nel codice vs

  9. Dopo l'autenticazione, il server dovrebbe iniziare l'esecuzione e dovrebbe essere visualizzato un file denominato mcp.json che controlla la presenza di configurazioni del server MCP nell'area di lavoro vs Code.

    Immagine che mostra l'avvio dell'esecuzione del server MCP

Abilitare GitHub Copilot modalità agente

  1. Aprire il menu >Visualizzazione chat > di VS Code Chat o premere CRTL + ALT + I.

  2. Impostare la chat sulla modalità Agente.

    Immagine per mostrare la modalità agente nella chat

  3. Selezionare l'icona degli strumenti nella barra dei prompt.

    Immagine per mostrare gli strumenti dell'agente nella chat

  4. È possibile visualizzare un elenco degli strumenti usati da GitHub Copilot. Espandere la riga per il server MCP appena aggiunto per visualizzare i cinque strumenti per la creazione di agenti:

    Immagine per visualizzare gli strumenti dell'elenco di server MCP

Gestire il contesto per gli strumenti MCP

Fornendo il contesto corretto, è possibile ottenere assistenza dall'IA in VS Code per fornire risposte pertinenti e accurate. Questa sezione illustra due opzioni per gestire il contesto e garantire che il assistente di intelligenza artificiale usi gli strumenti MCP come previsto e con maggiore coerenza.

È possibile scegliere tra una delle opzioni seguenti per gestire il contesto:

  1. Istruzioni personalizzate

  2. Aggiungere un file di contesto

Istruzioni personalizzate

Le istruzioni personalizzate consentono di definire linee guida o regole comuni in un file Markdown per descrivere le modalità di esecuzione delle attività. Invece di includere manualmente il contesto in ogni richiesta di chat, specificare istruzioni personalizzate in un file Markdown per garantire risposte di intelligenza artificiale coerenti in linea con i requisiti del progetto.

È possibile configurare istruzioni personalizzate per l'applicazione automatica a tutte le richieste di chat o solo a file specifici.

Usare un file di istruzioni personalizzato

Definire le istruzioni personalizzate in un singolo .github/copilot-instructions.md file Markdown nella radice dell'area di lavoro. VS Code applica automaticamente le istruzioni in questo file a tutte le richieste di chat all'interno dell'area di lavoro.

Procedura per l'uso di un .github/copilot-instructions.md file:

  1. Abilitare l'impostazione github.copilot.chat.codeGeneration.useInstructionFiles .

  2. Creare un .github/copilot-instructions.md file nella radice dell'area di lavoro. Se necessario, creare prima una .github directory.

    Immagine per aggiungere istruzioni personalizzate per gestire il contesto in Visual Studio Code

  3. Descrivere le istruzioni usando il linguaggio naturale e in formato Markdown.

  4. Per iniziare, copiare il contenuto del file scp-mcp-context.md di contesto nel copilot-instructions.md file. Vedere Contesto MCP.

Aggiungere un file di contesto

Per garantire che i assistente di intelligenza artificiale possano usare gli strumenti MCP come previsto e con maggiore coerenza, aggiungere questo file di contesto all'IDE. Assicurarsi che il assistente di intelligenza artificiale faccia riferimento a questo file quando viene richiesto.

  1. Aggiungere il contesto scp-mcp-context.md a VS Code o incollarlo direttamente nell'area di lavoro. Usare il file di contesto, vedere Contesto MCP. L'area di lavoro è simile alla seguente:

    Immagine che mostra il file di contesto MCP aggiunto all'area di lavoro

  2. Selezionare Aggiungi contesto nella barra dei prompt e selezionare il file di contesto.

    Immagine per visualizzare il file di contesto MCP aggiunto nella barra dei prompt

File di contesto per gli strumenti MCP

Copiare l'oggetto scp-mcp-context.md da usare con l'avvio rapido.


# 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://learn.microsoft.com/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.

Passaggi successivi

  • Last updated on