Riferimento al server MCP di Windows 365 for Agents (anteprima)

Windows 365 for Agents è un server MCP per il pieno controllo operativo di un PC cloud con Windows 365. Usa questo server MCP per guidare un vero ambiente Windows tramite interazione desktop (mouse, tastiera, cattura dello schermo, esecuzione dei comandi), automazione del browser tramite Microsoft Edge e ispezione semantica dell'interfaccia utente tramite Windows Automazione interfaccia utente.

Per saperne di più sulle Windows 365 per gli agenti, consulta Windows 365 per la documentazione degli agenti.

Overview

Available tools

mcp_desktop_move_mouse

Sposta il cursore in una posizione a schermo. Usalo mcp_desktop_click invece se intendi cliccare sulla destinazione.  Required parameters:

• x: Coordinata X nei pixel dello schermo
• y: Coordinata Y nei pixel dello schermo

mcp_desktop_click

Clicca su una posizione, o sulla posizione attuale del cursore se le coordinate sono omesse. Supporta clic singolo, doppio clic e tutti e cinque i tasti del mouse. 

Optional parameters:

• x: Coordinata X nei pixel dello schermo (omettere la posizione attuale)

• y: Coordinata Y nei pixel dello schermo (omettere la posizione attuale)

• button: Sinistra, Destra, Centrale, Avanti o Indietro (predefinito Sinistra)

• clickCount: 1 = clic singolo, 2 = doppio clic (predefinito 1)

mcp_desktop_get_cursor_position

Restituisci le coordinate attuali del cursore. No parameters. Restituisce {cursorX, cursorY}.

mcp_desktop_drag_mouse

Trascina da una posizione all'altra. Utile per spostare oggetti, ridimensionare finestre o scorrere con precisione pixel. Required parameters:

• startX: Coordinate Start X.
• startY: Coordinata Start Y.
• endX: Fine della coordinata X.
• endY: Fine Coordinata Y. Optional parameters:
• button: Sinistra, Destra o Centrale (il predefinito è Sinistra)

mcp_desktop_scroll

Scorri in una posizione usando unità notch (non pixel). Tre tacche corrispondono a circa una pagina. 

Required parameters:

• x: Posizione di scroll X

• y: Posizione di scorrimento Y

Optional parameters:

• deltaX: Tacche orizzontali, positivo = destra (predefinito 0)
• deltaY: Tacche verticali, positivo = giù (predefinito 0)

mcp_desktop_type_text

Digita il testo tramite simulazione da tastiera. Per le scorciatoie da tastiera, usa mcp_desktop_press_keys. Per i campi del modulo web, usa mcp_browser_type. 

Required parameters:

• text: Testo da scrivere

mcp_desktop_press_keys

Premi contemporaneamente una combinazione di tasti. Supporta tasti modificatori, tasti funzione e tasti standard. 

Required parameters:

• keys: Array di nomi chiave da premere insieme (ad esempio, \["ctrl","c"\], \["alt","tab"\], \["ctrl","shift","s"\])

mcp_desktop_take_screenshot

Cattura lo schermo intero o una regione ritagliata come immagine PNG (codificata base64). 

Optional parameters:

• x: Bordo sinistro della regione coltivata
• y: Bordo superiore della regione coltivata
• width: Larghezza della regione coltivata
• height: Altezza della regione coltivata

mcp_desktop_analyze_screen

Esegui OCR su tutto lo schermo. No parameters. Restituisce {fullText, averageConfidence, boxes[{text, confidence, x, y, width, height}], width, height}.

mcp_desktop_get_screen_size

Ripristina la risoluzione dello schermo. No parameters. Restituisce {width, height}.

mcp_desktop_list_windows

Elenca tutte le finestre visibili con i loro titoli, posizioni e dimensioni. No parameters. Restituisce un array di {title, processName, handle, x, y, width, height}.

mcp_desktop_activate_window

Porta una finestra in primo piano usando un fuzzy title match.

Required parameters:

• titlePattern: Titolo parziale della finestra (sottostringa insensibile alla maiuscole)

mcp_desktop_focus_browser

Focali una finestra del browser (Edge, Chrome o Firefox), opzionalmente filtrata da URL o titolo.

Optional parameters:

• pattern: URL o sottostringa del titolo per corrispondere (omettere in qualsiasi finestra del browser)

mcp_desktop_close_window

Chiudi con grazia una finestra con un match per il titolo confuso. I processi critici per il sistema sono protetti e non possono essere chiusi.

Required parameters:

• titlePattern: Titolo parziale della finestra (80% soglia di partita). Restituisce {matchedTitle, processName, closed}.

