pyxis-mcp

The MCP server of Pyxis: lets an AI agent read your dashboard's numbers, with a read-only token you can revoke at any time.

Pyxis · Live demo · API reference

Status: on npm as pyxis-mcp, every release published from GitHub Actions with provenance. The fifteen tools read the live Pyxis API.

Ecosystem

Related MCP server: shop-sql-mcp

Why it exists

More and more questions about a product are asked to an agent instead of a dashboard: "how did last week compare", "where does the sign-up funnel lose people", "which route started failing". This server gives Claude Code, Claude Desktop, Cursor and other MCP clients the same numbers the Pyxis dashboard shows, and nothing more: it uses an access token that only reads, created by an admin in the dashboard's Settings and revocable there at any moment. Like the rest of Pyxis, there is no personal data to hand over: events carry no cookies, no addresses and no user agents.

Tools

Every tool only reads, and maps to one GET route of the Pyxis API. Dates are YYYY-MM-DD in the project's time zone; list_projects gives each project's today, so call it first.

A result is JSON text, { "untrusted_visitor_text": "…", "report": … }: the report is the API's answer, and the first field reminds the agent that names, paths and values inside it were written by the site's visitors. Problems come back as tool errors the agent can act on (a revoked token, an unknown project, the rate limit and when to retry).

Configuration

A missing or malformed value stops the server with a sentence on standard error that names the variable and never repeats its value.

Use it

Create a token in the dashboard (Settings, Access tokens), then add the server to your client. It runs with npx, so there is nothing to install beforehand (Node 22 or later).

Claude Code:

claude mcp add pyxis -e PYXIS_TOKEN=pyxis_at_… -- npx -y pyxis-mcp

Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "pyxis": {
      "command": "npx",
      "args": ["-y", "pyxis-mcp"],
      "env": { "PYXIS_TOKEN": "pyxis_at_…" }
    }
  }
}

A self-hosted Pyxis adds PYXIS_API_URL. To run it from source instead, npm ci && npm run build in a clone and use node /path/to/pyxis-mcp/dist/cli.js as the command. Keep the token out of shared files and chats; revoke it in the dashboard the moment it leaks.

Architecture

flowchart LR
  Agent["MCP client<br>(Claude Code, Cursor…)"] -- "stdio, JSON-RPC" --> Server["pyxis-mcp<br>(on the user's machine)"]
  Server -- "HTTPS GET<br>Authorization: Bearer pyxis_at_…" --> API["Pyxis API"]
  API --> DB[("Events")]

The server opens no port and keeps no state. The API decides what the token may read, exactly as it does for a dashboard session (ADR 0002).

Tech stack

TypeScript (strict) on Node 22 or later, ES modules. Vitest with V8 coverage, ESLint (typescript-eslint strict, type-checked) and Prettier, Husky and commitlint, GitHub Actions with CodeQL, Dependabot and release-please.

Getting started

npm ci
npm run lint && npm run typecheck && npm run test:cov && npm run build

Testing

• npm run test:cov runs the unit tests in Node and fails below 100% of statements, branches, functions and lines. The server is tested with a real MCP client over an in-memory transport and a fake fetch.

• One file is left out of the unit coverage: src/cli.ts, which only wires the modules to the standard input and output. npm run test:e2e covers it: after npm run build, a real MCP client starts dist/cli.js, lists the tools and calls them against a local fake of the API, checks that standard output carries nothing but the protocol, and that a bad configuration stops the process with the reason on standard error.

• src/contract.test.ts checks the tools against contract/openapi.json, the API's own contract (npm run contract:sync copies it from pyxis-api): every route a token may read has a tool, and every tool sends only declared parameters, with values inside their enums.

• npm run test:tooling tests the lint rule and the scripts.

• CI runs the unit tests on Node 24 and again on Node 22, the oldest version the package supports.

Project structure

src/
├── config.ts        reads PYXIS_TOKEN and PYXIS_API_URL
├── pyxis-api.ts     one GET to the API, failures as sentences
├── tools.ts         the fifteen tools: input schemas, routes, requests
├── server.ts        registers the tools on the MCP server
├── version.ts       the package version, for the server and the user agent
└── cli.ts           the executable: stdio transport
e2e/                 the built server driven by a real MCP client
contract/            the API's OpenAPI contract, copied from pyxis-api
eslint-rules/        the local rule that forbids comments
scripts/             the comment check and the contract sync
docs/adr/            architecture decision records

Privacy and security

• Read-only: the API accepts the token only on its read routes; it cannot write, sign in, manage sessions or create tokens.

• The token only travels in the Authorization header to the configured API, over https (plain http only to localhost), and never reaches a log, an error message or a tool result.

• Text written by a site's visitors is returned as data, and each tool description says it is not an instruction.

• Vulnerabilities: see SECURITY.md.

Architecture decisions

Roadmap

• Repository skeleton, quality gates, configuration reader

• Tools over the API's read routes, tested against its OpenAPI contract

• First release on npm, with provenance

• Setup guides for Claude Code, Claude Desktop and Cursor

Contributing and license

See CONTRIBUTING.md and the Code of Conduct. MIT licensed: see LICENSE.