Skip to main content
Glama
Tideways MCP Server

Tideways MCP Server

by abuhamza

Tideways MCP Server

npm CI OpenSSF Scorecard

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-server

Add -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-server

The 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

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_issues reads all services. The API cannot list services; tideways_list_services finds them through the issues of all services, and its search costs one request per service.

  • tideways_search_traces returns 30 traces per call, or up to 100 with limit.

  • 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

MIT

Available Tools

10 tools
tideways_get_historyGet historical reportA
Read-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 issueA
Read-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 observationsA
Read-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 metricsA
Read-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 summaryA
Read-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 transactionA
Read-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 issuesA
Read-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 projectsA
Read-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 servicesA
Read-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 tracesA
Read-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

    A4.3/5.0

    Scored across 10 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      14
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects 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 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides 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