@xynogen/pix-mcp

Token-efficient MCP gateway for the Pix Pi distro.

See the monorepo's root README for upstream lineage and LICENSE for the retained MIT license.

Install

pi install npm:@xynogen/pix-mcp

Restart Pi after installation. Pix keeps MCP opt-in because external servers may require credentials, execute local commands, or expose sensitive data.

Configure

Preferred project config: .mcp.json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Preferred shared user config: ~/.config/mcp/mcp.json.

Pix MCP also reads, in increasing precedence:

1. ~/.config/mcp/mcp.json
2. <Pi agent dir>/mcp.json
3. .mcp.json
4. .pi/mcp.json

Run /mcp setup for guided discovery, or pix-mcp init to detect supported Cursor, Claude, Codex, Windsurf, and VS Code configs.

Token-efficient defaults

• One compact mcp proxy tool is exposed instead of every remote tool schema.
• Servers connect lazily and tool metadata is cached for seven days.
• search and server listing return bounded compact results by default.
• Schemas are loaded only with describe, or explicitly with includeSchemas: true on search.
• Large MCP results are truncated in context and written to a temporary file for targeted inspection.
• Direct tools remain opt-in because each one adds its schema to the baseline prompt.

Gateway examples

mcp({})
mcp({server: "github"})
mcp({search: "issue create", server: "github"})
mcp({describe: "github_create_issue"})
mcp({tool: "github_create_issue", args: "{\"owner\":\"acme\",\"repo\":\"app\",\"title\":\"Bug\"}"})

Search/list responses default to 12 items. Request up to 50 with limit:

mcp({search: "issue", limit: 25})

Set includeSchemas: true only when a single discovery call really needs all matching schemas; describe is usually smaller.

Lifecycle

Servers default to "lazy", disconnect after ten idle minutes, and reconnect on the next call. Set a server's lifecycle to "eager" or "keep-alive" only when startup connection or health-checked persistence is worth the cost.

Lazy servers are not connected merely to populate metadata at startup. Their metadata is cached after the first explicit connection or call, and later sessions can search, list, and describe valid cached metadata without a live connection. Eager and keep-alive servers still connect at startup.

Development

The test suite uses bun:test throughout:

bun run test

The package test command uses scripts/test.ts to run each test file in a separate Bun process. This isolation is intentional: Bun's mock.module() state can currently leak between test files even when bun test --isolate is used, causing tests that pass individually to interfere with the full suite. The runner is small, cross-platform, and is not included in the published npm package. It can be removed once Bun provides reliable module-mock isolation, or after the tests are refactored to avoid module-level mocks.

Compatibility

The package preserves the upstream MCP transport, OAuth, sampling, elicitation, MCP Apps/UI, resource, direct-tool, lifecycle, and output-guard capabilities. Existing .mcp.json files remain compatible.