Aha MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Aha.io's product management platform. Features offline database synchronization, vector embeddings for semantic search, and comprehensive workflow automation.

🔧 Client Configuration

MCP Registry

This server is published to the official MCP Registry as io.github.cedricziel/aha-mcp, so a client that browses the registry can install it without any of the configuration below:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.cedricziel/aha-mcp"

The registry holds metadata only. Its entry points at the three artifacts described below — the npm package, the ghcr.io image and the .mcpb desktop extension — and a client picks whichever it can run. Either way the server needs AHA_COMPANY and AHA_TOKEN.

Claude Desktop Extension (easiest)

Download aha-mcp-v<version>.mcpb from the latest release and open it with Claude Desktop, which will prompt you for your Aha.io subdomain and API token. No Node.js or Docker setup and no manual JSON editing required.

The extension exposes 50 tools that query Aha.io directly, so results are always current and nothing is stored locally. Cross-record search is served by Aha.io's own index — see Search.

Claude Desktop Configuration

To use this MCP server with Claude Desktop, add the following to your claude_desktop_config.json:

Using npx:

{
  "mcpServers": {
    "aha": {
      "command": "npx",
      "args": ["@cedricziel/aha-mcp"],
      "env": {
        "AHA_COMPANY": "your-company",
        "AHA_TOKEN": "your-api-token"
      }
    }
  }
}

Using Docker:

{
  "mcpServers": {
    "aha": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "AHA_COMPANY=your-company",
        "-e", "AHA_TOKEN=your-api-token",
        "ghcr.io/cedricziel/aha-mcp"
      ]
    }
  }
}

Note: Replace your-company and your-api-token with your actual Aha.io subdomain and API token.

🚀 Getting Started

Quick Start with npx

You can run the MCP server directly using npx without installing it globally:

# Set environment variables
export AHA_COMPANY="your-company"  # Your Aha.io subdomain
export AHA_TOKEN="your-api-token"   # Your Aha.io API token

# Run the server
npx @cedricziel/aha-mcp

Quick Start with Docker

You can also run the MCP server using Docker:

# Set environment variables
export AHA_COMPANY="your-company"  # Your Aha.io subdomain
export AHA_TOKEN="your-api-token"   # Your Aha.io API token

# Run in stdio mode (default)
docker run --rm -e AHA_COMPANY="$AHA_COMPANY" -e AHA_TOKEN="$AHA_TOKEN" ghcr.io/cedricziel/aha-mcp

# Run in Streamable HTTP mode (recommended for remote access)
docker run --rm -p 3001:3001 -e AHA_COMPANY="$AHA_COMPANY" -e AHA_TOKEN="$AHA_TOKEN" ghcr.io/cedricziel/aha-mcp --mode streamable-http

Development Setup

1. Install Bun if you haven't already:

   Terminal

   Copy

   curl -fsSL https://bun.sh/install | bash
   

2. Install dependencies:

   bash

   Copy

   bun install
   

3. Configure environment variables:

   server.ts

   Copy

   export AHA_COMPANY="your-company"  # Your Aha.io subdomain
   export AHA_TOKEN="your-api-token"   # Your Aha.io API token
   

4. Start the server:

   bash

   Copy

   # Start the stdio server (for MCP clients - default)
   bun start
   
   # Or start with Streamable HTTP (recommended for remote access)
   bun start -- --mode streamable-http
   
   # Or start the HTTP server (legacy entry point)
   bun run start:http
   

5. For development with auto-reload:

   bash

   Copy

   # Development mode with stdio
   bun run dev
   
   # Development mode with Streamable HTTP
   bun run dev -- --mode streamable-http
   
   # Development mode with HTTP (legacy)
   bun run dev:http
   

🔌 Aha.io Integration

This MCP server provides hybrid integration with Aha.io through both live API access and offline database synchronization. The server automatically maintains a local SQLite database with your Aha.io data, enabling faster queries, offline access, and advanced semantic search capabilities.

Architecture Overview

• Hybrid Data Access: Live API calls for real-time data + offline SQLite database for performance
• Background Sync: Automatic synchronization of Aha.io entities to local database
• Vector Embeddings: Semantic search using sentence transformers and SQLite vector extensions
• Real-time Progress: Background job monitoring with detailed progress tracking
• Configuration Management: Runtime configuration without server restarts

Configuration

The Aha.io integration can be configured using multiple methods, with the following priority order:

