> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/intelligence/ai-tools.md). # AI Tools Expose PowerShell scripts as AI Tools in PowerShell Universal for use by AI Agents and external MCP clients like GitHub Copilot, with authentication, roles, and persistent environments. AI Tools let you expose PowerShell scripts as callable tools for AI Agents and external MCP clients. They are useful when you want a model to retrieve PSU data, run a controlled action, or hand structured output back into a prompt. Each tool can require authentication, enforce roles, choose an execution environment, and optionally be exposed over MCP. ## Create an AI Tool Navigate to **Build > AI > Tools** and select **Create AI Tool**. Select the script to expose, then decide whether the tool should be available: * Only to PSU AI Agents. * To both AI Agents and MCP clients by enabling **MCP**. If **Authenticated** is enabled, the caller must be signed in. If roles are also assigned, the caller must have at least one of those roles. ### Description The description is one of the most important parts of the tool. It should tell the model: * When to use the tool. * What the tool returns. * Whether the tool changes state. * Any important parameter expectations. Short, concrete descriptions work best. ### Parameters Parameters are discovered automatically from the PowerShell script. Comment-based help is strongly recommended because PSU uses it to build better tool descriptions and parameter schemas. This example script makes a good AI Tool because it has clear parameters and predictable output: ```powershell <# .SYNOPSIS Returns the top running processes by CPU usage. .PARAMETER Count The number of processes to return. #> param( [Parameter()] [int]$Count = 5 ) Get-Process | Sort-Object CPU -Descending | Select-Object -First $Count Name, Id, CPU ``` Expose it as a tool: ```powershell New-PSUAiTool -Name 'Get Running Processes' ` -Description 'Returns the top running processes by CPU usage.' ` -ScriptFullPath '/tools/Get-RunningProcesses.ps1' ` -Authenticated ` -Role @('Operator') ` -Mcp ``` Useful cmdlets include: * `Get-PSUAiTool` * `New-PSUAiTool` * `Set-PSUAiTool` * `Remove-PSUAiTool` For example, review tools with: ```powershell Get-PSUAiTool Get-PSUAiTool -Name 'Get Running Processes' ``` ## Run tools in a persistent environment By default, each AI Tool invocation starts a new PowerShell process. For tools called frequently by an AI Agent or MCP client, assign a local environment with **Persistent Runspaces** enabled to reuse the running PowerShell process and avoid process startup for each call. 1. Create or edit an environment under **Manage > Environments > Environments**. 2. Enable **Persistent Runspaces** and choose an appropriate **Max Runspaces** value. 3. Create or edit the AI Tool. On the **Execution** tab, select that environment in **Run In**. You can also assign the environment in configuration with `-Environment`: ```powershell New-PSUAiTool -Name 'Get Running Processes' ` -Description 'Returns the top running processes by CPU usage.' ` -ScriptFullPath '/tools/Get-Running-Processes.ps1' ` -Environment 'Persistent Tools' ` -Mcp ``` Each invocation still creates its own job record, status, and output in **Run > Jobs**. Persistent environments reuse the PowerShell process and retain intentional runspace state between calls, while job output and cancellation remain isolated to the individual invocation. Persistent execution applies to eligible local, non-minimal environments. Remote-agent, PowerShell remoting, container, and Minimal environments continue to use their normal execution paths. Restarting the environment or the PSU server starts a new persistent process, so in-memory runspace state is reset. Use persistent environments only when state reuse is intentional, and set the runspace limit to the concurrency your tools require. ## Using a Tool in AI Agents Within an AI Agent, assign tool names directly or use wildcard patterns such as `ticket_*` or `*`. PSU only makes the matching tools available to that agent. Role-based access is enforced at both levels: * The user must be allowed to run the agent. * The user must also be allowed to run the tool. Tool executions started by an agent appear as child jobs of the AI prompt job. Example agent configuration: ```powershell Set-PSUAiAgent -Name 'SupportAgent' -Tool @('Get Running Processes', 'ticket_*') ``` ## Using a Tool over MCP Model Context Protocol (MCP) allows remote clients such as GitHub Copilot to discover and call your tools. PSU exposes MCP at `/api/v1/mcp`. Only tools with **MCP** enabled are listed to MCP clients. When exposed over MCP, tool names are normalized for the client. For example, spaces and periods are converted to underscores. When an MCP client connects, PSU filters visible tools based on: * Whether the tool is marked for MCP. * Whether the caller is authenticated when required. * Whether the caller has at least one required role. Calls made through MCP appear as MCP jobs in the Jobs page. If your client supports bearer tokens, provide a PSU app token when connecting to the MCP endpoint. ## Access in GitHub Copilot GitHub Copilot can call PSU tools when VS Code is configured to connect to the PSU MCP server. In this example, the tool wraps a script that returns running processes: ```powershell Get-Process | Select-Object Name, Id ``` With the MCP extension enabled, press `Ctrl+Shift+P` and run `MCP: Add Server...`. Choose the HTTP option and enter the MCP endpoint URL. By default, this is `http://localhost:5000/api/v1/mcp`. The resulting `settings.json` contents will look something like this: ```json "mcp": { "servers": { "PSU": { "url": "http://localhost:5000/api/v1/mcp" } } } ``` If the connection is successful, Copilot shows the number of available tools. You can then ask Copilot to use the PSU tool. For example: ``` Use the PSU tool to list the top 5 processes and create a PowerShell script that writes them to JSON. ``` If you also expose a tool that starts a process, a prompt like this can trigger that action: ``` Use the PSU tool to start a new process named calc. ``` Keep tool descriptions and parameter help clear so Copilot can choose the correct tool without trial and error. ## Name MCP server connections PowerShell Universal identifies its MCP server as `Universal.Server` by default. Set a distinct name for each environment so multiple PowerShell Universal MCP connections are easy to distinguish in Visual Studio Code. Configure the name in `appsettings.json`: ```json { "Mcp": { "ServerName": "Production PSU" } } ``` For containerized or environment-variable-based deployments, use: ``` Mcp__ServerName=Production PSU ``` Leave the setting blank or unspecified to preserve the default `Universal.Server` name. ## Govern AI and MCP access Use the global AI and MCP settings to bound server capacity and to disable AI capabilities when they are not permitted in an environment. ### Limit MCP requests and jobs Go to **Settings gear > Automation** to configure: * **MCP requests per minute**: Requests above the configured rate are rejected before execution. * **MCP concurrent jobs**: Additional MCP jobs wait until an execution slot is available. A value of `0` means unlimited. Negative values are not valid. Set both limits according to the capacity available to PowerShell Universal and the scripts exposed as MCP tools. ### Disable AI features Select **Disable AI Features** under **Settings gear > Automation** to disable AI capabilities for the server. This hides AI Agents, AI Tools, and AI Chat in the admin console. Disabling AI also removes the MCP endpoint from new endpoint registration and returns `404 Not Found` for requests to `/api/v1/mcp` immediately. A server restart is not required. For configuration scripts, use `Set-PSUSetting -DisabledFeatures` to manage disabled product features. `-Features` remains an alias for existing configurations. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/intelligence/ai-tools.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.