> 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/built-in-mcp-tools.md).

# Built In MCP Tools

Use PowerShell Universal built-in MCP tools to inspect and manage resources, repository files, notifications, jobs, and portal controls.

PowerShell Universal includes built-in MCP tools at `/api/v1/mcp`. They help MCP clients inspect the PowerShell Universal configuration repository, discover cmdlets, read job output and notifications, and apply supported repository changes.

Built-in tools are separate from custom AI Tools. Connect an MCP client to `/api/v1/mcp` and authenticate with a PowerShell Universal app token.

## Connect from Visual Studio Code

GitHub Copilot can call the built-in tools when Visual Studio Code is connected to the PowerShell Universal MCP server.

Press `Ctrl+Shift+P`, run **MCP: Add Server...**, select **HTTP**, and enter the MCP endpoint URL. By default, the URL is `http://localhost:5000/api/v1/mcp`.

The resulting `settings.json` configuration looks like this:

```json
"mcp": {
  "servers": {
    "PSU": {
      "url": "http://localhost:5000/api/v1/mcp"
    }
  }
}
```

To authenticate with a PowerShell Universal app token, include it as a bearer token in the `Authorization` header:

```json
"mcp": {
  "servers": {
    "PSU": {
      "url": "http://localhost:5000/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-app-token>"
      }
    }
  }
}
```

Replace `<your-app-token>` with a token for the PowerShell Universal user and roles the client should use. Do not commit a configuration containing a real app token to source control.

If the connection succeeds, GitHub Copilot displays the available PowerShell Universal tools.

## Access control

Most built-in tools require the **Administrator** or **Operator** role. `search_ant_design_controls` also supports the **App Editor** role. `get_job_output_by_id` requires an authenticated user and verifies that user has permission to read the requested job or its configured read permission.

Use a dedicated app token with only the role required by the MCP client. Repository write tools can create, update, move, and delete configuration files, so do not grant Administrator or Operator access to an untrusted MCP client.

## Typical flow

1. Call `list_resource_types` and `list_resources` to identify the configuration resource.
2. Use the repository and command tools to inspect the relevant files and cmdlets.
3. Apply a deliberate repository change with a write tool when authorized.
4. Call `reload_resource` to reload the affected resource.
5. Use `get_notifications` or `get_job_output_by_id` to verify the result.

## Resource and command tools

| Tool                  | Description                                                           |
| --------------------- | --------------------------------------------------------------------- |
| `list_resource_types` | Lists available PowerShell Universal resource types.                  |
| `list_resources`      | Lists resources of a selected type, with wildcard filtering.          |
| `reload_resource`     | Reloads a selected resource type after a configuration change.        |
| `list_commands`       | Lists commands from a PowerShell module.                              |
| `command_help`        | Returns focused or full help for a command, parameters, and examples. |
| `list_app_commands`   | Lists Universal App-development cmdlets.                              |

## Repository and operational tools

### Repository tools

The following tools inspect and manage repository-relative files and directories:

| Tool                      | Description                             |
| ------------------------- | --------------------------------------- |
| `list_files`              | Lists files and directories.            |
| `search_files`            | Searches file and directory names.      |
| `search_file_content`     | Searches repository file contents.      |
| `get_file_content`        | Reads a repository file.                |
| `set_file_content`        | Replaces a repository file's content.   |
| `new_file_system_item`    | Creates a repository file or directory. |
| `move_file_system_item`   | Moves or renames a repository item.     |
| `delete_file_system_item` | Deletes a repository item.              |

All paths are repository-relative. Use the discovery tools before changing a file, and call `reload_resource` after an authorized configuration change.

### Operational tools

| Tool                         | Description                                                                              |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| `get_notifications`          | Returns recent notifications, optionally filtered by read state, level, time, or cursor. |
| `get_job_output_by_id`       | Returns pipeline or job-stream output when the caller is allowed to read that job.       |
| `search_ant_design_controls` | Searches available Ant Design and PSBlazor portal controls and returns their parameters. |

## Tool limits and run targets

PowerShell Universal supports optional per-minute MCP tool rate limiting and an optional concurrent-job limit for AI tool jobs. Configure these limits in the server settings to protect the instance from excessive tool activity.

Custom AI Tools can also define **Run In** and **Run On** targets. These settings control the environment and computer or computer group used when a custom tool starts a job. They do not change the authorization requirements of the built-in MCP tools listed on this page.

## Examples

Use resource discovery before editing configuration:

```
list_resource_types
list_resources(type: "scripts", filter: "Inventory*")
get_file_content(path: "scripts/Inventory.ps1")
```

After an authorized update, reload and inspect notifications:

```
set_file_content(path: "scripts/Inventory.ps1", content: "<new script content>")
reload_resource(resourceType: "scripts")
get_notifications(unreadOnly: true, levels: "Warning,Error")
```


---

# 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/built-in-mcp-tools.md?ask=<question>&goal=<endgoal>
```

`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.