OQOS Connector

A deployable base Model Context Protocol server for OQOS. Its name and description are registered in server.json so MCP registries and compatible chatbot clients can discover it. The initial server exposes only connector_info; OQOS-specific tools can be added after deployment.

Run locally

Requirements: Node.js 20 or newer.

npm ci
npm test
npm start

The server uses MCP's stdio transport. In a chatbot or MCP host configuration, launch it with node /path/to/oqos-connector/src/index.js (or npx -y oqos-connector after publishing the package).

Run as a web server (custom connector)

For claude.ai, mobile, and other clients that connect by URL, run the Streamable HTTP server:

npm run start:http        # listens on $PORT (default 8080)

The MCP endpoint is /mcp (POST only, stateless) and /healthz is a health check. Deploy it anywhere that runs Node or Docker and serves HTTPS, then add https://<your-host>/mcp in Claude under Settings → Connectors → Add custom connector. This endpoint has no authentication, so it is only suitable while the server exposes nothing sensitive.

Run as a container

docker build -t oqos-connector:0.1.0 .
docker run --rm -p 8080:8080 oqos-connector:0.1.0              # HTTP server on :8080
docker run --rm -i oqos-connector:0.1.0 node src/index.js      # stdio

The -i flag keeps stdin open for the MCP stdio connection.

Publish and register

The MCP Registry indexes published packages; server.json describes the package and is the registry submission manifest. Publishing requires authorized npm and MCP Registry accounts.

1. Add an NPM_TOKEN repository secret in GitHub with permission to publish the package to npm.
2. Publish a GitHub Release to run the package publishing workflow. It installs dependencies, runs npm test, publishes to npm, then authenticates with the MCP Registry using GitHub Actions OIDC and publishes server.json. No MCP Registry token secret is needed.
3. For manual publishing, install mcp-publisher using the official instructions, authenticate with mcp-publisher login github, then run mcp-publisher publish. If a Registry JWT expires, log in again before publishing.

Keep the versions in package.json, src/index.js, and server.json aligned when preparing a release. Once the registry accepts the manifest, chatbots that support the MCP Registry can find OQOS Connector by its name or description.