---
title: "Connect AI tools with MCP"
description: "Connect Claude or another MCP client to your Outpost so it can work as you, with your permissions and your approval for high-impact actions."
url: "https://support.outpostplatform.com/pioneer-ai/mcp-server/"
product: "depot"
type: "how-to"
status: "draft"
ai_summary: "Preview. Outpost serves an MCP server at <your-address>/mcp with OAuth 2.1 sign-in. A connected app acts as the signed-in user with that user's permissions. Calls are read, write, or high risk; high-risk calls need the person's approval. Secrets, recordings, exports, payment changes, and sign-in settings are never allowed. Covers Claude Code, Claude.ai, tools, limits, and ai:mcp_control."
availability:
  plans: ["home-lab", "essentials", "enterprise", "msp"]
  permission: "ai:use"
  preview: true
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/pioneer-ai/mcp-server.md"
license: "CC BY 4.0"
---

# Connect AI tools with MCP

The Model Context Protocol (MCP) is an open standard that lets an AI app, such
as Claude, call tools that another system provides. Your Outpost runs an MCP
server, so an AI app you connect can look up endpoints, work tickets, and run
commands as you. This page explains what a connected app can and cannot do,
and shows how to connect Claude Code, Claude.ai, or another MCP client.

## How it works

Your Outpost serves MCP at `https://<your-address>/mcp`, where `<your-address>`
is the address you sign in to the console at. The **AI connections** page shows
the exact URL.

- **Sign-in.** The app signs in with OAuth 2.1. The first time it connects, it
  opens your browser at your Outpost, you sign in to the console, and you
  approve the app. You never give the app your password.
- **Your permissions.** A connected app acts as you. It can do what your roles
  let you do and nothing more, and every check that applies to you in the
  console applies to it, including your plan, your
  [access rules](/depot/access-rules/), and the clients you can reach.
- **Your approval for high-impact actions.** Before the app runs anything
  high-impact, you see exactly what it will do and approve or deny it.
- **A record of every call.** Every call an app makes, including refused ones,
  appears under **Recent activity** on **Settings** > **AI**. Changes it makes
  appear in the [audit log](/depot/audit-log/) like your own.

Unlike [Pioneer AI](/pioneer-ai/), MCP sends nothing to a model provider from
your Outpost. The AI app you connect decides where its conversation goes, under
that app's own terms. What a tool returns to the app becomes part of that
conversation.

## Risk tiers

Every tool call falls into one of three tiers.

| Tier | What it covers | Approval |
| --- | --- | --- |
| Read | Looking things up: endpoints, software, alerts, tickets, patches, scripts, documentation | None |
| Write | Routine changes: acknowledging alerts, creating and updating tickets, adding ticket messages, logging time, making a ticket the child of another, editing documentation and tags, refreshing inventory, scanning for patches | None |
| High | Everything else that changes something, including running commands, scripts, and shell input, endpoint actions, wake, approving and applying patches, deploying software, merging tickets, removing a ticket from its parent, every delete, and changes to users, roles, profiles, and policy | Yours, for every call |

When a high-risk call needs approval, Outpost asks in the first way your app
supports:

1. A link the app opens to the **Approve an AI action** page in your console.
2. A confirmation prompt inside the app.
3. A message from the app asking you to open the approval link and then ask
   it to try again.

The **Approve an AI action** page shows the tool, the clients and endpoints it
targets, the script and its version, and the exact command or request body.
Values whose names look like secrets, such as a `password` or `apiKey` field,
show as **(hidden)**. Select **Approve** or **Deny**. Only you can answer an
approval for your own app. An approval works once, for exactly the request
shown, and expires after 10 minutes. If the script changes after you approve,
the app has to ask again.

An app waits about a minute for your decision, because MCP apps give up on a
call that takes much longer. If you have not decided by then, the app is
answered with the approval link instead. Approve the request, then ask the app
to try again. The retried call, with the same arguments, runs once.

## Actions that are never allowed

Some actions are refused for every AI app, whatever the person's permissions.
The app gets **This action can never be performed by an AI tool. Use the
Outpost console.** They include:

