AI Tools

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:

<#
.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:

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:

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:

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:

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:

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:

"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:

{
  "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.