mcp_desktop_execute_shell_command

Esegui un comando shell in un ambiente sandbox. I comandi vengono convalidati rispetto a una lista di permessi e i pattern pericolosi vengono bloccati.

Required parameters:

• command: Comando di eseguire

Optional parameters:

• cwd: Directory operativo
• timeoutMsTimeout in millisecondi (predefinito 30000, massimo 30000)

mcp_desktop_execute_python_code

Esegui codice Python in un ambiente sandbox con limiti di risorse. Ideale per l'elaborazione dati, i calcoli, l'I/O dei file e qualsiasi calcolo che vada oltre i semplici comandi shell.

Required parameters:

• code: codice Python (massimo 262.144 caratteri).

Optional parameters:

• cwd: Directory operativo
• timeoutMsTimeout in millisecondi (predefinito 30000, massimo 30000).

Restituisce lo stesso schema come mcp_desktop_execute_shell_command

mcp_desktop_wait_milliseconds

Mettere in pausa l'esecuzione per permettere il completamento di animazioni o transizioni. Non usare nei cicli di sondaggio—usare mcp_browser_wait_for per il sondaggio DOM. 

Required parameters:

• ms: Durata di attesa in millisecondi (serrata a [0, 5000])

mcp_browser_navigate

Naviga fino a un URL e aspetta che la pagina si carichi. 

Required parameters:

