What is Aha Mcp

aha-mcp is a Model Context Protocol (MCP) server designed for accessing Aha! records. It facilitates seamless interaction with Aha! features, requirements, and pages through the MCP.

Use cases

Use cases for aha-mcp include automating the retrieval of Aha! records, integrating Aha! features into custom applications, and enhancing collaboration within development teams by providing direct access to project requirements.

How to use

To use aha-mcp, you can either run it using npx or install it manually by cloning the repository and installing dependencies. Ensure you have Node.js and npm installed, and set up your Aha! API token and domain as environment variables.

Key features

Key features of aha-mcp include easy integration with Aha! records, support for API authentication, and the ability to manage environment variables securely. It allows developers to interact with Aha! features programmatically.

Where to use

aha-mcp can be used in software development environments where Aha! records need to be accessed or manipulated, particularly in project management, product development, and agile methodologies.

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 if you access aha at 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

The instructions below were copied from the instructions found here.

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

Cursor

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

Cline

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

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:

Claude Desktop

Add a configuration to your claude_desktop_config.json:

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