Tideways MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to queryTidewaysperformance monitoring data and provide conversational performance insights for PHP applications.

About Tideways:Tidewaysis a powerful application performance monitoring (APM) platform designed specifically for PHP applications. For technical details, see theREST API documentation.

Forked fromabuhamza/tideways-mcp-serverbyMouhammed Diop.

Repository:5hahiL/tideways-mcp-serverLicense: MIT

- Tidewaysaccount with a valid API token
- API token with appropriate scopes (metrics,issues,traces) - seeAPI documentation
- Access to a Tideways organization and project

{ "mcpServers": { "tideways": { "command": "npx", "args": ["tideways-mcp"], "env": { "TIDEWAYS_TOKEN": "your_token", "TIDEWAYS_ORG": "your_org", "TIDEWAYS_PROJECT": "your_project" } } } }

{ "mcpServers": { "tideways": { "command": "tideways-mcp", "env": { "TIDEWAYS_TOKEN": "your_token", "TIDEWAYS_ORG": "your_org", "TIDEWAYS_PROJECT": "your_project" } } } }

Cursor supports MCP through its settings. Add the server configuration in Cursor's MCP settings:
- Open Cursor Settings
- Tools & Integration
- Add a new server with:

{ "mcpServers": { "tideways": { "command": "tideways-mcp", "env": { "TIDEWAYS_TOKEN": "your_token", "TIDEWAYS_ORG": "your_org", "TIDEWAYS_PROJECT": "your_project" } } } }

If using VS Code with an MCP-compatible extension:

{ "mcp.servers": { "tideways": { "command": "npx", "args": ["tideways-mcp"], "env": { "TIDEWAYS_TOKEN": "your_token", "TIDEWAYS_ORG": "your_org", "TIDEWAYS_PROJECT": "your_project" } } } }

Once configured, you can ask your AI assistant questions like:

- "What's the current performance of my application?"
- "Show me recent errors in the last 24 hours"
- "How is my API performing compared to yesterday?"
- "What are the slowest transactions right now?"

Advanced Trace Analysis & Optimization

- "Analyze the/api/users/{id}endpoint and identify bottlenecks"
- "Find the root cause of slow performance in my checkout process"
- "Detect N+1 queries in my product listing endpoint and suggest fixes"
- "Analyze traces for/dashboardand recommend code optimizations"
- "Identify database query bottlenecks in my user authentication flow"
- "Find memory leaks or inefficient code paths in my API endpoints"
- "Analyze dependency injection overhead in my application"
- "Detect redundant database calls and suggest caching strategies"

- "Recommend performance improvements for my slowest endpoints"
- "Analyze my SQL queries and suggest indexing strategies"
- "Identify opportunities for query batching or lazy loading"
- "Find inefficient loops or recursive calls in my traces"
- "Suggest code refactoring based on performance bottlenecks"
- "Analyze memory usage patterns and recommend optimizations"

All tools return raw JSON from the Tideways API. The AI assistant (Claude, Cursor, etc.) performs the actual analysis and interpretation of this data.

Retrieve aggregate performance metrics and system-wide statistics.

- ts(optional): End timestamp in Y-m-d H:i format (e.g., "2025-08-12 18:30")
- m(optional): Number of minutes backward from timestamp (e.g., 60 for 1 hour, 1440 for 24 hours)
- env(optional): Filter by specific environment
- s(optional): Filter by specific service name

"What's the current performance of my application?" "Show me performance metrics for the last 6 hours" "Get metrics for the API service in production" "How is my web service performing in the staging environment?" "Compare today's metrics with the last 24 hours"

Returns:Raw performance data from Tideways including response times, throughput, error rates, and transaction breakdowns.

Retrieve time-series performance summary data in 15-minute intervals for trend analysis.

- s(optional): Service name to filter by (e.g., "web", "api", "worker"). Default: "web"

"Show me performance trends over the last few hours" "Get the performance summary for my API service" "How has my web service been performing recently?" "Display trends for the worker service" "Show me response time patterns for today"

Returns:Raw time-series data with 15-minute intervals showing response times, request counts, and error rates.

Retrieve and analyze recent errors, exceptions, and performance issues.

- issue_type(optional): "error", "slowsql", "deprecated", "all" (default: "all")
- status(optional): "open", "new", "resolved", "not_error", "ignored", "all" (default: "open")
- page(optional): Page number for pagination (default: 1)

"What errors are currently happening in my application?" "Show me all open errors from the last 24 hours" "Get slow SQL queries that need attention" "Are there any new performance issues I should know about?" "List all deprecated function calls in my code" "Show me resolved errors to understand what was fixed"

Returns:Raw issue data from Tideways including error types, occurrence counts, affected endpoints, and stack traces where available.

Analyze individual trace samples for detailed bottleneck identification and performance debugging.

- env(optional): Environment name (e.g., "production", "staging")
- s(optional): Service name (e.g., "web", "api", "worker")
- transaction_name(optional): Filter by specific transaction/endpoint name
- has_callgraph(optional): Only return traces with detailed callgraph data
- search(optional): Word-based search on transaction_name, host, and URL
- min_date(optional): Minimal date in YYYY-MM-DD HH:MM format (requires max_date)
- max_date(optional): Maximal date in YYYY-MM-DD HH:MM format (requires min_date)
- min_response_time_ms(optional): Minimum response time filter
- max_response_time_ms(optional): Maximum response time filter
- sort_by(optional): "response_time", "date", "memory" (default: "response_time")
- sort_order(optional): "ASC", "DESC" (default: "DESC")

