Aha.io

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 .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 54 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:

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

1. Install dependencies:

   bun install

1. Configure environment variables:

   export AHA_COMPANY="your-company"  # Your Aha.io subdomain

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

1. Start the server:

   # 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

1. For development with auto-reload:

   # 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

Semantic Search & Embeddings

The server includes advanced semantic search capabilities using vector embeddings.

Embedding Management Tools

• aha_generate_embeddings: Generate vector embeddings for entity text content
• aha_embedding_status: Check the status of embedding generation jobs
• aha_semantic_search: Search entities using natural language queries
• aha_generate_entity_embedding: Generate embedding for a specific entity
• aha_find_similar: Find entities similar to a given entity
• aha_pause_embeddings: Pause embedding generation jobs
• aha_stop_embeddings: Stop embedding generation jobs

Semantic Search Features

• Vector Storage: Embeddings stored in SQLite with sqlite-vec extension
• Multiple Models: Support for different embedding models (default: all-MiniLM-L6-v2)
• Similarity Search: Cosine similarity search with configurable thresholds
• Cross-Entity Search: Find similar content across different entity types
• Real-time Generation: Background embedding generation with progress tracking

Example Embedding Workflow

# Generate embeddings for features and ideas

aha_generate_embeddings --entities features,ideas --batchSize 25

Search for similar content

aha_semantic_search --query "user authentication security" --threshold 0.7

Find similar features to a specific feature

aha_find_similar --entityType features --entityId FEAT-123 --limit 5

Check embedding job progress

aha_embedding_status --jobId embed-xyz789

Available Resources

Breaking change: many collection resources (slim index lists like aha_features, and a few with a handful of scalar columns like aha_ideas) now return text/markdown - a link list or a table, depending on the record type - instead of a JSON array. Anything that used to parse those collections' contents as JSON needs to change. Collections with richer nested data (aha_goals, aha_initiatives, comment resources, and similar) are unaffected and, l