# clarity-mcp-multi

An MCP proxy that adds per-client token routing on top of Microsoft's official [Clarity MCP server](https://www.npmjs.com/package/@microsoft/clarity-mcp-server).

## Why

The official server authenticates with a single Clarity Data Export token, and a token maps to exactly one project. If you manage several Clarity projects you end up editing the config and restarting the client every time you switch project.

This proxy keeps a `name → token` map and resolves the token by name at runtime. It does not reimplement any Clarity functionality: it launches the official server as a child process and forwards calls to it, so it inherits the full tool set and tracks upstream changes automatically.

## How it works

The package acts as a server towards its MCP client (Claude, Cursor, …) and as a client towards the official server at the same time. It registers two tools of its own and re-exports whatever the official server exposes. A call that isn't one of its own tools is forwarded to the child process and the response is returned unchanged.

Selecting a client with `clarity_usa_cliente` restarts the child with that client's token. The token is read from the registry on the server side and is never sent through the conversation.

The child is launched as `@microsoft/clarity-mcp-server@latest`, so upstream releases are picked up without changes here.

## Configuration

```json
{
  "mcpServers": {
    "clarity": {
      "command": "npx",
      "args": ["-y", "clarity-mcp-multi@latest"],
      "env": {
        "CLARITY_TOKENS": "{\"acme\":\"<token>\",\"globex\":\"<token>\"}"
      }
    }
  }
}
```

`CLARITY_TOKENS` is a JSON object mapping a client name to its Clarity Data Export token (Clarity → Settings → Data export). As an alternative, set `CLARITY_TOKENS_FILE` to a path holding the same JSON. `CLARITY_DEFAULT_CLIENT` optionally sets the client selected at startup.

Keep tokens out of source control: pass them through the environment or a file the host loads, not in a committed config.

## Tools

| Tool | Description |
|------|-------------|
| `clarity_clienti` | Lists the configured client names and the active one. No token is returned. |
| `clarity_usa_cliente` | Sets the active client by name; subsequent calls use its token. |

Names are matched case-insensitively. Every other tool is proxied to the official server under the active client's token.

## Requirements

Node.js 18 or later. One Clarity Data Export token per project.

## License

MIT