@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"]
    }
  }
}

chrome-devtools above is a generic, illustrative example of the config shape — not a recommendation or endorsement. Any MCP server works; Pix stays provider-neutral.

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 suite uses bun test --isolate (see root package.json). This is required because mock.module() is process-global and leaks between files without isolation. The flag is intentionally on the default bun test command so bare runs pass everywhere (bunfig.toml does not support [test].isolate in Bun 1.3).

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.