• url: URL completo incluso il protocollo (ad esempio, https://example.com)

mcp_browser_back

Torna indietro nella cronologia del browser. No parameters.

mcp_browser_forward

Naviga avanti nella cronologia del browser. No parameters.

mcp_browser_reload

Ricarica la pagina corrente. No parameters.

mcp_browser_get_url

Restituisci l'URL della pagina corrente come stringa semplice. No parameters.

mcp_browser_get_title

Restituisci il titolo della pagina corrente come una stringa semplice. No parameters.

mcp_browser_get_text

Restituisci il contenuto del testo della pagina visibile come una stringa semplice. No parameters. Troncato a 512 KB.

mcp_browser_get_html

Restituisci la fonte HTML a pagina intera come stringa semplice. No parameters. Troncato a 512 KB.

mcp_browser_click

Clicca su un elemento DOM tramite il selettore CSS. Più affidabile del clic basato su coordinate per i contenuti web.

Required parameters:

• selettore: selettore CSS (ad esempio, #submit-btn oppure a.nav-link)

mcp_browser_type

Digita il testo in un elemento di forma tramite il selettore CSS.

Required parameters:

• selector: CSS selettore dell'elemento di input.
• text: Testo da scrivere

mcp_browser_query_text

Fai corrispondere il contenuto del testo del primo elemento a un selettore CSS.

Required parameters:

• selector: CSS selettore

mcp_browser_wait_for

Aspetta che appaia un elemento DOM. Utile per contenuti dinamici che si caricano in modo asincrono.

Required parameters:

• selector: CSS selettore da aspettare

Optional parameters:

• timeoutMsTimeout in millisecondi (predefinito 5000, massimo 30000)

mcp_browser_eval_js

Valuta un'espressione JavaScript nel contesto della pagina e restituisci il risultato come stringa.

Required parameters:

• expression: JavaScript espressione che restituisce una stringa

mcp_browser_list_tabs

Elenca tutte le schede aperte con il loro index, title, e URL. No parameters. Restituisce un array di {index, title, url}.

mcp_browser_switch_tab

Passa a una scheda per indice.

Required parameters:

• tabIndex: Indice di tabulazione basato su 0

mcp_browser_new_tab

Apri una nuova scheda, opzionalmente navigando verso un URL.

Optional parameters:

• url: URL per aprire (scheda vuota se omessa)

Restituisce {index, title, url}.

mcp_browser_close_tab

Chiudi una scheda per indice.

Required parameters:

• tabIndex: Indice di tabulazione basato su 0

mcp_browser_screenshot

Scatta uno screenshot PNG solo della viewport del browser (non a schermo intero). No parameters. Restituisce una PNG codificata base64.

mcp_accessibility_get_accessibility_tree

Recupera l'albero degli elementi UI per la finestra in primo piano. Ogni elemento include ruolo, nome, valore e coordinate dello schermo.

Optional parameters:

• maxDepth: Profondità massima di attraversamento dell'albero, 1-10 (predefinito 3)
• maxElements: Massimo elementi da restituire, 1-2000 (predefinito 500)

Restituisce un albero gerarchico di {ruolo, nome, valore, x, y, larghezza, altezza, figli[...]}.

mcp_accessibility_find_ui_element

Cerca elementi UI per contenuto testuale, ruolo di accessibilità o nome (sottostringa insensibile alla maiuscolo). Restituisce elementi corrispondenti con le loro coordinate sullo schermo cliccabili.

Optional parameters:

• text: Testo da cercare (usato come nome se nome omesso)
• role: Filtro ruolo UI — Button, TextBox, CheckBox, MenuItem, ComboBox, e altro ancora
• name: Nome accessibile (ha la precedenza sul testo se entrambi sono forniti)
• windowHandle: Maniglia della finestra target (nullo = finestra in primo piano)

Key features

Desktop interaction

• Click, doppio clic, clic destro e cinque tasti mouse controllo.
• Trascinare e rilasciare con precisione pixel.
• Scorrimento basato su tacche (tre tacche ≈ una pagina).
• Tastiera e scorciatoie multitasto.
• Tracciamento della posizione del cursore.
• Rilevamento della risoluzione dello schermo.

Acquisizione e analisi dello schermo

• Screenshot PNG a schermo intero o ritagliati.
• OCR dello schermo intero con punteggi di fiducia per regione e riquadri di delimitazione.
• Screenshot solo per i contenuti web con vista del browser.

Window management

• Enumerare tutte le finestre visibili con posizioni e dimensioni.
• Attiva Windows tramite fuzzy title match.
• Focalizza le finestre del browser (Edge, Chrome, Firefox) filtrate opzionalmente per URL o titolo.
• Chiusura elegante con protezione per processi critici per il sistema.

Command execution

• Comandi shell sandboxati con una lista di permessi (git, npm, dotnet, python, cargo, node, pip, dir, mkdir, del, copy, move, robocopy, findstr, where, type).
• Esecuzione Python in sandbox fino a 262.144 caratteri di codice.
• Directory di lavoro e controllo del timeout per chiamata (massimo 30 secondi).
• Limiti di risorse e lista di blocchi rafforzata contro i metacaratteri della shell, flag di valutazione, escalation dei privilegi e operazioni distruttive.

Browser automation

• Naviga, indietro, avanti, ricarica.
• Leggi paginaURL, titolo, testo visibile (limite di 512 KB) e HTML completo (limite di 512 KB).
• Query di click, digitazione e testo a livello DOM tramite selettore CSS.
• Aspetta gli elementi dinamici con timeout configurabile.
• Valuta JavaScript le espressioni nel contesto della pagina.
• Gestione multi-scheda: lista, switch, apri, chiudere.
• Gira su Microsoft Edge, avviata automaticamente al primo utilizzo.

UI accessibility

• Recupera il Windows Automazione interfaccia utente tree per la finestra in primo piano con profondità e numero di elementi configurabili.
• Trova gli elementi dell'interfaccia utente per testo, ruolo o nome accessibile.
• Restituisce le coordinate dello schermo cliccabili per il targeting preciso di pulsanti, caselle di testo, caselle di spunta, elementi del menu e caselle combo.

Tempismo e sincronizzazione

• Brevi pausa di one-shot ( mcp_desktop_wait_milliseconds massimo cinque secondi).
• Polling a livello DOM tramite mcp_browser_wait_for (massimo 30 secondi).

Notes

• Tutte le coordinate sono in pixel dello schermo con (0,0) nell'angolo in alto a sinistra. Le coordinate da mcp_desktop_take_screenshot, mcp_desktop_analyze_screen, mcp_accessibility_find_ui_element, e mcp_desktop_list_windows tutte condividono lo stesso spazio di coordinate.
• È attivo un sistema di sicurezza del cursore: se il cursore si sposta entro cinque pixel da qualsiasi angolo dello schermo, le operazioni con il mouse vengono annullate. Evita di puntare ai bordi estremi dello schermo.
• Gli operatori dei tubi shell (|), i punti e virgola (;), i numeri ampersand (&) e la redirezione di uscita (>, <) sono bloccati. Per trasformare l'output del comando, catturalo ed elaboralo con mcp_desktop_execute_python_code.
• Se i flag di valutazione dell'interprete sono bloccati o se python -c "..." e node -e "..." vengono rifiutati, puoi usare mcp_desktop_execute_python_code per Python codice, oppure scrivere codice su un file prima.
• Il comando stdout/stderr è troncato a 32 KB ciascuno. Usa flag per limitare l'output verboso (ad esempio, git log --oneline -20) oppure reindirizza a un file e leggilo separatamente.
• Il timeout massimo per mcp_desktop_execute_shell_command e mcp_desktop_execute_python_code è di 30 secondi. Per lavori più lunghi, suddividilo in passaggi più piccoli o avvia un processo in background da Python e fai sondaggi.
• Non esiste uno strumento dedicato per la lettura/scrittura dei file. Leggi file con mcp_desktop_execute_shell_command usando il comando type; scrivi file con mcp_desktop_execute_python_code usando l'I/O integrato di Python. La redirezione dell'uscita della shell (>, >>) è bloccata.
• mcp_browser_eval_js restituisce sempre una corda. Converti oggetti o numeri esplicitamente prima di restituirli.
• Gli strumenti DOM del browser (mcp_browser_click, mcp_browser_type, mcp_browser_eval_js, ecc.) operano solo sull'istanza Microsoft Edge.  mcp_desktop_focus_browser Può mettere a fuoco le finestre di Chrome o Firefox, ma gli strumenti DOM non le prenderanno di mira.
• mcp_desktop_take_screenshot Richiede tutti e quattro i parametri di ritaglio (x, y, larghezza, altezza) insieme, oppure nessuno per una cattura a schermo intero.
• mcp_desktop_scroll Usa unità a tacca (fissate a [-20, 20]), non pixel. Tre tacche corrispondono a circa una pagina.
• mcp_accessibility_find_ui_element Richiede almeno uno di testo, ruolo o nome. Quando sono forniti sia testo che nome, il nome ha la precedenza.

Casi d'uso comuni

Compila un modulo web

• Chiama mcp_browser_navigate per aprire la pagina target.
• Chiama mcp_browser_wait_for per aspettare che il modulo si carichi.
• Chiamata mcp_browser_type per compilare ogni campo tramite il selettore CSS.
• Chiama mcp_browser_click per inviare il modulo.
• Chiama mcp_browser_wait_for per aspettare l'elemento di conferma.
• Chiama mcp_browser_get_text per leggere e verificare il risultato.

Automatizza un'applicazione desktop

• Chiama mcp_desktop_activate_window per portare la domanda in primo piano.
• Chiamata mcp_desktop_take_screenshot per catturare lo stato attuale.
• Chiama mcp_accessibility_find_ui_element per trovare un pulsante o un campo per nome.
• Chiama mcp_desktop_click le coordinate segnalate dall'elemento.
• Chiama mcp_desktop_type_text per inserire dati.
• Richiedi mcp_desktop_press_keys scorciatoie (ad esempio, ["ctrl","s"] per salvare).
• Chiama mcp_desktop_take_screenshot per verificare il risultato.

Estrae dati da una pagina web

• Chiama mcp_browser_navigate per aprire la pagina.
• Chiamata mcp_browser_get_text per estrarre il contenuto testuale visibile.
• Chiamata mcp_desktop_execute_python_code per analizzare ed elaborare i dati estratti.
• Chiama mcp_browser_eval_js a query valori specifici tramite JavaScript quando l'estrazione del testo non è sufficiente.

Esegui compiti di sviluppo

• Chiama mcp_desktop_execute_shell_command , git pullnpm install, e dotnet build.
• Chiamata mcp_desktop_take_screenshot per catturare l'output della build.
• Chiama mcp_desktop_execute_python_code per analizzare log o risultati di test.
• Chiama mcp_browser_navigate ad aprire un server di sviluppo locale nel browser.
• Chiama mcp_browser_screenshot per catturare la pagina renderizzata.

Leggi e scrivi file

• Leggi un file con mcp_desktop_execute_shell_command usando type C:\path\to\file.txt.
• Scrivi un file con mcp_desktop_execute_python_code usando Python open(...) e write(...).
• Verifica usando mcp_desktop_execute_shell_commanddir C:\path\to\output.txt.

Naviga in un'interfaccia utente complessa con accessibilità

• Chiama mcp_accessibility_get_accessibility_tree per capire tutta la struttura dell'interfaccia utente.
• Chiama mcp_accessibility_find_ui_element per trovare un controllo specifico (ad esempio, ruolo: "MenuItem", nome: "Impostazioni").
• Chiama mcp_desktop_click usando le coordinate riportate dall'elemento.
• Chiama mcp_accessibility_find_ui_element di nuovo per trovare il controllo successivo nel dialogo.
• Chiama mcp_desktop_type_text o mcp_desktop_click interagisci con esso.

Mantenere viva una sessione di lunga durata

• Invia qualsiasi richiesta MCP almeno una volta ogni 30 minuti per evitare lo sfratto inattivo.
• mcp_desktop_get_screen_size è leggero e funziona bene come battito cardiaco.