About Tideways
Tideways MCP Server is an unofficial, read-only connector for Tideways PHP performance data. It is for teams investigating application performance, errors, and traces through an AI assistant, using Tideways REST API GET endpoints.
Key features
- 01Read performance metrics and summaries
- 02Inspect transactions and response-time history
- 03List and examine issues
- 04Search slow request traces
- 05Retrieve historical reports and observations
Use cases
- 01Investigate a slow transaction from yesterday
- 02Review errors and slow SQL across services
- 03Find where individual requests spend time
MCP support
The MCP server exposes tools that query Tideways projects, services, performance metrics, issues, traces, history, and observations. All API access is read-only and uses GET endpoints.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
We haven’t collected a package or remote endpoint for this server. Follow the instructions in the project README.
Tools
10Saved tool list · updated 2w ago
This tool takes no parameters.
Details
From the project READMETideways 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 Code
claude mcp add tideways -e TIDEWAYS_TOKEN=your-token -- npx -y tideways-mcp-server
Add -s user to use it in every project.
Claude Desktop
Open the .mcpb bundle from the latest release. It asks for the token and keeps it in the OS keychain.
Codex
codex mcp add tideways --env TIDEWAYS_TOKEN=your-token -- npx -y tideways-mcp-server
The Codex CLI, IDE extension and app share this entry in ~/.codex/config.toml.
Cursor, Gemini CLI and other clients
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" }
}
}
}
OpenCode
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}" }
}
}
}
VS Code
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}" }
}
}
}
Docker
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" }
Tools
| Tool | Answers |
|---|---|
tideways_list_projects | Which projects and scopes does my token have, and how much of the hourly rate limit is left? |
tideways_list_services | Which services does a project have, and which of them serve "voucher"? |
tideways_get_performance | How is the app doing in any window of up to 24 h within the last ~30 days? Totals, layers, top transactions |
tideways_get_transaction | When did one transaction get slow, and in which layer? Per-minute timeline and response-time histogram |
tideways_get_performance_summary | Requests, errors and p95 in 15-minute buckets over up to 30 days |
tideways_list_issues | Which errors, slow SQL queries, deprecations, warnings or notices are open, resolved or ignored, in any service or transaction? |
tideways_get_issue | Where in the code does an issue fail, which transactions does it hit, and when did it start or stop? |
tideways_search_traces | Which individual requests were slow, in any transaction, and where did the time go? |
tideways_get_history | Day, week or month report for a past date |
tideways_get_observations | 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 |
|---|---|---|
TIDEWAYS_TOKEN | required | API token |
TIDEWAYS_PROJECT | the token's only project | Default project; with several projects and no default, pass project per call |
TIDEWAYS_ORG | from the token's projects | Organization, to match a plain project name |
TIDEWAYS_ENV | API default | Default environment |
TIDEWAYS_SERVICE | the project's default service | Default service |
TIDEWAYS_BASE_URL | https://app.tideways.io/apps/api | API base URL, https only |
TIDEWAYS_REQUEST_TIMEOUT | 30000 | Request timeout in ms, a positive integer up to 600000 |
LOG_LEVEL | info | debug, info, warn or error, case-insensitive; logs go to stderr |
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 Inspector
Architecture, invariants and how to add a tool: CLAUDE.md. Commits follow Conventional Commits.
License
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.