<p align="center"><img src="assets/whagons-icon-512.png" width="100" alt="Whagons"></p>

# Whagons MCP

Read Whagons tasks and workspace information from an MCP client. Each person supplies their own Whagons API key and tenant. The server exposes six read-only tools. It does not create, change, approve, or delete tasks.

**Preview release.** Protocol and adapter tests pass. All six read-only API checks passed against production on September 5, 2026 using the correct tenant credential. An earlier 401 came from using another tenant's key, not a backend failure. Desktop-client installation and end-to-end client verification remain pending. This package has not been accepted into the ChatGPT or Claude public directories.

## Install in Claude Desktop

Download `whagons-0.1.0.mcpb` from the [releases page](https://github.com/Desarso/whagons-mcp/releases). Open it in Claude Desktop using its local extension installer. Supply your API key and tenant in the extension settings. Requires a client that supports MCP bundles and a Node.js 22 or newer runtime. Desktop installation on macOS and Windows is not yet verified.

Create a Whagons API key with `ext:read` scope in Settings > Integrations > API Keys. Your account's permissions still apply. Keep the key in the client's sensitive configuration field. Never put it in a prompt, source file, or GitHub issue.

## Install as a Claude plugin

In Claude Code, add this public marketplace and install the plugin:

```text
/plugin marketplace add Desarso/whagons-mcp
/plugin install whagons@whagons
```

Claude prompts for your API key and tenant when you enable the plugin. Requires Node.js 22 or newer. The bundled server has no runtime npm-install step. Cowork compatibility is not yet verified.

## Other MCP clients

Clone the repository or extract the source archive. Configure a stdio MCP server with command `node`, the absolute path to `dist/server.mjs` as its argument, and these environment variables supplied through your client's credential settings:

| Variable | Purpose |
| --- | --- |
| `WHAGONS_API_KEY` | Your read-enabled Whagons API key |
| `WHAGONS_TENANT_ID` | The tenant associated with that key |
| `WHAGONS_API_BASE_URL` | Optional operator override; defaults to `https://gonvex.whagons.com/api/v1` |

Only change the API URL to an HTTPS service you trust. The configured service receives your key. Redirects are refused. The Codex manifest uses a plugin-relative working directory and inherited environment variables. Set them in your client environment before enabling it.

## ChatGPT

The public ChatGPT connector needs a hosted MCP endpoint and per-user authentication. This preview contains a local stdio server. It does not provide a hosted OAuth service, and installing the Codex package does not publish a ChatGPT connector. OpenAI publisher verification and directory review are separate steps.

## Tools

| Tool | Purpose |
| --- | --- |
| `list_workspaces` | List accessible workspaces |
| `list_tasks` | Search tasks; filter by workspace, status, priority, or your assignments |
| `get_task` | Read a task by its canonical ID |
| `list_task_comments` | Read task comments |
| `list_statuses` | Resolve status names |
| `list_priorities` | Resolve priority names |

Collection tools default to 25 results and accept up to 100. Pass a returned `nextCursor` into the next call. Task text and comments are user-authored data and may contain untrusted instructions.

## Backend changes

Whagons is changing its Gonvex backend. `src/adapter.mjs` is the only backend-specific module. It calls the supported external API and sends tenant routing in a header at that boundary. It does not define application Queries, Reducers, Actions, or tenant arguments. Keep the six public tool contracts stable and reverify the adapter against the intended production release after staging ships.

## Develop and test

```sh
npm ci --ignore-scripts
npm run build
npm test
claude plugin validate .
```

The test suite uses synthetic data and a real MCP stdio client. It checks tool discovery and calls, rejection of tenant overrides and write tools, credential-safe failures, response limits, and standalone bundle startup. It does not prove backend authorization or desktop-client compatibility.

Read [PRIVACY.md](PRIVACY.md) for this package's data flow. For support, [open an issue](https://github.com/Desarso/whagons-mcp/issues) without keys or private task data. Published by Gabriel Malek using a personal account. The Whagons logo is the existing application mark.