jwx-mcp

The Justworx MCP server — exposes Justworx devices to AI agents (Claude, ChatGPT, agent frameworks) as MCP tools (control) and resources (read-only state), backed entirely by the public Developer API (/api/dev/v1).

It is a thin, standalone client of the Developer API: it calls the gateway over HTTPS, holding no device keys — actuation flows through the gateway to the Justworx platform.

Two run modes, one server core (the tools/resources are transport-agnostic):

• stdio (src/index.js) — a client (Claude Desktop, etc.) launches it locally with a single jwx_live_ API key. This is the local/desktop path.

• remote (src/http-entry.js) — a hosted, multi-tenant OAuth 2.1 Resource Server over the MCP Streamable HTTP transport, for clients that can't launch a local process (claude.ai web, ChatGPT connectors). Each caller brings their own OAuth access token; see below.

Tools

Related MCP server: eyeot-mcp

Resources

• justworx://devices — the accessible device list.

• justworx://devices/{serial} — live state for one device.

Configure & run

The server speaks stdio (how MCP clients launch a local server). It needs a Developer API key — issue one via the portal / the gateway's /manage/keys API.

// Claude Desktop / MCP client config
{
  "mcpServers": {
    "justworx": {
      "command": "node",
      "args": ["C:/Users/Wkyle101/jwx-mcp/src/index.js"],
      "env": {
        "JWX_API_KEY": "jwx_live_…",
        "JWX_API_BASE_URL": "https://dev-api.justworx.com/api/dev/v1"
      }
    }
  }
}

Inspect it locally with the MCP Inspector:

JWX_API_KEY=jwx_live_… npx @modelcontextprotocol/inspector node src/index.js

Remote mode (hosted, OAuth 2.1)

For hosted clients (claude.ai web, ChatGPT connectors) that can't spawn a local process, run the Streamable HTTP server. It is a standard OAuth 2.1 Resource Server: it does not issue tokens, it validates the ones from the OAuth authorization server and forwards each caller's token to the Developer API (the gateway accepts either an API key or an OAuth token). Fully multi-tenant — a fresh server is built per request, bound to that caller's token; no shared key, no cross-tenant state.

npm run start:http     # → http://0.0.0.0:$MCP_HTTP_PORT/mcp

• Endpoint: POST /mcp (Streamable HTTP, stateless). GET /healthz for liveness.

• OAuth discovery (so clients self-register + authorize): GET /.well-known/oauth-protected-resource (RFC 9728 → points at the AS) and GET /.well-known/oauth-authorization-server (RFC 8414 mirror). An unauthenticated call returns 401 + WWW-Authenticate: Bearer resource_metadata="…".

• Tokens must be audience-bound (RFC 8707) to MCP_RESOURCE_URL; scopes map to Developer-API scopes.

Deployment: run this server behind an HTTPS reverse proxy or tunnel and publish it at your resource URL (e.g. mcp.justworx.com). It validates tokens from the OAuth authorization server at https://oauth.justworx.com. The OAuth Resource-Server layer is complete and covered by tests against a stub issuer. See DEPLOY-REMOTE.md.

Config (env)

Test

npm test   # node:test — connects a real MCP client over an in-memory transport

Tests drive an actual MCP Client against the server with an injected fake API client; the HTTP client itself is also verified end-to-end against a live jwx-dev-api (mock upstream).

Layout

src/apiClient.js   thin fetch client for /api/dev/v1 (bearer: api key OR OAuth token)
src/server.js      buildServer({client}) — tools + resources (transport-agnostic)
src/config.js      env config (stdio + remote/OAuth)
src/index.js       stdio entrypoint
src/oauth.js       OAuth 2.1 token verifier (JWKS) — Resource Server side
src/http.js        remote app: Streamable HTTP + OAuth discovery + per-request token forwarding
src/http-entry.js  remote entrypoint (npm run start:http)
test/server.test.js  stdio: MCP client ⇄ server over in-memory transport
test/http.test.js    remote: real Streamable-HTTP MCP client + stub AS (JWKS) → authed tool calls