Tideways
Read-only access to Tideways PHP performance monitoring: performance, issues, traces, history.
Tideways MCP Server
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" }
}
}
}
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, scopes and rate-limit budget does my token have? |
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_performance_summary | Requests, errors and p95 in 15-minute buckets over up to 30 days |
tideways_list_issues | Which errors, slow SQL queries or deprecations are open, resolved or ignored? |
tideways_search_traces | Which individual requests were slow, 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 token and clock hour, shared by all projects. - Tools read the project's default service unless you name one. The API cannot list services;
tideways_list_servicesfinds them through open issues, and itssearchcosts one request per service. - Limits of the Tideways API: at most 30 traces per search, 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 typecheck && npm run lint && npm run format:check && npm test # the gate
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
Installation
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y tideways-mcp-serverSet up in your AI client
Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-abuhamza-tideways-mcp-server": {
"command": "npx",
"args": [
"-y",
"tideways-mcp-server"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencePackage
Compatible MCP Clients
Tideways works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
- Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect. - Cursor
~/.cursor/mcp.jsonRestart Cursor for changes to take effect. - VS Code
.vscode/mcp.jsonReload VS Code window for changes to take effect. - Windsurf
~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect. - Claude Code
.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.