Skip to main content
Glama
popand

aha-mcp

by popand
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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

Related MCP server: TeamDesk MCP Server

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
}

4. create_feature

Creates a new feature in Aha!

Parameters:

  • release_id (required): Numeric ID or key of the release to create the feature in

  • name (required): Name of the feature

  • workflow_kind (optional): Type of feature

  • workflow_status (optional): Object with name or id of the workflow status

  • description (optional): Description of the feature (may include HTML formatting)

  • assigned_to_user (optional): Object with email or id of the assigned user

  • tags (optional): Comma-separated tags to apply to the feature

  • initial_estimate_text (optional): Initial estimated effort (e.g., "2d 1h" for time or "4p" for points)

  • start_date (optional): Date work will start (YYYY-MM-DD format)

  • due_date (optional): Date work is due (YYYY-MM-DD format)

  • initiative (optional): Name or ID of initiative

  • epic (optional): Name or ID of epic

  • team (optional): Numeric ID or key of the team

Example:

{
  "release_id": "PRJ1-R-1",
  "name": "New Mobile App Feature",
  "workflow_kind": "new",
  "workflow_status": {
    "name": "Under consideration"
  },
  "description": "<p>Implement push notifications for mobile app</p>",
  "assigned_to_user": {
    "email": "developer@company.com"
  },
  "tags": "mobile,notifications,push"
}

Response:

{
  "id": "12345",
  "reference_num": "DEVELOP-789",
  "name": "New Mobile App Feature",
  "description": "<p>Implement push notifications for mobile app</p>",
  "workflow_status": {
    "id": "67890",
    "name": "Under consideration"
  },
  "assigned_to_user": {
    "id": "54321",
    "name": "John Developer",
    "email": "developer@company.com"
  },
  "release": {
    "id": "11111",
    "name": "Q2 2024 Release",
    "reference_num": "PRJ1-R-1"
  },
  "tags": "mobile,notifications,push"
}

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"

  • "Create a new feature called 'User Authentication' in release PRJ1-R-1"

  • "Create a feature for mobile push notifications in release MOBILE-R-2"

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

  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. Feature creation errors (create_feature tool):

    • 404 "Record not found": The release_id doesn't exist or you don't have access to it

      • Verify the release ID format (e.g., "PRJ1-R-1", "PROJ-R-123")

      • Check that the release exists in your Aha! workspace

      • Ensure your API token has permissions to create features in that release

    • 403 "Forbidden": Your API token lacks permissions to create features

    • 422 "Unprocessable Entity": Invalid field values (check workflow_status names, user emails, etc.)

    • To find valid release IDs: Use the Aha! UI or call GET /api/v1/releases endpoint

  6. 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

Available Tools

4 tools
create_featureB

Create a new feature in Aha!

ParametersJSON Schema
NameRequiredDescriptionDefault
epicNoName or ID of epic
nameYesName of the feature (required)
tagsNoTags to add to the feature (comma-separated)
teamNoNumeric ID or key of the team
due_dateNoDate that work is due to be completed (YYYY-MM-DD format)
created_byNoEmail address of the user who created the feature
initiativeNoName or ID of initiative
release_idYesNumeric ID or key of the release (required)
start_dateNoDate that work will start (YYYY-MM-DD format)
descriptionNoDescription of the feature (may include HTML formatting)
release_phaseNoName or ID of release phase
workflow_kindNoType of feature
workflow_statusNoStatus of the feature
assigned_to_userNoUser assigned to the feature
initial_estimate_textNoInitial estimated effort (e.g., '2d 1h' for time or '4p' for points)
detailed_estimate_textNoDetailed estimated effort (e.g., '2d 1h' for time or '4p' for points)
remaining_estimate_textNoRemaining estimated effort (e.g., '2d 1h' for time or '4p' for points)

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but only states 'Create a new feature in Aha!'. It discloses that this is a write operation, but nothing about required inputs, potential side effects, or return behavior. Since there is no output schema, this is inadequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence. It is minimal but not padded, achieving maximum brevity and clarity. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 17 parameters and no output schema, this one-sentence description provides almost no contextual completeness. It does not explain what a feature is, how it relates to a release, or what the tool returns. The agent is left to infer everything from the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 17 parameters are fully described in the input schema, so the description's lack of parameter detail is acceptable. The schema provides definitions for each field, including required ones, meeting the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Create' and names the resource 'feature' within 'Aha!', clearly distinguishing it from sibling read/search tools. The purpose is unambiguous and immediately understood.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites like needing a release_id. The description is a bare statement with zero usage context, leaving the agent to infer when this tool should be invoked.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pageC