- Revealing secrets: vault credentials, their TOTP codes and history, hidden
  fields in documentation, BitLocker and other recovery keys, and backup keys.
- Playing or downloading remote session recordings.
- Exports, such as documentation exports and the organization data export.
- Billing and payment changes, and recording payments on client invoices.
- Sign-in and account security: passwords, two-factor authentication,
  passkeys, invitations, access rules, and the organization security policy.
- Changing Pioneer AI settings, AI budgets, a client's AI override, or AI
  connections themselves.
- Chatting with Pioneer AI.
- Transferring files to or from an endpoint. An app can read and write text
  files only through `run_command`.

## Tools

On the MSP plan, tools that act on one client take a `clientId`. Ask the app to
list clients first. A client whose AI access is off is left out of every list,
and a call that names it is refused with **Client** followed by its name and
**has AI access turned off by your organization's policy.**

| Area | Tools |
| --- | --- |
| You and your clients | `whoami`, `list_clients` (MSP plan) |
| Endpoints | `find_endpoints`, `get_endpoint`, `endpoint_software`, `endpoint_connection_history`, `refresh_inventory`, `endpoint_action`, `wake_endpoint`, `bulk_move_endpoints_to_site`, `bulk_update_device_group_members` |
| Commands | `run_command`, `get_command_result`, `list_commands` |
| Shell | `shell_open`, `shell_send`, `shell_read`, `shell_close` |
| Scripts | `search_scripts`, `get_script`, `run_script`, `get_script_batch`, `cancel_script_batch` |
| Alerts | `list_alerts`, `get_alert`, `get_alert_counts`, `acknowledge_alert` |
| Tickets | `list_tickets`, `get_ticket`, `create_ticket`, `update_ticket`, `add_ticket_message`, `log_time`, `merge_tickets`, `link_child_ticket`, `unlink_child_ticket` |
| Contacts | `list_contact_tags`, `list_client_contacts`, `set_contact_tags` |
| Scheduling | `list_my_day` (MSP plan) |
| Workflows | `list_workflows`, `get_workflow`, `create_workflow`, `update_workflow`, `delete_workflow`, `duplicate_workflow`, `resume_workflow`, `test_workflow`, `list_workflow_runs`, `list_workflow_library`, `install_workflow_preset`, `get_workflow_settings`, `update_workflow_settings`, `get_workflow_registry`, `get_workflow_references` |
| Notifications | `list_my_notifications`, `mark_notifications_read` |
| Timesheets | `get_timesheet_week`, `add_timesheet_entry`, `submit_timesheet`, `review_timesheets`, `start_timer`, `stop_timer`, `list_time_categories` (MSP plan). See [Timesheet reference](/msp/timesheet-reference/#mcp-tools). |
| Patches | `list_patches`, `scan_patches`, `approve_patches`, `apply_patches` |
| Software | `list_software_catalog`, `deploy_software` |
| Documentation | `search_docs`, `get_kb_article` |
| Network maps | `get_network_topology`, `trace_network_path`, `topology_changes`, `check_diagram_drift`, `list_doc_diagrams`, `read_doc_diagram`, `list_network_diagrams`, `get_diagram_drift`. See [Network maps with Pioneer AI and MCP](/network-maps/pioneer-and-mcp/). |
| Anything else | `search_operations`, `describe_operation`, `call_operation` |

The last three reach any other console API operation you have permission for,
under the same tiers and the same never-allowed list. `run_command` and
`run_script` wait up to 60 seconds for a result by default, and up to 300
seconds when asked. Command output is cut at 64 KB. An app can hold up to 3
shells at a time.

`shell_open` opens a shell as the agent's account by default. With `runAs`
set to `user`, it opens the shell as the person signed in at the endpoint,
under the same rules as the console's terminal. The approval request says the
shell runs as the signed-in user. See
[Run as the agent or the signed-in user](/remote-access/terminal/#run-as).

What to know about the ticket and scheduling tools:

- `log_time` can post a note with the time. A note that is not internal is a
  public reply, and the requester is emailed when the public reply
  notification is on. Without a charge type, the entry
  gets the client agreement's default charge type, or Labor.
- `merge_tickets` cannot be undone, and is refused while the ticket has child
  tickets. It is high risk and needs `ticket:admin`.
- `link_child_ticket` makes a ticket the child of another, so public replies
  on the parent, and solving or closing it, carry to the child. It is a write.
  `unlink_child_ticket` is high risk.
- `list_my_day` lists your appointments for one day, today by default, in
  the same time zone **My day** uses: your profile's time zone, else the
  practice's, else UTC. Pass `timeZone` (an IANA name such as
  `America/Chicago`) to use another. It needs `project:calendar`.

What to know about the contact tools:

- `list_contact_tags` lists the contact tags a client has, such as **Primary
  contact** and **VIP**. `list_client_contacts` lists the client's people,
  with their phone, title, and tags, and takes an optional `contactTag` code
  to list only the people who hold it. Both are reads.
- `set_contact_tags` replaces the whole set of tags one person holds. Giving
  someone a single-holder tag such as **Primary contact** moves it from
  whoever held it. It is high risk and needs `identity:manage`. See
  [Client contacts, sites, and contact tags](/msp/contacts-and-sites/).

What to know about the workflow and notification tools:

- Every workflow tool needs `automation:manage`. On the MSP plan they work on
  your practice's workflows and take no `clientId`. See
  [Workflows](/service-desk/workflows/).
- `get_workflow_registry` returns the fields, operators, steps, recipients,
  and placeholders each trigger allows, and `get_workflow_references` the
  queue, group, schedule, and template names in your clients, so an app can
  write a workflow definition that saves. See
  [Workflow reference](/service-desk/workflow-reference/).
- The reads are `list_workflows`, `get_workflow`, `list_workflow_runs`,
  `list_workflow_library`, `get_workflow_settings`, `get_workflow_registry`,
  and `get_workflow_references`. `test_workflow` is a write, and changes
  nothing. Every other workflow tool is high risk.
- `update_workflow_settings` sets **Pause all workflows** and the two
  **Safety limits**: actions per workflow per hour, and client emails per
  ticket per day.
- `list_my_notifications` and `mark_notifications_read` work on the signed-in
  person's own notifications only, and need no permission.
  `mark_notifications_read` is a write. See
  [Notifications](/depot/notifications/).

What to know about the timesheet tools:

- `log_time` and `stop_timer` are refused with **This week's timesheet is
  approved. Ask a manager to reopen it.** when the time falls in a week whose
  timesheet is approved.
- `review_timesheets` approves or returns weeks and is high risk. Approving
  needs each week's total exactly as `get_timesheet_week` read it, so the app
  cannot approve hours nobody looked at. It needs `timesheet:approve`.

## Before you begin

- You need the `ai:use` permission. Every role has it by default. Without it
  the app gets **Your role does not include AI tools.**
- Add a second factor to your account: an authenticator app or a passkey.
  Approving a connection asks you to confirm it. See
  [Manage your console account](/depot/account-security/).
- **Allow AI tools to connect** must be on under **AI tools (MCP)** on
  **Settings** > **AI**. It is on by default. On the MSP plan, AI tools cannot
  connect while the client policy is **Off for all clients**.
- You cannot approve a connection from an emergency sign-in.

## Connect Claude Code

1. In the console, open the profile menu in the header and select **AI
   connections**.
2. Under **Set up an app**, select **Claude Code** and copy the command. It
   has this form:

   ```bash
   claude mcp add --transport http outpost https://<your-address>/mcp
   ```

3. Run the command in a terminal.
4. In Claude Code, enter `/mcp` and choose **outpost**.
5. In the browser page that opens, sign in to the console if asked, check the
   app name and where it returns to, and select **Approve**. Confirm with your
   authenticator app or passkey when asked. **Deny** refuses the connection.

## Connect Claude.ai

1. In the console, open the profile menu and select **AI connections**. Copy
   the URL under **Server URL**.
2. In Claude, open **Settings** > **Connectors**.
3. Select **Add custom connector**.
4. Name it `Outpost` and paste the server URL.
5. Select **Connect**, then sign in to Outpost and approve.

## Connect another MCP client

Most MCP clients read a configuration like this one, which the **Other MCP
clients** tab on **AI connections** shows with your URL:

```json
{
  "mcpServers": {
    "outpost": {
      "type": "http",
      "url": "https://<your-address>/mcp"
    }
  }
}
```

The client opens a browser for you to sign in the first time it connects.

The same sign-in also issues tokens for the Outpost REST API. A script that
signs in this way calls the API as you, with the same tiers. A high-risk REST
call is answered with an approval link. Approve it, then send the identical
request again with the header `X-Outpost-Approval` set to the approval ID.

## Saved prompts

The [saved prompts](/pioneer-ai/use-pioneer-ai/#use-a-saved-prompt) you can
use in Pioneer AI, your own and the shared ones, are also offered to a
connected app as MCP prompts. Each prompt's name is its command, such as
`triage`. In Claude Code, they appear as slash commands such as
`/mcp__outpost__triage`. Apps can read prompts but not change them. Add and
edit them on **Settings** > **AI** > **Prompts**.

## Verify

Ask the app who it is signed in as. It calls `whoami` and answers with your
console account. The app appears under **Connected apps** on **AI
connections**.

## Manage connections

- **Disconnect one of your apps.** On **AI connections**, under **Connected
  apps**, select **Disconnect**. The app is signed out at once. App names are
  chosen by the apps themselves, so a name is marked **Unverified name** unless
  the app is part of Outpost.
- **See every connection.** On **Settings** > **AI**, **Connected apps** lists
  every person's apps, and **Recent activity** lists every call. Viewing them
  needs `ai:manage`. Disconnecting another person's app needs `ai:mcp_control`,
  which the owner holds by default. On an MSP's practice console, every role
  that holds `billing:manage` has it.
- **Turn AI tools off.** Turn off **Allow AI tools to connect**. Every
  connected app stops at its next call.
- **Unguarded mode.** On **Settings** > **AI**, a person with `ai:mcp_control`
  can let one person's apps run high-risk calls without asking first. It skips
  approval only. Permissions and the never-allowed list still apply. Turning
  it on needs a code from your authenticator app and typing the person's name.
  Where the server does not offer it, the card says **Not available on this
  server yet.**

A connection ends on its own after 30 days without use, and after 90 days in
any case. If your organization's [security policy](/depot/security-policy-preview/)
sets **Idle timeout (minutes)** or **Maximum length (hours)** below its
default, connections follow the shorter limit instead. A connection also ends
when you change your password, when you are signed out everywhere, when your
account is disabled, and when someone saves a stricter security policy.
Connect the app again to continue.

While your account is locked after too many failed sign-ins, your connections
are refused. They work again once the lock runs out, without reconnecting.

## Limits

- 120 calls a minute, and 20 high-risk calls in 10 minutes, for each
  connection and for each person.
- A result larger than 100 KB of text is cut short, with **Result truncated.
  Narrow your query.**
- Over a limit, the app gets **Too many AI tool calls. Try again in** a number
  of seconds.

## If something goes wrong

| What the app reports | Cause | Fix |
| --- | --- | --- |
| **AI tools are turned off for your organization. An owner can turn them on in Settings > AI.** | **Allow AI tools to connect** is off. | Ask someone with `ai:manage` to turn it on. |
| **AI access is turned off by your organization's policy.** | On the MSP plan, the client policy is **Off for all clients**. | See [Choose which clients get Pioneer AI](/pioneer-ai/set-up/#choose-which-clients-get-pioneer-ai). |
| **This AI connection was signed out or revoked. Reconnect to continue.** | The connection was disconnected or expired. | Connect the app again. |
| **The action was not approved. Nothing was changed.** | You denied the approval or let it expire. | Ask the app to try again and approve it. |
| **Connecting AI tools asks for a second factor, such as an authenticator app or a passkey. Add one in Security to continue.** | Your account has no second factor. | Add an authenticator app or a passkey. See [Manage your console account](/depot/account-security/). |

## Next steps

- [Pioneer AI](/pioneer-ai/)
- [Roles and permissions](/depot/roles-and-permissions/)