Other MCP clients

The Helmdesk server is a standard stdio MCP server with no client-specific behaviour, so anything that speaks the protocol can use it. If your client is not one of the four with their own page, this is all you need.

The generic configuration

Almost every client uses the same JSON shape under an mcpServers key. Windsurf, Zed, VS Code, and most others accept this verbatim:

{
  "mcpServers": {
    "helmdesk": {
      "command": "npx",
      "args": ["-y", "@helmdesk/mcp"],
      "env": {
        "HELMDESK_API_KEY": "sk_live_your_key_here",
        "HELMDESK_PROJECT": "ledgerly",
        "HELMDESK_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Only the first variable is required. Where the file lives is the part that differs by client — check its own documentation for that, and it is usually reachable from a settings panel rather than by hand.

Two differences worth knowing

Codex uses TOML and calls the table mcp_servers with an underscore — see Codex. Some clients declare a "type": "stdio" field alongside command. Adding it is harmless where it is not required.

Run it by hand

When a client will not connect and gives you nothing to work with, run the server yourself. It talks JSON-RPC over stdio, so it will sit there waiting for input — which is itself the signal that it started cleanly:

HELMDESK_API_KEY=sk_live_your_key_here npx -y @helmdesk/mcp

Without a key it exits immediately and prints a usage block to stderr. That is the fastest way to tell a credential problem from a PATH problem: if this works in your shell but the client shows nothing, the client is launching with a different environment, and the fix is an absolute path to npx.

What the server needs

Node 18 or newer. No install step — npx fetches the package.
stdio transport. There is no HTTP or SSE endpoint to point at.
Outbound HTTPS to helmdesk.dev. Override it with HELMDESK_BASE_URL if you are pointing at something else.

What your client will see

73 tools and three read-only resources (helmdesk://tickets/open, helmdesk://tickets/pending, helmdesk://articles). Every tool carries annotations distinguishing reads from writes from calls that reach a real customer, so a client with per-tool approval has what it needs to treat them differently. The full list is in the tool reference.

The server also publishes an instructions string covering how to choose a project and the rule that it must never guess before doing something that reaches a customer. Clients that surface server instructions will show it; clients that pass it to the model will follow it.

If your client has no approval step

Some clients run tools without asking. Ten of the 73 tools email a real person and cannot be undone. With a client like that, bound it with the credential rather than with attention: issue a read-only key, or a sk_sandbox_ key, which can never reach live data whatever it is asked to do. See Safety & approvals.

Building your own client

If you are writing the integration rather than configuring one, the same surface is available as a REST API and a TypeScript SDK, which is a great deal less machinery for anything that is not conversational. See REST API and the Node.js SDK. The MCP server is a thin layer over both.