AIC Requirements MCP Server

A standalone Model Context Protocol (MCP) server for managing requirements on the AIC Requirements platform. Exposes tools for workspaces, initiatives, epics, user stories, and subtasks — with export support for external adapters (Jira, Azure DevOps, etc.).

Installation

npm (global)

npm install -g aic-requirements-mcp

npx (no install)

npx aic-requirements-mcp

From source

git clone <repository-url>
cd packages/mcp-server
npm install
npm run build

Configuration

Required Environment Variables

| Variable | Description | |----------|-------------| | AIC_API_KEY | Your API key for the AIC Requirements platform | | AIC_REQUIREMENTS_URL | Base URL of the Requirements BFF (e.g., https://aic-requirements.hml.ms.aicockpit.ai or http://localhost:3003) |

Optional Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | MCP_TRANSPORT | stdio | Transport mode: "stdio" or "sse" | | MCP_PORT | 3100 | Port for SSE transport (valid range: 1024–65535) |

CLI Arguments

CLI arguments override environment variables:

npx aic-requirements-mcp --transport=sse --port=4000

If a required variable is missing, the server logs the specific missing variable to stderr and exits with a non-zero status code.

Client Configuration Examples

Kiro

Add to your .kiro/settings.json:

{
  "mcpServers": {
    "aic-requirements": {
      "command": "npx",
      "args": ["aic-requirements-mcp"],
      "env": {
        "AIC_API_KEY": "your-api-key",
        "AIC_REQUIREMENTS_URL": "https://aic-requirements.hml.ms.aicockpit.ai"
      }
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "aic-requirements": {
      "command": "npx",
      "args": ["aic-requirements-mcp"],
      "env": {
        "AIC_API_KEY": "your-api-key",
        "AIC_REQUIREMENTS_URL": "https://aic-requirements.hml.ms.aicockpit.ai"
      }
    }
  }
}

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "aic-requirements": {
      "command": "npx",
      "args": ["aic-requirements-mcp"],
      "env": {
        "AIC_API_KEY": "your-api-key",
        "AIC_REQUIREMENTS_URL": "https://aic-requirements.hml.ms.aicockpit.ai"
      }
    }
  }
}

Available Tools

| Tool | Description | |------|-------------| | list_workspaces | List all workspaces for the authenticated organization | | get_workspace | Get a single workspace by its id | | create_workspace | Create a new workspace with name and optional description | | update_workspace | Update an existing workspace (name, description) | | delete_workspace | Delete a workspace by id | | list_initiatives | List initiatives for a given project key | | create_initiative_in_adapter | Create an initiative in the configured adapter | | list_epics | List epics for a project key with pagination | | create_epic_in_adapter | Create an epic in the configured adapter | | list_stories | List stories filtered by project key and optional epic key | | create_story_in_adapter | Create a story in the configured adapter | | create_subtasks_in_adapter | Create subtasks under a parent story (1–50) | | list_adapters | List configured adapters (Jira, Azure DevOps, etc.) | | list_adapter_projects | List available projects for the configured adapter |

Error Format

All errors returned by the server follow this structure:

{
  "content": [{ "type": "text", "text": "{\"code\":\"not_found\",\"message\":\"Workspace not found\"}" }],
  "isError": true
}

Error Codes

| Code | Meaning | |------|---------| | unauthorized | API key is invalid or expired | | forbidden | API key lacks permission for this operation | | not_found | Requested resource does not exist | | validation | Input parameters failed validation | | unavailable | Requirements BFF is unreachable (timeout or connection refused) | | bad_gateway | Requirements BFF returned invalid JSON | | server_error | Unexpected server-side error |

Development

# Build
npm run build

# Run tests
npm test

# Watch mode (rebuild on changes)
npm run dev

License

Private — internal use only.