aha-mcp

Model Context Protocol (MCP) server for accessing Aha! records through the MCP. This integration enables seamless interaction with Aha! features, requirements, and pages directly through the Model Context Protocol.

Prerequisites

• Node.js v20 or higher
• npm (usually comes with Node.js)
• An Aha! account with API access

Installation

Using npx

npx -y aha-mcp@latest

Manual Installation

# Clone the repository
git clone https://github.com/aha-develop/aha-mcp.git
cd aha-mcp

# Install dependencies
npm install

# Run the server
npm run mcp-start

Authentication Setup

1. Log in to your Aha! account at <yourcompany>.aha.io
2. Visit secure.aha.io/settings/api_keys
3. Click "Create new API key"
4. Copy the token immediately (it won't be shown again)

For more details about authentication and API usage, see the Aha! API documentation.

Environment Variables

This MCP server requires the following environment variables:

• AHA_API_TOKEN: Your Aha! API token
• AHA_DOMAIN: Your Aha! domain (e.g., yourcompany.aha.io)

IDE Integration

For security reasons, we recommend using your preferred secure method for managing environment variables rather than storing API tokens directly in editor configurations. Each editor has different security models and capabilities for handling sensitive information.

Below are examples of how to configure various editors to use the aha-mcp server. You should adapt these examples to use your preferred secure method for providing the required environment variables.

VSCode

Add this to your .vscode/settings.json, using your preferred method to securely provide the environment variables:

{
  "mcpServers": {
    "aha-mcp": {
      "command": "npx",
      "args": ["-y", "aha-mcp"]
      // Environment variables should be provided through your preferred secure method
    }
  }
}

Cursor

1. Go to Cursor Settings > MCP
2. Click + Add new Global MCP Server
3. Add a configuration similar to:

{
  "mcpServers": {
    "aha-mcp": {
      "command": "npx",
      "args": ["-y", "aha-mcp"]
      // Environment variables should be provided through your preferred secure method
    }
  }
}

Cline

Add a configuration to your cline_mcp_settings.json via Cline MCP Server settings:

{
  "mcpServers": {
    "aha-mcp": {
      "command": "npx",
      "args": ["-y", "aha-mcp"]
      // Environment variables should be provided through your preferred secure method
    }
  }
}

RooCode

Open the MCP settings by either:

• Clicking "Edit MCP Settings" in RooCode settings, or
• Using the "RooCode: Open MCP Config" command in VS Code's command palette

Then add:

{
  "mcpServers": {
    "aha-mcp": {
      "command": "npx",
      "args": ["-y", "aha-mcp"]
      // Environment variables should be provided through your preferred secure method
    }
  }
}

Claude Desktop

Add a configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "aha-mcp": {
      "command": "npx",
      "args": ["-y", "aha-mcp"]
      // Environment variables should be provided through your preferred secure method
    }
  }
}

Available MCP Tools

1. get_record

Retrieves an Aha! feature or requirement by reference number.

Parameters:

• reference (required): Reference number of the feature or requirement (e.g., "DEVELOP-123")

Example:

{
  "reference": "DEVELOP-123"
}

Response:

{
  "reference_num": "DEVELOP-123",
  "name": "Feature name",
  "description": "Feature description",
  "workflow_status": {
    "name": "In development",
    "id": "123456"
  }
}

2. get_page

Gets an Aha! page by reference number.

Parameters:

• reference (required): Reference number of the page (e.g., "ABC-N-213")
• includeParent (optional): Include parent page information. Defaults to false.

Example:

{
  "reference": "ABC-N-213",
  "includeParent": true
}

Response:

{
  "reference_num": "ABC-N-213",
  "name": "Page title",
  "body": "Page content",
  "parent": {
    "reference_num": "ABC-N-200",
    "name": "Parent page"
  }
}

3. search_documents

Searches for Aha! documents.

Parameters:

• query (required): Search query string
• searchableType (optional): Type of document to search for (e.g., "Page"). Defaults to "Page"

Example:

{
  "query": "product roadmap",
  "searchableType": "Page"
}

Response:

{
  "results": [
    {
      "reference_num": "ABC-N-123",
      "name": "Product Roadmap 2025",
      "type": "Page",
      "url": "https://company.aha.io/pages/ABC-N-123"
    }
  ],
  "total_results": 1
}

Example Queries

• "Get feature DEVELOP-123"
• "Fetch the product roadmap page ABC-N-213"
• "Search for pages about launch planning"
• "Get requirement ADT-123-1"
• "Find all pages mentioning Q2 goals"

Configuration Options

Variable	Description	Default
AHA_API_TOKEN	Your Aha! API token	Required
AHA_DOMAIN	Your Aha! domain (e.g., yourcompany.aha.io)	Required
LOG_LEVEL	Logging level (debug, info, warn, error)	info
PORT	Port for SSE transport	3000
TRANSPORT	Transport type (stdio or sse)	stdio

Troubleshooting

Common Issues

1. Authentication errors:

   • Verify your API token is correct and properly set in your environment
   • Ensure the token has the necessary permissions in Aha!
   • Confirm you're using the correct Aha! domain

2. Server won't start:

   • Ensure all dependencies are installed
   • Check the Node.js version is v20 or higher
   • Verify the TypeScript compilation succeeds
   • Confirm environment variables are properly set and accessible

3. Connection issues:

   • Check your network connection
   • Verify your Aha! domain is accessible
   • Ensure your API token has not expired

4. API Request failures:

   • Check the reference numbers are correct
   • Verify the searchable type is valid
   • Ensure you have permissions to access the requested resources

5. Environment variable issues:

   • Make sure environment variables are properly set and accessible to the MCP server
   • Check that your secure storage method is correctly configured
   • Verify that the environment variables are being passed to the MCP server process