Skip to main content
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

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.
Windshift 0.8.4 or newer is required, with Windshift’s MCP server enabled (MCP_ENABLED=true).

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

​
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

​
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

An administrator must set the Windshift URL in Settings → Integrations → Windshift server (or set WINDSHIFT_BASE_URL as a fallback on the connector container).
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.
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.
Windshift is personal — confirm that user completed the OAuth connection from My Integrations and that they have access to the workspaces you expect.

​
What’s Next

Search Your Data

Search work items alongside your other sources

Access Control

Understand document and action authorization

Connector Management

Monitor syncs and manage sources