Tideways MCP Server
A read-only MCP server for Tideways that lets an AI assistant query performance metrics, issues, traces, and observations via GET-only API tools.
List projects, token scopes, default project, and rate-limit status.
List services of a project, optionally searching for a service by keyword.
Get performance metrics (totals, error rate, p95, layers, top transactions, timeline) for up to 24h windows within ~30 days.
Get 15-minute performance summaries (requests, errors, p95) over up to ~30 days.
List issues (errors, slow SQL, deprecations) by status and type, 10 per page.
Search individual traces by text, time window, response time, and sort by response time or memory (at most 30 per call).
Get day/week/month historical reports for a past date.
Get observations (configuration problems and code bottlenecks like N+1 queries).
Supports optional project, service, and environment parameters; all times UTC.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Tideways MCP Server why was checkout slow yesterday?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Tideways MCP Server
An unofficial, community-maintained server, not affiliated with or supported by Tideways. For Tideways' own tooling, see the official Tideways CLI.
A read-only Model Context Protocol server for Tideways. It lets an AI assistant answer questions such as "why was checkout slow yesterday?" from your performance data, issues and traces. It only calls GET endpoints of the Tideways REST API.
Install
You need a Tideways API token with the scopes metrics, traces and errors (Organization settings → API Access), and Node.js 22+ or Docker. Coming from 1.x? See UPGRADING.md.
claude mcp add tideways -e TIDEWAYS_TOKEN=your-token -- npx -y tideways-mcp-serverAdd -s user to use it in every project.
Open the .mcpb bundle from the latest release. It asks for the token and keeps it in the OS keychain.
codex mcp add tideways --env TIDEWAYS_TOKEN=your-token -- npx -y tideways-mcp-serverThe Codex CLI, IDE extension and app share this entry in ~/.codex/config.toml.
Add to the client's MCP configuration (Cursor: ~/.cursor/mcp.json; Gemini CLI: ~/.gemini/settings.json; either also per project):
{
"mcpServers": {
"tideways": {
"command": "npx",
"args": ["-y", "tideways-mcp-server"],
"env": { "TIDEWAYS_TOKEN": "your-token" }
}
}
}Add to opencode.json in the project, or to ~/.config/opencode/opencode.json for all projects. {env:TIDEWAYS_TOKEN} reads the token from your shell's environment.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"tideways": {
"type": "local",
"command": ["npx", "-y", "tideways-mcp-server"],
"environment": { "TIDEWAYS_TOKEN": "{env:TIDEWAYS_TOKEN}" }
}
}
}Add to .vscode/mcp.json, or run MCP: Open User Configuration for all workspaces. VS Code asks for the token on first start and stores it.
{
"inputs": [
{ "type": "promptString", "id": "tideways-token", "description": "Tideways API token", "password": true }
],
"servers": {
"tideways": {
"type": "stdio",
"command": "npx",
"args": ["-y", "tideways-mcp-server"],
"env": { "TIDEWAYS_TOKEN": "${input:tideways-token}" }
}
}
}In any setup above, replace npx -y tideways-mcp-server with docker run -i --rm -e TIDEWAYS_TOKEN ghcr.io/abuhamza/tideways-mcp-server (pin a version with :2.0.0). For example:
claude mcp add tideways -e TIDEWAYS_TOKEN=your-token -- docker run -i --rm -e TIDEWAYS_TOKEN ghcr.io/abuhamza/tideways-mcp-server"command": "docker",
"args": ["run", "-i", "--rm", "-e", "TIDEWAYS_TOKEN", "ghcr.io/abuhamza/tideways-mcp-server"],
"env": { "TIDEWAYS_TOKEN": "your-token" }Related MCP server: otel-mcp-server
Tools
Tool | Answers |
| Which projects and scopes does my token have, and how much of the hourly rate limit is left? |
| Which services does a project have, and which of them serve "voucher"? |
| How is the app doing in any window of up to 24 h within the last ~30 days? Totals, layers, top transactions |
| When did one transaction get slow, and in which layer? Per-minute timeline and response-time histogram |
| Requests, errors and p95 in 15-minute buckets over up to 30 days |
| Which errors, slow SQL queries, deprecations, warnings or notices are open, resolved or ignored, in any service or transaction? |
| Where in the code does an issue fail, which transactions does it hit, and when did it start or stop? |
| Which individual requests were slow, in any transaction, and where did the time go? |
| Day, week or month report for a past date |
| Configuration problems and code bottlenecks Tideways detected (e.g. N+1 queries) |
All tools except tideways_list_projects take an optional project (name or organization/name).
Configuration
Environment variables; empty values count as unset. The server does not load .env files.
Variable | Default | Meaning |
| required | API token |
| the token's only project | Default project; with several projects and no default, pass |
| from the token's projects | Organization, to match a plain project name |
| API default | Default environment |
| the project's default service | Default service |
|
| API base URL, https only |
|
| Request timeout in ms, a positive integer up to |
|
|
|
Good to know
All times are UTC,
YYYY-MM-DD HH:mm. The API rate limit is per Tideways organization and clock hour; its size depends on the plan, and all tokens and projects of the organization share it.Tools read the project's default service unless you name one;
tideways_list_issuesreads all services. The API cannot list services;tideways_list_servicesfinds them through the issues of all services, and itssearchcosts one request per service.tideways_search_tracesreturns 30 traces per call, or up to 100 withlimit.Limits of the Tideways API: history for production and the default service only, issues 10 per page, and no trace filter by bottleneck (an N+1 observation's link opens the affected traces in Tideways).
Security
The token is read from the environment and never logged, and trace URLs are returned without query strings. Report vulnerabilities privately as described in SECURITY.md.
Development
npm ci
npm run check # the gate: typecheck, lint, format, tests, commit messages
npm run build && npm run inspect # try the tools in the MCP InspectorArchitecture, invariants and how to add a tool: CLAUDE.md. Commits follow Conventional Commits.
License
Available Tools
10 toolstideways_get_historyGet historical reportARead-onlyIdempotent
Daily, weekly or monthly performance report for a past date: total requests, error rate, p95, top 20 transactions by impact and a timeline. Use to compare days or weeks. A period that has not ended covers only its finished hours (pendingBuckets > 0), and today has no data until it ends; compare such periods per day or use tideways_get_performance_summary. Covers production and the project's default service only; for another environment or service use tideways_get_performance with end and minutes=1440 (one day per call).
Inputs: date (required), detail, project, granularity. Returns: raw, report, project, timeline, +4 more
tideways_get_issueGet issueARead-onlyIdempotent
Get one issue from tideways_list_issues in depth: the stack trace of its latest occurrence (first 15 frames) with the request it came from (URL, method, status, host, service), the transactions it occurred in with counts, and its occurrences per time bucket over the retention period. Use to point at the failing code, rank the affected endpoints, and say when the issue started, peaked or stopped. Pass the id and the type the issue was listed under.
Inputs: issueId (required), type, detail, project. Returns: id, raw, type, title, +15 more
tideways_get_observationsGet observationsARead-onlyIdempotent
Automatic findings Tideways made for a project: PHP configuration problems (e.g. OPcache buffers, timeouts) and code bottlenecks detected in traces (e.g. N+1 queries, sleep, waits). Use for a quick health check or optimization ideas. Findings do not name the affected requests, and the API cannot filter traces by bottleneck: give the user the link, whose page in the Tideways UI lists recent affected traces. Do not infer N+1 queries from slow-SQL issues.
Inputs: project, service, environment. Returns: project, criteria, observations
tideways_get_performanceGet performance metricsARead-onlyIdempotent
Performance of any window of 1-1440 minutes ending at "end" (default now) within the last ~30 days: totals (requests, error rate, p95/median/average response time, time per layer), the top 20 transactions by impact, and a timeline. Older windows return zeros; use tideways_get_history for them. For 15-minute trends over 30 days use tideways_get_performance_summary.
Inputs: end, detail, minutes, project, +2 more. Returns: raw, totals, project, criteria, +2 more
tideways_get_performance_summaryGet performance summaryARead-onlyIdempotent
Requests, errors and p95 response time in 15-minute buckets for the last hours hours (up to ~30 days), with totals. Use for trends, before/after comparisons and spotting incidents. For per-minute detail and top transactions use tideways_get_performance.
Inputs: hours, detail, project, service, +1 more. Returns: raw, totals, window, buckets, +3 more
tideways_get_transactionGet one transactionARead-onlyIdempotent
Timeline of one transaction over 1-1440 minutes ending at "end" (default now): per minute (or per bucket above 60 minutes) requests, errors, requests over the response-time target, p95/median/average and time per layer, plus totals with a response-time histogram. Use it to see when a transaction got slow and in which layer. Take transactionId from transactions[].id of tideways_get_performance.
Inputs: transactionId (required), end, minutes, project, +2 more. Returns: id, name, totals, project, +3 more
tideways_list_issuesList issuesARead-onlyIdempotent
List error, slow-SQL, deprecation, warning or notice issues of a project, newest occurrence first, 10 per page, with the total count. Use to find what is failing or slow and how often. Reads all services unless "service" is passed or configured; "transactionIds" narrows to issues of given transactions. One type and one status per call. There is no time filter; use lastOccurred to judge recency.
Inputs: page, type, detail, status, +4 more. Returns: raw, issues, hasMore, project, +3 more
tideways_list_projectsList Tideways projectsARead-onlyIdempotent
List the projects and scopes of the configured Tideways API token, and how much of the organization's hourly rate limit is left. Call this first when unsure which project to use, or after a scope or unknown-project error.
Inputs: no named parameters. Returns: scopes, projects, rateLimit, organization, +2 more
tideways_list_servicesList servicesARead-onlyIdempotent
List the services of a project (web, APIs, workers, CLI) named by its issues, the default service first. Call it when the user names an app, API or worker that is not a project, or a transaction that tideways_search_traces does not find in the default service, with "search" set to one word of it: each service is searched for that word and the services are sorted by matching traces, so the first ones serve it. Costs 4 requests, plus 1 per service searched: at most 30, fewer when the hourly rate limit is small or nearly used up. Only services named by the newest open or ignored issues are listed; the Tideways UI service selector lists all.
Inputs: search, project, environment. Returns: search, project, services, environment, +1 more
tideways_search_tracesSearch tracesARead-onlyIdempotent
Find individual request traces (30 per call unless "limit" asks for up to 100; newest first unless sortBy is set) with response time, memory, bottlenecks and the slowest layers. Use to investigate specific slow or failing requests; filter by transaction IDs from tideways_get_performance, text, time window and response time.
Inputs: to, from, limit, detail, +9 more. Returns: raw, count, traces, project, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools have clearly distinct purposes (list_issues vs get_issue, search_traces vs get_transaction). The performance family—get_performance, get_performance_summary, get_history, get_transaction—overlaps in domain but the descriptions carefully delineate granularity and use cases, leaving only mild ambiguity.
All tools follow a consistent tideways_<verb>_<noun> pattern (list_issues, get_performance, search_traces, get_observations). Prefix and verb/noun conventions are uniform throughout with no deviations.
Ten tools is well-scoped for an observability/monitoring server. Each tool maps to a distinct facet (issues, projects, services, performance, traces, history, observations) without redundancy.
The surface covers the core read workflows well: discovery (projects/services), performance windows, transactions, traces, issues and automatic findings. It is read-only by nature, so lifecycle coverage is reasonable, though some deeper drill-downs (e.g. arbitrary trace-by-bottleneck filtering) are noted as unavailable.
Maintenance
Related MCP Connectors
Query your app's logs, metrics and incidents from your AI assistant.
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Manage uptime monitors and incidents and search logs, metrics and traces from an AI assistant.
Ask your AI about your Airbnb and VRBO listings, bookings, guest messages and reviews. Read-only.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Mender IoT platform for device management, deployment monitoring, and fleet analysis through natural language commands. Provides read-only access to device status, deployment logs, releases, and system monitoring capabilities.2MIT
- AlicenseNot gradedqualityDmaintenanceEnables natural language querying and analysis of OpenTelemetry traces, metrics, and logs stored in Elasticsearch/OpenSearch, allowing AI assistants to investigate performance issues, find root causes, and explore system behavior.22 npm14MIT
- AlicenseNot gradedqualityCmaintenanceConnects AI assistants to New Relic with read-only access to NRQL, logs, metrics, traces, alerts, and more. Offers optional, gated write operations with a dry-run and confirmation workflow.53 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides Claude and other AI agents with read-only, guardrailed access to Pinpoint APM data, enabling production debugging through traces, metrics, transactions, and service topology.Apache 2.0