{
  "markdown": "# Slack ↔ WxO MCP Gateway\n\n**Author:** Markus van Kempen  \n**Email:** [mvankempen@ca.ibm.com](mailto:mvankempen@ca.ibm.com) · [markus.van.kempen@gmail.com](mailto:markus.van.kempen@gmail.com)  \n**Web:** [https://markusvankempen.github.io/](https://markusvankempen.github.io/) · [GitHub](https://github.com/markusvankempen)\n\n**npm:** [`@markusvankempen/slack-wxo-mcp-gateway`](https://www.npmjs.com/package/@markusvankempen/slack-wxo-mcp-gateway) · **MCP:** `io.github.markusvankempen/slack-wxo-mcp-gateway`\n\n> **This GitHub repo is documentation + registry metadata.** It does **not** include the runnable application source.  \n> **Install / run via npm:** `npx -y @markusvankempen/slack-wxo-mcp-gateway` · Site: [https://markusvankempen.github.io/](https://markusvankempen.github.io/)\n\n**Pitch:** MCP gateway that **lifts watsonx Orchestrate Slack limitations** — every-message wake-up, multi-channel→multi-agent routing, clean in-thread replies, and a streamable-http toolkit for WxO + Cursor / VS Code / Bob / Antigravity — without replacing your agents.\n\n`tags:` `wxo-limitations` · `byo-slack` · `every-message` · `multi-channel` · `multi-agent` · `thread-followups` · `gateway-thread` · `no-done-noise` · `mcp-toolkit` · `streamable-http` · `poller` · `code-engine` · `ngrok` · `agentic-ai`\n\n> **One config site:** map many Slack channels → many WxO agents.  \n> Poller (and optional Slack Events) wake agents.  \n> Same host exposes an **MCP toolkit** (`/mcp`) for WxO / Cursor / other clients.\n\nDeep dive: **[Why this MCP — lifting WxO limits](docs/WHY-THIS-MCP.md)**\n\n### Architecture at a glance\n\n```mermaid\nflowchart LR\n  subgraph Slack\n    C1[\"#support\"]\n    C2[\"#orders\"]\n    C3[\"#ops\"]\n  end\n\n  subgraph Gateway[\"Slack ↔ WxO MCP Gateway\"]\n    Bind[\"config.yaml bindings\"]\n    Poll[\"Poller / Events\"]\n    MCP[\"/mcp streamable-http\"]\n    UI[\"Admin UI /\"]\n  end\n\n  subgraph WxO[\"watsonx Orchestrate\"]\n    A1[\"Agent A\"]\n    A2[\"Agent B\"]\n    A3[\"Agent C\"]\n  end\n\n  subgraph Clients[\"MCP clients\"]\n    IDE[\"Cursor / VS Code / Bob / …\"]\n    TK[\"WxO toolkits\"]\n  end\n\n  C1 & C2 & C3 --> Poll\n  Poll --> Bind\n  Bind --> A1 & A2 & A3\n  A1 & A2 & A3 -.->|gateway_thread reply| Poll\n  IDE & TK --> MCP\n  UI --> Bind\n```\n\n---\n\n## Why this approach (WxO limits → lift)\n\n| WxO / Slack limit | Tag | Gateway lift |\n|-------------------|-----|----------------|\n| `byo_slack` ≈ @mention / DM only | `every-message` | Poller / Events wake agents on **every** human message |\n| Hard to run many channels → many agents | `multi-channel` `multi-agent` | One bindings table + admin UI |\n| Thread follow-ups easy to drop | `thread-followups` | Reads thread replies + context |\n| Noisy finals (`done`, etc.) in Slack | `gateway-thread` `no-done-noise` | Gateway posts answers; filters noise |\n| Agents need remote tools with real DNS | `mcp-toolkit` `streamable-http` | Hosted `/mcp` for Orchestrate toolkits |\n| Ops stuck cloning pollers | `ops-self-serve` | MCP tools + diagnostics + logs |\n| Slack ops only inside Slack/WxO UI | `ide-parity` | Same tools in Cursor, VS Code, Bob, Antigravity, Claude |\n\nWxO stays the **brain** (LLMs, skills, flows). This gateway is the **Slack + routing + MCP edge**.  \nBring-your-own agent frameworks: [`docs/frameworks/`](docs/frameworks/) (LangGraph, LlamaIndex, OpenAI Agents).\n\n---\n\n## npm / MCP identity\n\n| | |\n|---|---|\n| npm | `@markusvankempen/slack-wxo-mcp-gateway` |\n| MCP name | `io.github.markusvankempen/slack-wxo-mcp-gateway` |\n| Topics | `mcp` · `mcp-server` · `slack` · `watsonx` · `watsonx-orchestrate` · `ibm` · `wxo` · `byo-slack` · `multi-channel` · `code-engine` · `streamable-http` · `cursor` · `agentic-ai` |\n\nFull keyword list lives in [`package.json`](package.json) for npm discoverability.\n\n---\n\n## Publish & run modes (A–D)\n\n**One package / one image** — pick a mode (see [`docs/PUBLISH-MODES.md`](docs/PUBLISH-MODES.md)):\n\n```mermaid\nflowchart TB\n  PKG[\"npm @markusvankempen/slack-wxo-mcp-gateway<br/>+ optional container image\"]\n  PKG --> A[\"A Local HTTP<br/>:3100 UI + /mcp + poller\"]\n  PKG --> B[\"B Podman / Docker<br/>:8080\"]\n  PKG --> C[\"C Code Engine<br/>HTTPS always-on\"]\n  PKG --> D[\"D IDE stdio<br/>Cursor / VS Code / Bob\"]\n  A --> N[\"ngrok demo tunnel\"]\n  A & B & C --> R[\"Remote /mcp clients\"]\n  D --> L[\"Local MCP session\"]\n```\n\n| Mode | Command | Use |\n|------|---------|-----|\n| **A** Local HTTP | `./scripts/run.sh --mode http` | UI + `/mcp` + poller on laptop |\n| **B** Podman/Docker | `./scripts/run.sh --mode podman` | Same app in a container |\n| **C** Code Engine | `./scripts/run.sh --mode ce` | Always-on HTTPS |\n| **D** IDE MCP | `./scripts/run.sh --mode ide` | Cursor / VS Code stdio snippets (+ `--exec`) |\n| Ngrok demo | `./scripts/run.sh --mode ngrok` | A + tunnel + WxO toolkit |\n\n```bash\n./scripts/run.sh --mode ide      # print Cursor + VS Code mcp.json\n./scripts/run.sh --mode http     # local host :3100\n./scripts/run.sh --mode podman   # container :8080\n./scripts/run.sh --mode ce       # IBM Code Engine\n```\n\nDeep guides: [`docs/local-ngrok/`](docs/local-ngrok/) · [`docs/code-engine/`](docs/code-engine/) · [`docs/ide/`](docs/ide/)  \nIndex: [`docs/README.md`](docs/README.md) · Setup: [`SETUP.md`](SETUP.md)\n\nCopy-paste IDE JSON: [`examples/mcp/`](examples/mcp/)\n\n## Agent frameworks (LangGraph · LlamaIndex · OpenAI Agents)\n\nConnect frameworks **to** this MCP — do not embed them in the gateway.\n\n| Guide | Focus |\n|-------|--------|\n| [`docs/frameworks/`](docs/frameworks/) | Index + checklist |\n| [`docs/frameworks/langgraph.md`](docs/frameworks/langgraph.md) | LangGraph / LangChain |\n| [`docs/frameworks/llamaindex.md`](docs/frameworks/llamaindex.md) | LlamaIndex |\n| [`docs/frameworks/openai-agents.md`](docs/frameworks/openai-agents.md) | OpenAI Agents SDK |\n\n### Install (npm / npx) — not from this repo\n\n```bash\n# Hosted HTTP + admin UI (default)\nnpx -y @markusvankempen/slack-wxo-mcp-gateway\n\n# IDE / stdio MCP\nnpx -y @markusvankempen/slack-wxo-mcp-gateway --stdio\n```\n\nRequires Node 18+ and Python 3.10+. Env template: [`.env.example`](.env.example). Guides: [local-ngrok](docs/local-ngrok/) · [code-engine](docs/code-engine/).\n\n---\n\n## Mental model\n\nMulti-channel routing:\n\n```mermaid\nflowchart LR\n  S1[\"#support\"] --> G[\"Gateway bindings\"]\n  S2[\"#orders\"] --> G\n  S3[\"#ops\"] --> G\n  G --> WA[\"WxO agent A\"]\n  G --> WB[\"WxO agent B\"]\n  G --> WC[\"WxO agent C\"]\n```\n\nMessage path (`reply_mode: gateway_thread`):\n\n```mermaid\nsequenceDiagram\n  participant U as Slack user\n  participant Ch as Channel / thread\n  participant GW as Gateway poller\n  participant Wx as WxO Runs API\n  participant Bot as Slack bot reply\n\n  U->>Ch: Human message\n  GW->>Ch: Read new messages / replies\n  GW->>Wx: Start bound agent run\n  Wx-->>GW: Agent answer text\n  GW->>Bot: chat.postMessage in thread\n  Bot-->>Ch: Clean reply (no done noise)\n```\n\nSame host also serves **MCP** at `/mcp` and the **admin UI** at `/`.\n\n---\n\n## Config (`config.yaml`)\n\n| Field | Meaning |\n|-------|---------|\n| `slack_channel_id` | e.g. `C0BHWEZ7NLC` |\n| `wxo.agent_id` | Target Orchestrate agent |\n| `mode` | `poll` \\| `events` \\| `both` |\n| `reply_mode` | `gateway_thread` = gateway posts Slack thread after Runs API; `agent_tools` = only start agent |\n| `poll_sec` / `lookback_sec` | Poller timing |\n\nSecrets: use `${ENV_VAR}` (loaded from `.env`).\n\n---\n\n## Endpoints\n\n| Path | Role |\n|------|------|\n| `/` | Admin UI |\n| `/mcp` | MCP streamable HTTP |\n| `/slack/events` | Slack Event Subscriptions |\n| `/health` | Liveness |\n| `/api/logs` | Log ring buffer |\n| `/api/tools` | MCP tool catalog |\n| `/api/diagnostics` | Slack + WxO checks |\n| `/api/poll` | One poll cycle |\n| `/api/config` | Masked JSON / raw YAML |\n\n### Admin dashboard auth\n\n```bash\nGATEWAY_ADMIN_USER=admin\nGATEWAY_ADMIN_PASSWORD=choose-a-strong-password\n```\n\nProtects `/` and `/api/*`. **Public:** `/health`, `/mcp`, `/slack/events`.\n\n### IBM Code Engine\n\n```bash\n./deploy_code_engine.sh\n./test_code_engine.sh\n```\n\nRegister the toolkit:\n\n```bash\norchestrate toolkits add -k mcp -n slack_wxo_gateway \\\n  --url \"https://YOUR-HOST/mcp\" \\\n  --transport streamable_http \\\n  --tools \"*\"\n```\n\n### MCP tools (14)\n\n**Config:** `list_bindings`, `upsert_binding`  \n**Slack:** `list_slack_channels`, `list_recent_messages`, `list_thread_replies`, `get_message_context`, `post_thread_reply`, `set_typing_indicator`  \n**WxO:** `list_wxo_agents`, `invoke_wxo_agent`  \n**Ops:** `poll_once`, `get_gateway_status`, `get_recent_logs`, `run_diagnostics_tool`\n\nBot scopes: `channels:read`, `groups:read`, `reactions:write` (reinstall Slack app after adding).\n\n**Agents:**\n\n| Agent | Role |\n|-------|------|\n| [`agent.yaml`](agent.yaml) → `slack_gateway_test_agent` | Full-toolkit smoke |\n| [`agents/slack_gateway_ops_agent.yaml`](agents/slack_gateway_ops_agent.yaml) | Day-2 ops / routing |\n| [`agents/slack_gateway_answer_agent.yaml`](agents/slack_gateway_answer_agent.yaml) | Channel answers (`gateway_thread`) |\n\n**Setup (Slack + WxO):** [`SETUP.md`](SETUP.md) — also live in admin UI → **Setup**  \n**Use cases + test plan:** [`USE_CASES.md`](USE_CASES.md)  \n**Publish (npm / GitHub):** [`PUBLISH.md`](PUBLISH.md)\n\n---\n\n## Reply modes\n\n**`gateway_thread` (default)** — poller/Events → Runs API → gateway `chat.postMessage` in thread. Use the answer-only agent (no `done`).\n\n**`agent_tools`** — gateway only starts the agent; agent uses its own Slack tools.\n\n---\n\n## Cursor / VS Code / Bob / Antigravity / Claude\n\nSee **[`docs/ide/`](docs/ide/)** for each client. Quick remote bridge:\n\n```json\n{\n  \"mcpServers\": {\n    \"slack-wxo-gateway\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-remote\", \"https://YOUR-HOST/mcp\"]\n    }\n  }\n}\n```\n\nPackage identity:\n\n- npm: [`@markusvankempen/slack-wxo-mcp-gateway`](https://www.npmjs.com/package/@markusvankempen/slack-wxo-mcp-gateway)\n- MCP: `io.github.markusvankempen/slack-wxo-mcp-gateway`\n- Site: [https://markusvankempen.github.io/](https://markusvankempen.github.io/)\n\n---\n\n## License\n\n[Apache-2.0](LICENSE) — © Markus van Kempen  \n[https://markusvankempen.github.io/](https://markusvankempen.github.io/) · [https://github.com/markusvankempen](https://github.com/markusvankempen)\n",
  "bytes": 10140,
  "sha": "402b40c4699af3c2369b3565a5f126661e54261ef39197542ab788dea4a80a76",
  "repo_slug": "markusvankempen/slack-wxo-mcp-gateway",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_markusvankempen_slack_wxo_mcp__c92f36be/readme"
}