1. Environment Variables (highest priority)
2. Configuration File (~/.aha-mcp-config.json)
3. Default Values (lowest priority)

Environment Variables

• AHA_COMPANY: Your Aha.io subdomain (e.g., mycompany for mycompany.aha.io)
• AHA_TOKEN: Your Aha.io API token (for API token authentication)
• AHA_ACCESS_TOKEN: Your OAuth 2.0 access token (for OAuth authentication)
• MCP_TRANSPORT_MODE: Transport mode (stdio or streamable-http)
• MCP_PORT: Port number for HTTP-based modes (default: 3001)
• MCP_HOST: Host address for HTTP-based modes (default: 0.0.0.0)
• MCP_AUTH_TOKEN: Authentication token for HTTP-based modes (optional)
• MCP_TOOL_RATE_LIMIT_PER_MINUTE: Tool calls allowed per minute (default: 120, 0 disables)

Transport Modes

The server supports two transport modes:

1. stdio: Standard input/output mode for MCP client integration (default)
2. streamable-http: HTTP transport (MCP protocol 2025-06-18), for remote and web clients

Example usage:

# Stdio mode (default)
aha-mcp

# Streamable HTTP mode
aha-mcp --mode streamable-http --port 3001

Removed: the sse transport was deprecated in MCP spec 2025-03-26 and has been removed. MCP_TRANSPORT_MODE=sse and --mode sse now fall back to streamable-http with a warning, so existing configurations keep starting.

Authentication (HTTP transport)

The streamable-http transport supports optional Bearer token authentication:

Environment Variable Configuration

# Set authentication token
export MCP_AUTH_TOKEN="your-secure-token-here"

# Start server with authentication
aha-mcp --mode streamable-http --port 3001

Client Authentication

When authentication is enabled, clients must include a Bearer token in the Authorization header. All MCP traffic goes to the single /mcp endpoint:

curl -X POST \
     -H "Authorization: Bearer your-secure-token-here" \
     -H "Content-Type: application/json" \
     -H "MCP-Protocol-Version: 2025-06-18" \
     -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' \
     http://localhost:3001/mcp

Most callers should use an MCP client library rather than raw HTTP; pass the token as an Authorization header when constructing the transport.

Security Notes

• Opt-in: Authentication is optional. If MCP_AUTH_TOKEN is not set, all requests are allowed.
• Token Security: Use strong, randomly generated tokens (minimum 8 characters).
• HTTPS: In production, always use HTTPS to protect tokens in transit.
• Token Storage: Tokens are obfuscated (base64 encoded) in the configuration file but should be treated as sensitive data.

Checking Authentication Status

curl http://localhost:3001/

# Response includes:
# {
#   "authentication": {
#     "enabled": true,
#     "type": "Bearer token"
#   }
# }

Configuration Management Tools

The server provides three MCP tools for configuration management:

1. configure_server: Update server settings at runtime
2. get_server_config: View current configuration and validation status
3. test_configuration: Test API connectivity with current settings

These tools allow you to manage configuration without restarting the server, making it easy to switch between different Aha.io accounts or update credentials.

Database Synchronization

The server maintains a local SQLite database with your Aha.io data for improved performance and offline access.

Sync Management Tools

• aha_sync_start: Start background synchronization of specified entity types
• aha_sync_status: Check the status and progress of sync jobs
• aha_sync_stop: Stop a running sync job
• aha_sync_pause: Pause a sync job (can be resumed later)
• aha_sync_resume: Resume a paused sync job
• aha_sync_history: View detailed history of sync operations
• aha_sync_health: Get overall sync service health status
• aha_database_health: Check database connectivity and statistics
• aha_database_cleanup: Clean up old sync jobs and optimize database

Sync Features

• Entity Types: Sync features, products, ideas, epics, initiatives, releases, goals, users, comments
• Progress Tracking: Real-time progress updates with detailed statistics
• Error Handling: Comprehensive error logging and recovery mechanisms
• Batch Processing: Configurable batch sizes for optimal performance
• Incremental Updates: Support for updatedSince filtering to sync only recent changes
• Concurrent Operations: Multiple sync jobs can run simultaneously

Example Sync Workflow

# Start syncing features and products
aha_sync_start --entities features,products --batchSize 50

# Check progress
aha_sync_status --jobId sync-abc123

# View sync history
aha_sync_history --jobId sync-abc123 --limit 20

# Check overall health
aha_sync_health