Overview

Tideways MCP Server is a lightweight backend that exposes PHP performance monitoring data in a format suitable for programmatic queries and conversational workflows. It bridges Tideways-style trace and metric captures with a Model Context Protocol (MCP) surface so that tools, agents, or language models can fetch relevant traces, summarize performance issues, and drive interactive investigations.

For developers and SREs, this server reduces the friction of turning raw profiler output into actionable insights. Rather than manually hunting through traces, you can query specific timeframes, endpoints, or traces, and surface pre-formatted context for observability dashboards or AI assistants that provide natural-language explanations and troubleshooting steps.

Features

Exposes performance traces, spans, and metrics via an HTTP API
Aggregation and filtering by service, endpoint, tag, time window, or error state
Produces MCP-compatible context bundles for LLMs and other consumers
Conversational/assistant endpoints for natural-language summaries and suggested fixes
Docker-ready and configurable via environment variables
Lightweight storage/backing with optional persistence (SQLite/Postgres) or in-memory mode
Example clients and curl snippets for quick experimentation

Installation / Configuration

Clone the repository and run locally, or use Docker. Below are common steps and example environment variables to configure the server.

Clone and run (Node/npm example)

git clone https://github.com/abuhamza/tideways-mcp-server.git
cd tideways-mcp-server
npm install
# create .env file (see example below)
npm run start

Example .env

PORT=8080
DATABASE_URL=sqlite:./data/tideways.db
LOG_LEVEL=info
OPENAI_API_KEY=sk-REPLACE_WITH_KEY   # optional, for AI-driven summaries
MCP_MAX_CONTEXT_SIZE=250000

Docker

# docker-compose.yml (basic example)
version: "3.8"
services:
  tideways-mcp:
    build: .
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - DATABASE_URL=sqlite:./data/tideways.db
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./data:/app/data

docker compose up --build

Configuring Tideways / PHP agent

Configure your Tideways PHP agent to capture traces as usual.
If your pipeline supports forwarding traces, point it to a collector or export traces into a storage location the MCP server can access.
The server supports direct ingestion from compatible JSON trace exports (see ingestion endpoints).

Available Resources

GitHub repository (source and examples): https://github.com/abuhamza/tideways-mcp-server
HTTP API (example endpoints listed below)
Example clients: simple curl and Node/Python snippets in the repo
Optional AI integration: enable an LLM API key to allow conversational summaries

Sample API endpoints (illustrative)

Method	Path	Purpose
GET	/api/traces	List traces with filters (service, endpoint, since, until)
GET	/api/traces/:id	Fetch a single trace and spans
POST	/api/query	Run ad-hoc queries (time window, tags, duration thresholds)
POST	/api/mcp/context	Build a MCP context bundle for an LLM from selected traces
POST	/api/assistant	Ask a natural-language question and receive an AI-driven analysis

Example: fetch slow traces

curl "http://localhost:8080/api/traces?min_duration=500&since=2026-04-01T00:00:00Z"

Generate an MCP context bundle

curl -X POST http://localhost:8080/api/mcp/context \
  -H "Content-Type: application/json" \
  -d '{"traceIds":["abc123","def456"], "maxSize":200000}'

Use Cases

Faster incident triage: Ask the assistant “Which endpoints regressed after last deploy?” and receive a short list of candidates with trace snippets and suggested root-cause directions.
Root-cause investigation: Query spans related to slow database queries, aggregate SQL statements, and surface the top offenders with example stack frames.
Continuous profiling: Integrate the server into CI/CD alerts to automatically produce a human-readable summary when performance thresholds are exceeded.
Developer onboarding: New team members can query historical traces for a service and receive a guided explanation of common hotspots and patterns.
Dashboard augmentation: Use MCP bundles to feed LLMs that generate human-friendly observations for dashboard widgets (e.g., “Top 3 slow endpoints this week and likely causes”).

Tips for Developers

Start small: ingest a few representative traces and iterate on your queries and filters before connecting production telemetry.
Use MCP context size limits: keep bundles focused (relevant spans, tags, and a short timeline) so LLM consumers remain efficient and within token limits.
Secure AI keys: if enabling AI-driven endpoints, put keys in environment variables or secret stores and limit access to the MCP server.
Automate alerts: combine trace filters with CI hooks to trigger context generation and automated summaries when regressions are detected.

For complete usage examples, client libraries, and advanced configuration options, see the repository’s examples and API references.

Tideways MCP Server for PHP Performance Insights