Guides3 min read
Client setup guides
Per-assistant steps for connecting Claude, Claude Code, ChatGPT, Cursor, VS Code, Codex CLI, Gemini CLI and Windsurf to a self-hosted OpsKnight.
Each guide gives the exact steps for one assistant, its documented limits and what to check when it fails. They are written from each vendor's official documentation, fetched on 12 November 2026 and linked at the top of each page. Vendors move menus often; when a step does not match what you see, follow the linked vendor page.
| Assistant | Guide | Status |
|---|---|---|
| Claude (claude.ai, Desktop, mobile) | Claude apps | Expected |
| Claude Code | Claude Code | Tested (see certification) |
| ChatGPT | ChatGPT | Expected |
| Cursor | Cursor | Expected |
| VS Code with GitHub Copilot | VS Code | Expected |
| OpenAI Codex CLI | Codex CLI | Expected |
| Gemini CLI | Gemini CLI | Expected |
| Windsurf (Devin Desktop) | Windsurf | Expected |
Expected means the steps follow the vendor's documentation and OpsKnight implements what that documentation requires, but nobody has recorded an end-to-end run of that application against OpsKnight. Tested links the recorded run.
What every guide assumes
- The address. Your MCP server URL is
<App URL>/mcp, for examplehttps://ops.your-company.com/mcp. Copy it from Settings → Integrations & ChatOps → MCP → Connect. Any installation also describes itself at<App URL>/llms.txt. - MCP is on. An administrator turned it on (self-hosted setup). With Automatic connections on, assistants register themselves; otherwise an administrator registers a manual client with the assistant's redirect URI first.
- Sign-in is OAuth by default. The assistant opens your browser, you sign in to OpsKnight and approve the permissions. Access tokens last five minutes and the assistant refreshes them itself.
- A personal access token is the alternative for clients that can send a fixed
Authorizationheader and for agents without a browser. An administrator must allow personal tokens first; you then create one under Connections → Personal access tokens. It starts withokmcp_pat_, is shown once, and changes it prepares always need a second person to approve. Keep it in an environment variable or the client's secret store, never in a file you commit. See API-hosted and headless agents. - Tool count. OpsKnight lists between 17 tools (view-only permissions) and 54 tools (an administrator who allowed changes). That is below every cap documented by the clients here; a client with a lower cap can hide some tools, and turning off unused capabilities under Exposed capabilities lowers the count.
Troubleshooting that applies to every client
- Check connection on the Connect tab shows the connection you just made, or what to do next.
npm run mcp:doctor -- https://ops.your-company.com/mcp(from a checkout of OpsKnight) checks discovery, TLS, automatic registration and the 401 challenge from outside, without creating credentials.- A cloud-hosted assistant (Claude apps, ChatGPT) connects from the vendor's network: the server must be reachable from the internet with a publicly trusted certificate.
- Every error code an assistant can show is on the troubleshooting page.
Last updated for v2.2.0
Edit this page on GitHub