SPX MCP Server

Web-only MCP server for php-spx reports. It calls the embedded SPX web endpoints, parses the full report, and returns LLM-sized JSON summaries instead of raw event streams.

Prerequisites

• Node.js 20 or newer

• An application with the spx PHP extension enabled for HTTP profiling

• SPX HTTP access configured, for example:

spx.http_enabled=1
spx.http_key="dev"
spx.http_ip_whitelist="127.0.0.1"

Build

npm install
npm run build

The built stdio entry point is:

/path/to/spx-mcp-server/dist/index.js

Set these environment variables in your agent config, or pass them per tool call:

SPX_BASE_URL=http://localhost
SPX_KEY=dev

Install In Codex CLI

Edit ~/.codex/config.toml and add:

[mcp_servers.spx]
command = "node"
args = ["/path/to/spx-mcp-server/dist/index.js"]
env = { SPX_BASE_URL = "http://localhost", SPX_KEY = "dev" }

Restart Codex CLI after editing the file.

Install In Claude Code

Local project config:

claude mcp add --transport stdio --scope project \
  --env SPX_BASE_URL=http://localhost \
  --env SPX_KEY=dev \
  spx -- node /path/to/spx-mcp-server/dist/index.js

User-wide config:

claude mcp add --transport stdio --scope user \
  --env SPX_BASE_URL=http://localhost \
  --env SPX_KEY=dev \
  spx -- node /path/to/spx-mcp-server/dist/index.js

Verify:

claude mcp list
claude mcp get spx

Equivalent .mcp.json project config:

{
  "mcpServers": {
    "spx": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/spx-mcp-server/dist/index.js"],
      "env": {
        "SPX_BASE_URL": "http://localhost",
        "SPX_KEY": "dev"
      }
    }
  }
}

Install In Cline

Cline is a popular open-source VS Code agent with MCP support.

For Cline CLI, run:

cline mcp

Then add a local stdio server with:

name: spx
command: node
args: /path/to/spx-mcp-server/dist/index.js
env:
  SPX_BASE_URL=http://localhost
  SPX_KEY=dev

For the VS Code extension, open the Cline MCP Servers settings and add this JSON:

{
  "mcpServers": {
    "spx": {
      "command": "node",
      "args": ["/path/to/spx-mcp-server/dist/index.js"],
      "env": {
        "SPX_BASE_URL": "http://localhost",
        "SPX_KEY": "dev"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Install In OpenClaw

OpenClaw is an open-source personal agent/gateway that can manage outbound MCP servers under mcp.servers.

Edit ~/.openclaw/openclaw.json or the file pointed to by OPENCLAW_CONFIG_PATH:

{
  mcp: {
    servers: {
      spx: {
        command: "node",
        args: ["/path/to/spx-mcp-server/dist/index.js"],
        env: {
          SPX_BASE_URL: "http://localhost",
          SPX_KEY: "dev",
        },
      },
    },
  },
}

Check the saved config:

openclaw mcp status --verbose
openclaw mcp probe spx

Basic Workflow

1. Call profile_url for the web URL you want to profile.

2. Call list_reports.

3. Pick the newest matching report.

4. Call analyze_report or get_hot_paths.

Tools

• profile_url: sends one HTTP request with SPX cookies enabled.

• list_reports: reads ?SPX_UI_URI=/data/reports/metadata.

• get_report_metadata: reads one report metadata JSON.

• analyze_report: downloads and parses ?SPX_UI_URI=/data/reports/get/<key>.

• get_hot_paths: returns the most expensive call paths.

• get_function_profile: returns one function's aggregate and callers/callees.

• get_raw_events: returns a paginated debug slice of raw events.

The analyzer limits output by default. Large SPX reports can contain millions of events, so full raw report output is intentionally not exposed as a normal tool result. get_raw_events is capped at 1000 events per call and is intended for debugging parser or analyzer behavior.

References

• Claude Code MCP configuration: https://code.claude.com/docs/en/mcp

• Cline MCP configuration: https://github.com/cline/cline/blob/main/docs/mcp/mcp-overview.mdx

• OpenClaw MCP configuration: https://docs.openclaw.ai/gateway/configuration-reference