stdio bridge for local MCP clients
Connect clients that only run local stdio MCP servers, or cannot do remote OAuth, to a self-hosted OpsKnight with the opsknight-mcp bridge.
Some MCP clients only start local servers over standard input and output (stdio), or cannot complete a remote OAuth sign-in. opsknight-mcp is a small local program that such a client starts like any other stdio server. It forwards each message to your OpsKnight server's /mcp endpoint and writes the answers back. It has no dependencies beyond Node.js 20 or later, keeps no session and adds no permissions: every call runs as you, within your token's permissions, exactly as a remote connection would.
Clients that can connect to a remote server with OAuth should do that instead; see self-hosted setup.
Before you begin
- An administrator has turned on AI assistant access in Settings → Integrations & ChatOps → MCP (AI Assistants), and allowed either personal access tokens or Device sign-in (see Sign in).
- Node.js 20 or later on the machine that runs your MCP client.
- Your OpsKnight App URL, for example
https://ops.your-company.com.
The steps are:
- Get the bridge.
- Sign in with a personal access token or device sign-in.
- Configure your client to start the bridge.
- Verify the connection.
Get the bridge
The bridge is not published to a package registry. It lives in the OpsKnight repository under sdk/mcp-bridge. Copy that folder to the machine that runs your MCP client and run node <folder>/bin/opsknight-mcp.js, or link it once with npm link from inside the folder to get an opsknight-mcp command.
The bridge refuses plain http:// addresses except localhost and 127.0.0.1, so your token never crosses a network unencrypted.
Sign in
Choose one:
-
Personal access token (an administrator must allow personal tokens). Create one under Settings → Integrations & ChatOps → MCP → Connections → Personal access tokens and give it to the bridge in the
OPSKNIGHT_TOKENenvironment variable. Tokens start withokmcp_pat_. See API-hosted and headless agents. -
Device sign-in (an administrator must turn on Device sign-in, and either Automatic connections or register the client by hand). Run once:
opsknight-mcp login --url https://ops.your-company.comThe bridge registers itself as "OpsKnight stdio bridge" (or uses
--client-id <id>for an assistant an administrator registered with Allow device sign-in with a code), prints a code and an address, and waits while you approve in any browser (how device sign-in works). Add--scope "incidents:read services:read"to ask for fewer permissions. It stores the client id and refresh token in$XDG_CONFIG_HOME/opsknight/mcp.json(default~/.config/opsknight/mcp.json), readable only by you (mode 0600). Access tokens are kept only in memory and refreshed before they expire. Revoking the connection under Your connections signs the bridge out.
OPSKNIGHT_TOKEN wins when both are present. The bridge never prints a token; it writes diagnostics to standard error only.
Configure your client
The command is the same for every stdio client: opsknight-mcp --url <App URL>, with OPSKNIGHT_TOKEN in the environment if you use a personal token. If opsknight-mcp is not on the client's PATH, use node as the command and the full path to bin/opsknight-mcp.js as the first argument.
Claude Desktop (claude_desktop_config.json, under Settings → Developer → Edit Config):
{
"mcpServers": {
"opsknight": {
"command": "opsknight-mcp",
"args": ["--url", "https://ops.your-company.com"],
"env": { "OPSKNIGHT_TOKEN": "okmcp_pat_…" }
}
}
}
Leave out env after opsknight-mcp login. The same mcpServers entry works in Cursor (~/.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json) and Gemini CLI (~/.gemini/settings.json). VS Code (.vscode/mcp.json) uses "servers" with "type": "stdio":
{
"servers": {
"opsknight": {
"type": "stdio",
"command": "opsknight-mcp",
"args": ["--url", "https://ops.your-company.com"]
}
}
}
Claude Code:
claude mcp add opsknight -- opsknight-mcp --url https://ops.your-company.com
Codex CLI:
codex mcp add opsknight -- opsknight-mcp --url https://ops.your-company.com
Keep a personal token in the client's own secret store or environment where it has one, not in a shared or committed file.
Verify the connection
- Restart or reload your client so it starts the bridge.
- Ask the assistant "Who am I in OpsKnight, and what can you do for me?". It calls
whoamiand answers with your role, teams and enabled tools. - If the call fails, read the bridge's diagnostics on standard error (your client's MCP log) and see Troubleshooting.
Options
| Option | Meaning |
|---|---|
--url <App URL> |
Your OpsKnight address (or OPSKNIGHT_URL). A trailing /mcp is accepted. |
--toolsets a,b |
Sends X-OpsKnight-Toolsets: a,b so the server offers only those groups of tools, where the server supports it. |
--channel |
Claude Code only: pushes your new pages into the running session. See below. |
login |
Device sign-in, as above. Takes --url, and optionally --scope and --client-id. |
What the bridge does
- Each line the client writes is one HTTP
POST <App URL>/mcpwith your bearer token and the protocol headers the server expects:MCP-Protocol-Version(the version in the request's_meta, otherwise the one agreed ininitialize),Mcp-Method, andMcp-Namefor tool calls, prompts, resource reads and tasks. - JSON answers and streamed (
text/event-stream) answers are both written back, one message per line. Several requests can run at once; each answer keeps its request's id. - 401: with a device sign-in the bridge refreshes once and retries; otherwise the client gets a JSON-RPC error telling you to sign in again or replace the token.
- 429: the bridge waits for
Retry-After(up to 30 seconds, three times) and retries; a longer wait is returned as an error. - If the server cannot be reached, the request gets a JSON-RPC error and the bridge keeps running.
Pages in Claude Code (channel)
Claude Code channels let a local MCP server push events into a running session. With --channel, the bridge declares the claude/channel capability, holds a subscriptions/listen stream for opsknight://oncall/me/pages and turns each update into a notifications/claude/channel event, so Claude learns that you were paged and can look with oncall_catch_up. The server ends each stream after ten minutes; the bridge reconnects, and backs off when the subscription is refused (for example on a server version without that resource).
Channels are a Claude Code research preview: start Claude Code with the channel enabled, for example claude --dangerously-load-development-channels server:opsknight, and on Team and Enterprise plans an administrator must allow channels. Only events from your own OpsKnight account arrive; the bridge does not relay permission prompts.
Troubleshooting
Refusing http://…: use thehttps://address.No credentials for …: setOPSKNIGHT_TOKENor runopsknight-mcp login.Device sign-in is turned off on this server: ask an administrator, or use a personal token.- Error codes the server returns are listed in troubleshooting.
Last updated for v2.2.0
Edit this page on GitHub