# Tideways Mcp Server

> MCP server from abuhamza/tideways-mcp-server.

- **Type:** MCP server
- **Install:** `agentstack add mcp-abuhamza-tideways-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [abuhamza](https://agentstack.voostack.com/s/abuhamza)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [abuhamza](https://github.com/abuhamza)
- **Source:** https://github.com/abuhamza/tideways-mcp-server

## Install

```sh
agentstack add mcp-abuhamza-tideways-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Tideways MCP Server

[](https://github.com/abuhamza/tideways-mcp-server/actions/workflows/ci.yml)
[](https://github.com/abuhamza/tideways-mcp-server/actions/workflows/release.yml)
[](https://github.com/abuhamza/tideways-mcp-server/actions/workflows/security.yml)
[](https://github.com/abuhamza/tideways-mcp-server/security/code-scanning)
[](https://codecov.io/gh/abuhamza/tideways-mcp-server)
[](https://www.npmjs.com/package/tideways-mcp-server)
[](https://www.npmjs.com/package/tideways-mcp-server)
[](https://www.npmjs.com/package/tideways-mcp-server)
[](https://github.com/abuhamza/tideways-mcp-server/security/dependabot)

A Model Context Protocol (MCP) server that enables AI assistants to query [Tideways](https://tideways.com/) performance monitoring data and provide conversational performance insights for PHP applications.

> **About Tideways**: [Tideways](https://tideways.com/) is a powerful application performance monitoring (APM) platform designed specifically for PHP applications. For technical details, see the [REST API documentation](https://support.tideways.com/documentation/reference/index.html).

## Features

- **Conversational Performance Insights**: Get performance data in natural language format optimized for AI assistants
- **AI Assistant Integration**: Works with Claude Desktop, Cursor, Claude Code, and other MCP-compatible tools
- **Real-time Performance Metrics**: Query current performance data with intelligent rate limiting
- **Issue Analysis**: Retrieve and analyze errors, exceptions, and performance issues
- **Intelligent API Management**: Built-in rate limiting with respect for Tideways API constraints
- **Robust Error Handling**: Comprehensive error handling with user-friendly messages

**Package Information:**
- **NPM Package**: [`tideways-mcp-server`](https://www.npmjs.com/package/tideways-mcp-server)
- **Repository**: [abuhamza/tideways-mcp-server](https://github.com/abuhamza/tideways-mcp-server)
- **Latest Version**: Check [npm version badge](#) above
- **License**: MIT

## Prerequisites

- [Tideways](https://tideways.com/) account with a valid API token
- API token with appropriate scopes (`metrics`, `issues`, `traces`) - see [API documentation](https://support.tideways.com/documentation/reference/index.html)
- Access to a Tideways organization and project

## AI Integration Setup

**This is an MCP (Model Context Protocol) server designed exclusively for AI assistants. It cannot be used as a standalone CLI tool.**

The server integrates with AI assistants through MCP configuration using the npm package `tideways-mcp-server`.

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `TIDEWAYS_TOKEN` | ✅ | - | Tideways API access token (see Security section) |
| `TIDEWAYS_ORG` | ✅ | - | Tideways organization name |
| `TIDEWAYS_PROJECT` | ✅ | - | Tideways project name |
| `TIDEWAYS_BASE_URL` | ❌ | `https://app.tideways.io/apps/api` | Tideways API base URL |
| `TIDEWAYS_MAX_RETRIES` | ❌ | `3` | Maximum API retry attempts |
| `TIDEWAYS_REQUEST_TIMEOUT` | ❌ | `30000` | API request timeout (ms) |
| `LOG_LEVEL` | ❌ | `info` | Log level (debug, info, warn, error) |

## AI Assistant Integration

**This server only works with MCP-compatible AI assistants. It uses stdio transport.**

#### Claude Desktop

Add to your Claude Desktop MCP configuration file:

**Location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/claude/claude_desktop_config.json`

**Configuration (Recommended - using npx):**
```json
{
  "mcpServers": {
    "tideways": {
      "command": "npx",
      "args": ["tideways-mcp-server"],
      "env": {
        "TIDEWAYS_TOKEN": "your_token",
        "TIDEWAYS_ORG": "your_org",
        "TIDEWAYS_PROJECT": "your_project"
      }
    }
  }
}
```

**Alternative (if installed globally):**
```json
{
  "mcpServers": {
    "tideways": {
      "command": "tideways-mcp-server",
      "env": {
        "TIDEWAYS_TOKEN": "your_token",
        "TIDEWAYS_ORG": "your_org",
        "TIDEWAYS_PROJECT": "your_project"
      }
    }
  }
}
```

#### Cursor IDE

Cursor supports MCP through its settings. Add the server configuration in Cursor's MCP settings:

1. Open Cursor Settings
2. Tools & Integration
3. Add a new server with:
```json
{
  "mcpServers": {
    "tideways": {
      "command": "tideways-mcp-server",
      "env": {
        "TIDEWAYS_TOKEN": "your_token",
        "TIDEWAYS_ORG": "your_org",
        "TIDEWAYS_PROJECT": "your_project"
      }
    }
  }
}
```

#### VS Code with MCP Extension

If using VS Code with an MCP-compatible extension:

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

### Using with AI Assistants

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

#### Basic Performance Queries
- "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 `/dashboard` and 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"

#### Performance Optimization Suggestions
- "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"

## Available MCP Tools

All tools return structured JSON data for optimal AI assistant integration. The MCP server follows a "raw JSON approach" where tools return complete API responses without formatting, allowing AI assistants to analyze and present data flexibly.

### `get_performance_metrics`

Retrieve aggregate performance metrics and system-wide statistics.

**Parameters:**
- `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

**Conversational Examples:**
```
"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:** Complete performance data including response times, throughput, error rates, memory usage, and database performance.

### `get_performance_summary`

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

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

**Conversational Examples:**
```
"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:** Time-series data with 15-minute intervals showing response times, request counts, error rates, and resource utilization trends.

### `get_issues`

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

**Parameters:**
- `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)

**Conversational Examples:**
```
"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:** Detailed error information including stack traces, occurrence frequency, affected endpoints, and suggested fixes for common issues.

### `get_traces`

Analyze individual trace samples for detailed bottleneck identification and performance debugging. Includes advanced AI-powered bottleneck detection and optimization recommendations.

**Parameters:**
- `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")

**Conversational Examples:**
```
"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:** Detailed trace data with AI-powered analysis including:
- Individual request traces with timing breakdown
- Bottleneck detection (database, CPU, memory, API calls)
- N+1 query detection and suggested fixes
- Performance optimization recommendations
- Call graph visualization data
- Resource utilization analysis

### `get_historical_data`

Retrieve historical performance data for specific dates with configurable granularity.

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

**Conversational Examples:**
```
"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:** Historical performance metrics with trend analysis, comparisons to previous periods, and insights into performance patterns over time.

## Development

### Project Structure

```
├── 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)
```

### Running Tests

```bash
# 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
```

### Building

```bash
# Build TypeScript to JavaScript
npm run build

# Clean build artifacts
npm run clean
```

### Code Quality

```bash
# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format
```

## Architecture

### Core Components

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

### Data Flow

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

### Response Format Philosophy

This server uses a **simplified raw JSON approach** for optimal performance:
- **Direct API-to-LLM Pipeline**: Tools return `JSON.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
- **Modern LLM Optimized**: GPT-4/Claude excel at parsing structured JSON data
- **Minimal Maintenance**: No formatter or caching logic to maintain or debug

### Rate Limiting Strategy

- **Rate Limiter**: Built-in rate limiting respects Tideways API constraints (900 requests/hour by default)
- **Direct API Calls**: All requests go directly to Tideways API without caching layer
- **Retry Logic**: Automatic retries for transient failures with exponential backoff
- **YAGNI Principle**: No caching complexity until performance issues are observed

## 🛡️ Security

- API tokens stored securely in environment variables
- Rate limiting to respect Tideways API constraints
- Input validation on all MCP function parameters
- No sensitive data logged or exposed in error messages

## 📊 Monitoring

The server provides structured JSON logs for monitoring:

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

## 🔧 Troubleshooting

### Common Issues

**Authentication Error**
```
Error: Authentication failed. Please check your API token.
```
- Verify `TIDEWAYS_TOKEN` is correct and has required scopes (`metrics`, `issues`, `traces`)
- Check token hasn't expired
- Ensure organization and project names are correct
- Verify environment variables are properly loaded

**Rate Limit Exceeded**
```
Error: Rate limit exceeded. Please try again later.
```
- Wait for rate limit reset (shown in error message)
- Reduce query frequency
- Built-in rate limiting respects Tideways API constraints (900 requests/hour)

**Connection Issues**
```
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 to `app.tideways.io`
- Test with curl: `curl -H "Authorization: Beare

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [abuhamza](https://github.com/abuhamza)
- **Source:** [abuhamza/tideways-mcp-server](https://github.com/abuhamza/tideways-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-abuhamza-tideways-mcp-server
- Seller: https://agentstack.voostack.com/s/abuhamza
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.