"Analyze traces for the /api/products endpoint and find bottlenecks" "Show me the slowest requests from the last hour with details" "Find traces with callgraph data for the checkout process" "What's causing slow response times in my user registration flow?" "Detect N+1 query problems in my product listing page" "Analyze memory usage patterns in my API endpoints" "Find database bottlenecks in the /dashboard endpoint" "Show me traces where response time is over 2 seconds"

Returns:Raw trace data from Tideways including per-request timing, layer breakdown (SQL, Redis, HTTP, etc.), bottleneck flags, and callgraph data whenhas_callgraph: trueis set. Usehas_callgraph: truefor the deepest debugging detail.

Retrieve historical performance data for specific dates with configurable granularity.

- date(required): Date in YYYY-MM-DD format
- granularity(optional): "day", "week", "month" (default: "day")

"Get historical performance data for August 1st, 2025" "Show me weekly performance trends for last Monday" "Compare this month's performance with last month" "How did my application perform on 2025-07-15?" "Get daily performance data for the past week" "Show me monthly trends for the last quarter"

Returns:Raw historical performance data from Tideways for the specified date and granularity.

├── src/ │ ├── config/ # Configuration management │ ├── lib/ # Core libraries │ │ ├── errors.ts # Error handling utilities │ │ ├── logger.ts # Structured logging │ │ └── tideways-client.ts # Tideways API client │ ├── tools/ # MCP tool implementations │ │ ├── definitions.ts # Tool schema definitions │ │ ├── registry.ts # Tool execution registry │ │ └── handlers/ # Individual tool handlers │ ├── types/ # TypeScript type definitions │ ├── utils/ # Utility functions │ ├── server.ts # Main MCP server implementation │ └── index.ts # Application entry point ├── tests/ # Test suites └── dist/ # Compiled JavaScript (generated)

# Run all tests npm test # Run tests with coverage npm run test:coverage # Run tests in watch mode npm run test:watch # Run type checking npm run typecheck

# Build TypeScript to JavaScript npm run build # Clean build artifacts npm run clean

# Run linter npm run lint # Fix linting issues npm run lint:fix # Format code npm run format

- MCP Server(src/server.ts): Main server implementing MCP protocol, handles tool definitions and routing
- Tideways API Client(src/lib/tideways-client.ts): HTTP client with rate limiting, retry logic, and security measures
- Tool Registry(src/tools/): Modular tool system with individual handlers for each MCP tool
- Error Handler(src/lib/errors.ts): Centralized error handling with user-friendly messages
- Logger(src/lib/logger.ts): Structured JSON logging for monitoring and debugging
- Configuration(src/config/index.ts): Environment-based configuration management

AI Assistant ←→ MCP Protocol (stdio) ←→ TidewaysMCPServer → TidewaysClient → Tideways API ↓ Raw JSON Response → AI Assistant

This server uses araw JSON approachfor optimal performance:

- Direct API-to-LLM Pipeline: Tools returnJSON.stringify(apiData, null, 2)without formatting
- Zero Processing Overhead: No complex formatting, caching, or interpretation logic
- Complete Data Preservation: LLM receives all available data for flexible analysis
- Minimal Maintenance: No formatter or caching logic to maintain or debug

- Configurable Rate Limiter: SetTIDEWAYS_RATE_LIMITto match your Tideways plan (default: 2500/hr)
- Direct API Calls: All requests go directly to Tideways API without caching layer
- Retry Logic: Automatic retries for transient failures with exponential backoff

- API tokens stored securely in environment variables
- Authorization headers automatically redacted in logs asBearer [REDACTED]
- Rate limiting to respect Tideways API constraints
- Input validation on all MCP function parameters
- No sensitive data logged or exposed in error messages
- Automated security scanning: CodeQL, Snyk, TruffleHog, GitLeaks

The server provides structured JSON logs for monitoring:

{ "timestamp": "2025-08-09T10:00:00.000Z", "level": "info", "message": "Tool called", "context": { "toolName": "get_performance_metrics", "arguments": {"time_range": "24h"} } }

Error: Authentication failed. Please check your API token.

- VerifyTIDEWAYS_TOKENis correct and has required scopes (metrics,issues,traces)
- Check token hasn't expired
- Ensure organization and project names are correct

Error: Rate limit exceeded. Please try again later.

- SetTIDEWAYS_RATE_LIMITto match your actual plan limit
- Wait for rate limit reset (shown in error message)
- Built-in rate limiting respects your configured limit

Error: Network error: Unable to connect to Tideways API.

- Check internet connection
- Verify Tideways API is accessible from your network
- Check if corporate firewall blocks API access toapp.tideways.io
- Test with curl:curl -H "Authorization: Bearer YOUR_TOKEN" https://app.tideways.io/apps/api/_token

Error: MCP server not responding or connection failed

- Restart your AI assistant (Claude Desktop, Cursor, etc.)
- Verify MCP configuration file syntax is correct
- Check that the server command path is correct
- Ensure environment variables are properly set in MCP config
- Try running the server manually first:npx tideways-mcp

Enable debug logging for detailed troubleshooting:

# When running directly LOG_LEVEL=debug npx tideways-mcp # In MCP configuration, add to env: { "env": { "LOG_LEVEL": "debug", "TIDEWAYS_TOKEN": "your_token", ... } }

- Check the logs: Debug mode provides detailed information about requests and responses
- Verify configuration: Double-check all environment variables and MCP settings
- Test API access: Use curl to verify your Tideways API credentials work
- Report issues:GitHub Issueswith debug logs and configuration details
- Create a feature branch:git checkout -b your-feature
- Make changes and add tests:npm test
- Submit a pull request

This project is licensed under the MIT License - see theLICENSEfile for details.

Health intelligence MCP — access biomarkers, biological age, and personalized longevity action plans from your Aniva profile.