# Claude Desktop Configuration for MCP Coroot

**IMPORTANT DOCUMENTATION POLICY**: This project maintains only two documentation files:
- `README.md` - Public-facing project documentation
- `CLAUDE.md` - Internal instructions and configuration details
- (Exception: `LICENSE` and `CHANGELOG` files are also allowed)

Please DO NOT create any other markdown documentation files. All documentation should be consolidated into these two files.

---

This file contains instructions for configuring the MCP Coroot server with Claude Desktop.

## Overview

The MCP Coroot server provides 58 tools for interacting with Coroot observability platform:
- Authentication and user management (5 tools)
- Project creation and management (8 tools)
- Application monitoring and troubleshooting (3 tools)
- Infrastructure overview and incidents (2 tools)
- Deployment and system overviews (5 tools)
- Dashboard management (5 tools)
- Integration configuration (4 tools)
- Configuration management (7 tools)
- Advanced troubleshooting (3 tools)
- Custom cloud pricing (3 tools)
- Database instrumentation (2 tools)
- System configuration (4 tools)
- Risk overview (1 tool)
- Health checks (1 tool)
- Panel data and advanced configuration (6 tools)

Test coverage: 87% (179 tests passing)

## Quick Setup

### Using Published Package (Recommended)

Edit your Claude Desktop configuration:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "coroot": {
      "command": "uvx",
      "args": ["mcp-coroot"],
      "env": {
        "COROOT_BASE_URL": "http://localhost:8080",
        "COROOT_USERNAME": "admin",
        "COROOT_PASSWORD": "your-password"
      }
    }
  }
}
```

### For SSO/MFA Users

If your organization uses SSO or MFA, use session cookie authentication:

```json
{
  "mcpServers": {
    "coroot": {
      "command": "uvx",
      "args": ["mcp-coroot"],
      "env": {
        "COROOT_BASE_URL": "http://localhost:8080",
        "COROOT_SESSION_COOKIE": "your-auth-cookie-value"
      }
    }
  }
}
```

To get your session cookie:
1. Login to Coroot through your browser
2. Open Developer Tools (F12)
3. Go to Application/Storage → Cookies
4. Copy the value of the `auth` cookie

### For Local Development

If you're developing or testing locally:

**macOS**:
```json
{
  "mcpServers": {
    "coroot": {
      "command": "uv",
      "args": ["run", "mcp-coroot"],
      "cwd": "/path/to/mcp-coroot",
      "env": {
        "COROOT_BASE_URL": "http://localhost:8080",
        "COROOT_USERNAME": "admin",
        "COROOT_PASSWORD": "your-password"
      }
    }
  }
}
```

**Windows**:
```json
{
  "mcpServers": {
    "coroot": {
      "command": "uv",
      "args": ["run", "mcp-coroot"],
      "cwd": "C:\\path\\to\\mcp-coroot",
      "env": {
        "COROOT_BASE_URL": "http://localhost:8080",
        "COROOT_USERNAME": "admin",
        "COROOT_PASSWORD": "your-password"
      }
    }
  }
}
```

## Authentication Methods

The server supports three authentication methods:

1. **Username/Password** (Recommended) - Automatic login and session management
2. **Session Cookie** - Required for SSO/MFA environments
3. **API Key** - Limited to data ingestion endpoints only

## Available Commands

Once configured, you can ask Claude to:

### Monitoring & Analysis
- "Show me all Coroot projects"
- "Check the health of all applications in production"
- "Show me error logs for the API service in the last hour"
- "Find slow traces in the payment service"
- "Analyze why the frontend has high latency"
- "Show CPU profiling data for the backend service"

### Infrastructure Management
- "List all nodes in the production project"
- "Show me the resource usage of server01"
- "Check for any incidents in the last 24 hours"
- "Display the deployment history"
- "Show me the risk assessment for our infrastructure"

### Configuration & Integration
- "Set up Slack notifications for critical alerts"
- "Configure Prometheus integration"
- "Update SLO thresholds for the API service"
- "Show me the application categorization rules"
- "Create a custom dashboard for Redis monitoring"

### Advanced Features
- "Perform root cause analysis on the payment service failures"
- "Show database instrumentation settings for PostgreSQL"
- "Configure custom cloud pricing for our AWS instances"
- "Update the AI configuration for RCA"
- "List all API keys for the production project"

## Known Limitations

Some Coroot API endpoints have limitations:

### Large Response Warnings
- **Traces**: Can return 100k+ tokens. Use time filters to limit data.
- **Profiling**: Can return 180k+ tokens. Always specify time ranges.

### Empty Response Handling
Some endpoints return empty bodies on success. The MCP server handles these gracefully.

### Not Yet Implemented
- Dashboard CRUD operations (limited functionality)
- RCA feature (returns "not implemented yet")
- Role creation/update (405 Method Not Allowed)

### FastMCP Type Conversion Workaround
Due to a known issue in FastMCP v2.10.6, the following tools have workarounds for parameter type conversion:
- `configure_profiling`: The `sample_rate` parameter accepts strings (e.g., "0.1") and converts to float
- `configure_tracing`: The `sample_rate` accepts strings, and `excluded_paths` accepts JSON strings (e.g., '["/health", "/metrics"]')

This workaround ensures compatibility with MCP clients that pass all parameters as strings. The implementation handles both string and native types transparently.

## Troubleshooting

### Connection Issues
- Verify COROOT_BASE_URL is correct and accessible
- Check if Coroot is running: `curl http://localhost:8080/health`
- Ensure no firewall is blocking the connection

### Authentication Errors
- For basic auth: Verify username and password are correct
- For SSO/MFA: Ensure session cookie is valid and not expired
- Session cookies expire after 7 days of inactivity

### Tool Errors
- "Tool not found": Restart Claude Desktop after configuration changes
- Large responses: Use time filters to reduce data size
- Empty responses: Normal for some operations (deletes, updates)

## Development

To run the server manually for testing:

```bash
# Clone and install
git clone https://github.com/jamesbrink/mcp-coroot.git
cd mcp-coroot
uv sync --all-groups

# Run with environment variables
COROOT_BASE_URL=http://localhost:8080 \
COROOT_USERNAME=admin \
COROOT_PASSWORD=your-password \
uv run mcp-coroot
```

### Running Tests
```bash
# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov

# Run specific test
uv run pytest tests/test_server.py -v
```

## Support

For issues or questions:
- GitHub Issues: https://github.com/jamesbrink/mcp-coroot/issues
- Coroot Documentation: https://coroot.com/docs