Tideways

What Tideways MCP server does

The Tideways MCP server gives an AI assistant read-only access to data held in Tideways, a PHP performance monitoring platform. It uses only GET requests against the Tideways REST API, so it can inspect monitoring data without changing projects, services, issues, or application settings. The project is unofficial and community-maintained, and is not affiliated with or supported by Tideways.

The available data covers several stages of performance investigation. An assistant can first identify the projects available to a token and inspect the remaining hourly rate limit. It can then examine services, request and error metrics, transaction timing, open or resolved issues, individual traces, historical reports, and Tideways observations such as N+1 query findings.

How it works

Each tool call uses a Tideways project context, except for tideways_list_projects. Most tools accept a project name or an organization/name reference. Defaults can be supplied through environment variables for the project, organization, environment, and service. Times are interpreted and returned in UTC using the format YYYY-MM-DD HH:mm.

Performance queries cover windows of up to 24 hours within roughly the previous 30 days and can return totals, layer data, and top transactions. Summary data uses 15-minute buckets for periods of up to 30 days. Transaction inspection provides minute-level timing and response-time histograms, while trace search returns individual slow requests and their time distribution. Historical reports support day, week, or month views for a past date.

Setup and configuration

The Tideways MCP server runs with Node.js 22 or later or through Docker. Set the required TIDEWAYS_TOKEN environment variable to a Tideways API token with metrics, traces, and errors scopes. The server reads the token from the environment and does not load .env files.

TIDEWAYS_PROJECT selects a default project. If the token can access several projects and no default is configured, pass a project to each applicable call. TIDEWAYS_ORG, TIDEWAYS_ENV, and TIDEWAYS_SERVICE provide matching defaults for organization, environment, and service. TIDEWAYS_BASE_URL can replace the HTTPS API endpoint, and TIDEWAYS_REQUEST_TIMEOUT sets a positive timeout in milliseconds up to 600,000. LOG_LEVEL controls stderr logging with debug, info, warn, or error values.

The package can be launched with npx -y tideways-mcp-server, or replaced with the Docker image ghcr.io/abuhamza/tideways-mcp-server. Configuration examples are provided for Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, VS Code, and OpenCode.

Tools and capabilities

• tideways_list_projects reports accessible projects, token scopes, and hourly rate-limit usage.
• tideways_list_services finds services associated with a project and can search for a service name.
• tideways_get_performance returns aggregate performance, layers, and top transactions for a recent window.
• tideways_get_transaction shows when a transaction slowed, with timeline and response-time distribution data.
• tideways_get_performance_summary reports requests, errors, and p95 values in 15-minute buckets.
• tideways_list_issues lists errors, slow SQL queries, deprecations, warnings, and notices by status.
• tideways_get_issue identifies affected code locations, transactions, and issue start or stop times.
• tideways_search_traces searches individual slow requests and their time allocation.
• tideways_get_history retrieves day, week, or month reports for past dates.
• tideways_get_observations returns detected configuration problems and code bottlenecks.

Limitations and notes

Tideways MCP server access is read-only. History is limited to production and the default service. Issues are returned 10 per page. Trace searches return 30 traces by default, or up to 100 when a higher limit is requested. The API cannot directly list services; service discovery uses issues across services, and a search can consume one request per service.

The rate limit belongs to the Tideways organization and resets by clock hour. Its size depends on the organization’s plan, and tokens and projects in that organization share it. Trace URLs omit query strings. An observation linking to an N+1 problem does not filter traces through the API; it opens the affected traces in Tideways instead.