Get an Aha! page by reference number with optional relationships

ParametersJSON Schema
NameRequiredDescriptionDefault
referenceYesReference number (e.g., ABC-N-213)
includeParentNoInclude parent page in the response

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, leaving the description responsible for behavioral disclosure. It implies a read operation via 'Get' but does not confirm safety, permissions, error behavior, or what 'relationships' actually entails. The vague 'optional relationships' adds little transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, short sentence that is front-loaded with the primary purpose. However, 'optional relationships' is imprecise and could be more specific, slightly reducing its effectiveness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description is too thin. It does not explain what an Aha! page is, what relationships are available beyond the includeParent flag, or how the tool behaves in error cases. More context is needed for an agent to invoke it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with both parameters documented. The description adds 'by reference number' and 'optional relationships', but these are already implied or covered by the schema. It provides no additional syntax or format details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets an Aha! page by reference number, identifying both the resource type and the lookup method. However, it does not explicitly differentiate from the sibling get_record, making it less distinct than ideal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives like get_record or search_documents. It does not state any prerequisites, exclusions, or scenarios where this tool is preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_recordA

Get an Aha! feature or requirement by reference number

ParametersJSON Schema
NameRequiredDescriptionDefault
referenceYesReference number (e.g., DEVELOP-123 or ADT-123-1)

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full responsibility for disclosing behavior. It only states that it 'gets' a record, which is already evident from the name. It does not mention error handling (e.g., what happens if the reference is not found), return format, or any side effects, leaving the agent with limited understanding of the tool's runtime behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one concise sentence, front-loaded with the action and resource. It contains no redundant information and earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single, well-described parameter and no output schema, the description is mostly sufficient. It tells the agent what the tool does and how to specify the input. However, it lacks any mention of the return value or possible response structure, which would be helpful for an agent to interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already includes a description for the single parameter 'reference' with examples (e.g., DEVELOP-123 or ADT-123-1), so the description adds little beyond what the schema provides. The tool description's phrase 'by reference number' reinforces the parameter's usage but does not offer new details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets an Aha! feature or requirement by reference number, using a specific verb and resource. It distinguishes itself from siblings like get_page (pages), search_documents (search), and create_feature (create).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used when you have a reference number to fetch a specific record, but it does not explicitly mention alternatives or when not to use it. There is no comparison with sibling tools or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_documentsC

Search for Aha! documents

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query string
searchableTypeNoType of document to search for (e.g., Page)Page

TDQS

C2.4/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the full burden of behavioral disclosure, and it barely restates the tool's function. It offers no insight into result formats, pagination, authentication, rate limits, or any side effects. This is essentially tautological.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (six words), but it is under-specified and essentially restates the tool name. It is not structured or front-loaded with useful information beyond the basic action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and only a minimal description, the tool is not adequately contextualized. The agent has no information about what results to expect, how many matches are returned, or any limitations. This is a significant gap for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides 100% coverage: both 'query' and 'searchableType' have descriptions. The tool description adds no further meaning, but since the schema already documents the parameters, a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Search for Aha! documents' clearly states a specific action (search) and a resource (Aha! documents). It is unambiguous but does not differentiate from sibling tools like get_page or get_record, which could also be used to retrieve documents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There is no mention of what kind of documents are searched, how search results differ from direct retrieval, or any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedcreate_feature
    • First observedget_page
    • First observedget_record
    • First observedsearch_documents
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 4 tools

Disambiguation4/5

Each tool clearly targets a different resource or action: get_record for features/requirements, get_page for pages, search_documents for broader search, and create_feature for creation. There is slight overlap in that search_documents could return records/pages, but the retrieval purposes are distinct.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with lowercase and underscores: get_record, get_page, search_documents, create_feature. This makes the set predictable and easy to navigate.

Tool Count5/5

Four tools is well-suited for a focused server that provides basic read, search, and create operations. There is no unnecessary bloat, and every tool serves a clear purpose.

Completeness3/5

The server covers reading records and pages, searching, and creating features, but lacks update/delete operations and support for creating other record types like requirements or pages. This leaves notable gaps for full lifecycle management.

Resources

Related MCP Connectors

Related MCP Servers