> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getomni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Windshift

> Connect Windshift work items to Omni for personal search and MCP-powered actions

The Windshift connector indexes the work items, descriptions, and comments a user can see in Windshift, and exposes Windshift's MCP tools as Omni actions. Windshift is a **personal source**: every user connects their own account, runs an independent sync, and sees only their own indexed items.

## Overview

### What Gets Indexed

| Windshift                  | Omni document                                         |
| -------------------------- | ----------------------------------------------------- |
| Item ID                    | `external_id = windshift:item:<id>`                   |
| Title                      | Document title                                        |
| Description and comments   | Markdown content                                      |
| Workspace                  | `attributes.workspace`                                |
| Status                     | `attributes.status`                                   |
| Priority                   | `attributes.priority`                                 |
| Assignee                   | `attributes.assignee` and `attributes.assignee_email` |
| Milestone and iteration    | `attributes.milestone` and `attributes.iteration`     |
| Created/updated timestamps | Document metadata                                     |

Full sync walks the workspaces visible to the connecting user while capturing each workspace's change watermark. Incremental sync then reads Windshift's ordered item change log, including comment activity and deletions.

### How It Works

1. An administrator sets the externally reachable Windshift base URL once for the instance.
2. Omni dynamically registers itself as a public OAuth client (no client ID or secret to manage), uses S256 PKCE, and binds every token to the Windshift MCP resource.
3. Each user connects Windshift from **My Integrations**. The initial authorization grants read access for that user's sync and read-only MCP tools; write and destructive tools request expanded authorization the first time they are used.

<Note>
  Windshift 0.8.4 or newer is required, with Windshift's MCP server enabled (`MCP_ENABLED=true`).
</Note>

## Prerequisites

* **Windshift 0.8.4+** with the MCP server enabled
* **Admin access** to Omni to set the Windshift server URL
* **A user account in Windshift** for each person who wants to search Windshift content
* Omni deployment with the Windshift connector service running (profile: `windshift`)

## Setup

### Step 1: Configure the Windshift server URL (admin)

Windshift is configured in the admin UI, not through environment variables:

1. Open **Settings** → **Integrations**.
2. Find the **Windshift server** card on the **Sources** tab and click **Configure**.
3. Enter the externally reachable Windshift base URL, e.g. `https://windshift.example.com`. If Windshift uses a context path, include it.
4. Save.

The URL is validated against Omni's SSRF policy — only `http(s)`, no credentials or fragments, and the resolved address must be publicly routable. The setting is stored in the database and read by the connector from connector-manager, so changes propagate without a container restart.

<Note>
  Deployments that predate the UI setting can still set `WINDSHIFT_BASE_URL` on the connector container as a fallback. The UI setting wins when both are present.
</Note>

#### Optional: internal route for server-to-server traffic

To keep client registration, token exchange, user-info, sync, and MCP traffic off the public network, set `WINDSHIFT_INTERNAL_BASE_URL` on the connector container to a private route to the same Windshift instance, e.g. `http://windshift:8080` on the Compose network. This is intentionally environment-only and cannot be set from the UI.

When set, the connector advertises it in its manifest and Omni's OAuth flow allows that exact origin (scheme + host + port) to resolve to RFC1918 addresses; loopback, link-local/metadata, and reserved ranges are still rejected, and every other endpoint must remain publicly routable. Browser authorization, resource binding, and document links always use the public URL.

### Step 2: Connect Windshift (each user)

1. Open **My Integrations** and select **Windshift**.
2. Click **Continue to Windshift** to start the OAuth flow.
3. Sign in to Windshift and approve the requested scopes.
4. Return to Omni. The connector starts syncing the workspaces you can access.

Access tokens are refreshed automatically, and rotated refresh tokens are persisted under the same per-credential database lock.

## Managing the Integration

### Restricting Sync

To restrict sync to specific Windshift workspaces, set the source's `workspace_keys` option to a list of workspace keys (omit it to sync all visible workspaces).

### Search Operators

| Operator     | Meaning                 |
| ------------ | ----------------------- |
| `status:`    | Filter by item status   |
| `priority:`  | Filter by item priority |
| `assignee:`  | Filter by assignee      |
| `workspace:` | Filter by workspace     |
| `milestone:` | Filter by milestone     |
| `iteration:` | Filter by iteration     |

### MCP Actions

Windshift has no static action list. Omni discovers the tools exposed by your Windshift MCP server after the first sync and surfaces them as source-scoped actions — for example `list_items`, `transition_item`, and `add_comment`. Read-only tools use the read scope from the initial authorization; write and destructive tools request expanded authorization when first used.

## Permissions

Windshift is a personal source. Each user's sync is backed by their own OAuth credential, and indexed items are visible only to that Omni user. Actions also run with the connecting user's Windshift identity, so tools can only see and change what that user can see and change in Windshift.

## Removing the Integration

1. Open **My Integrations** and remove the Windshift connection.
2. Revoke the Omni app in Windshift if you no longer want it authorized.

Removing the connection stops syncing and removes that user's indexed Windshift documents.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sync fails with Windshift base URL is not configured">
    An administrator must set the Windshift URL in **Settings** → **Integrations** → **Windshift server** (or set `WINDSHIFT_BASE_URL` as a fallback on the connector container).
  </Accordion>

  <Accordion title="Connection or token exchange fails behind a private network">
    If Omni reaches Windshift over a private route, set `WINDSHIFT_INTERNAL_BASE_URL` on the connector container. Browser-facing authorization still uses the public URL.
  </Accordion>

  <Accordion title="No MCP actions appear">
    Confirm the Windshift version is 0.8.4 or newer and that Windshift's MCP server is enabled. Omni discovers tools after the connector's first successful sync.
  </Accordion>

  <Accordion title="A user sees no Windshift content">
    Windshift is personal — confirm that user completed the OAuth connection from **My Integrations** and that they have access to the workspaces you expect.
  </Accordion>
</AccordionGroup>

## What's Next

<CardGroup cols={3}>
  <Card title="Search Your Data" icon="magnifying-glass" href="/user-guide/search">
    Search work items alongside your other sources
  </Card>

  <Card title="Access Control" icon="shield" href="/user-guide/access-control">
    Understand document and action authorization
  </Card>

  <Card title="Connector Management" icon="gear" href="/admin/connector-management">
    Monitor syncs and manage sources
  </Card>
</CardGroup>