workiq-proxy

Extends Microsoft Work IQ with broad MCP client support, structured search tools, an interactive REPL, and an OpenAI-compatible HTTP API.

What it does

workiq-proxy enhances Work IQ's MCP server so it works seamlessly with Claude Code, VS Code, Codex, and other MCP clients.

In MCP mode the proxy sits between the MCP client and the Work IQ server:

MCP Client <-stdio-> workiq-proxy <-stdio-> workiq mcp

It:

1. Extends MCP capabilities — Adds support for prompts/list, resources/list, and resources/templates/list so every MCP client connects cleanly

2. Advertises full capabilities — Ensures clients see a fully capable server during initialization

3. Future-proof — Automatically steps aside when Work IQ gains these capabilities natively

4. Error enrichment — Wraps opaque errors with troubleshooting context (EULA not accepted, token protection / error 530084, Entra ID conditional access / AADSTS, interactive login required, and "Failed to create conversation")

5. Synthetic tools — Exposes 7 domain-specific tools (search_emails, search_documents, search_chats, search_channels, search_meetings, search_people, search_external) backed by ask_work_iq

6. Interactive REPL — When run from a terminal with no arguments, launches a Bubble Tea UI with slash commands (/ask, /emails, /docs, /chats, /channels, /meetings, /people, /accept-eula, /tools, /help, /quit), session history, and glamour markdown rendering

7. OpenAI-compatible HTTP API — workiq-proxy serve starts a local server with /v1/chat/completions (streaming and non-streaming) and /v1/models

8. CLI passthrough — When run from an interactive terminal with arguments, delegates to the underlying workiq CLI (EULA acceptance, auth, queries) so you only need one package

9. Traffic logging — Logs all JSON-RPC messages to ~/.work-iq-cli/mcp-traffic.log

Related MCP server: MCP Server with OpenAI Integration

Install

curl -fsSL https://stuffbucket.github.io/workiq-proxy/install.sh | sh

The installer detects (or installs) Node.js and sets up workiq-proxy via npm.

On Windows (PowerShell):

irm https://stuffbucket.github.io/workiq-proxy/install.ps1 | iex

Alternatively, install directly with npm:

npm install -g @stuffbucket/workiq-proxy

This also installs @microsoft/workiq as a dependency — no separate setup needed. The npm package provides both workiq-proxy and wiq as binaries.

Or download a binary from GitHub Releases and place it in your PATH.

Prerequisites

Before using the proxy, set up Work IQ from your terminal:

# First run: accepts EULA interactively, then triggers browser auth
npx -y @stuffbucket/workiq-proxy ask

The interactive session walks you through EULA acceptance and signs you in via the browser. Once complete, the MCP server reuses cached tokens silently.

You can also accept the EULA directly:

npx -y @stuffbucket/workiq-proxy accept-eula

To verify auth works non-interactively:

npx -y @stuffbucket/workiq-proxy ask -q "What's on my calendar?"

Commands

Configure

Claude Code

Project-level (adds to .mcp.json in current directory):

claude mcp add --transport stdio workiq --scope project -- npx -y @stuffbucket/workiq-proxy

User-level (available in all projects):

claude mcp add --transport stdio workiq --scope user -- npx -y @stuffbucket/workiq-proxy

Or add to .mcp.json manually:

{
  "mcpServers": {
    "workiq": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stuffbucket/workiq-proxy"]
    }
  }
}

VS Code / GitHub Copilot

Project-level — add to .vscode/mcp.json:

{
  "servers": {
    "workiq": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stuffbucket/workiq-proxy"]
    }
  }
}

User-level — add to VS Code user settings (settings.json):

{
  "mcp": {
    "servers": {
      "workiq": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@stuffbucket/workiq-proxy"]
      }
    }
  }
}

OpenAI Codex CLI

Add to .codex/mcp.json:

{
  "mcpServers": {
    "workiq": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stuffbucket/workiq-proxy"]
    }
  }
}

Flags

Example with a globally installed Work IQ CLI:

{
  "mcpServers": {
    "workiq": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stuffbucket/workiq-proxy", "--workiq-cmd", "workiq"]
    }
  }
}

Verify

After configuring, check that the server connects:

• Claude Code: Run /mcp to see server status and available tools

• VS Code: Check the MCP server status in the output panel

You should see 9 tools: accept_eula, ask_work_iq, plus the 7 synthetic search tools.

Troubleshoot

The proxy enriches five categories of upstream errors with actionable hints:

Server not connecting — Check ~/.work-iq-cli/mcp-traffic.log for the full JSON-RPC transcript.

Development

# Build
make build

# Test
make test

# Lint (Go + JS)
make lint

# Cross-compile all platforms
make all

Programmatic API

Use workiq-proxy as a dependency to embed Work IQ in your own Node.js project:

npm install @stuffbucket/workiq-proxy

Pipe-based (no port, no network)

const { createClient } = require("@stuffbucket/workiq-proxy");

const client = await createClient();
const answer = await client.ask("What's on my calendar?");
console.log(answer);

const emails = await client.searchEmails({ from: "alice", date_range: "last week" });
const docs   = await client.searchDocuments({ keywords: "quarterly report" });
const chats  = await client.searchChats({ person: "bob", keywords: "standup" });

await client.close();

createClient() spawns workiq-proxy over stdio pipes — no port, no HTTP. The MCP handshake happens automatically.

Options: createClient({ workiqCmd?, noLog? })

HTTP server (OpenAI-compatible)

If you need an HTTP API (e.g. for non-Node consumers):

const { createServer } = require("@stuffbucket/workiq-proxy");

const server = await createServer();           // starts serve --json
const models = await server.listModels();      // /v1/models
const reply  = await server.chat("What's on my calendar?");
console.log(reply.choices[0].message.content);
await server.close();

Options: createServer({ port?, workiqCmd?, noLog? })

License

MIT — see LICENSE. Charmbracelet libraries are used under the MIT license (see third-party notices in LICENSE).