allstacks-mcp 0.1.6

MCP server for Allstacks API - provides AI-ready interface to Allstacks metrics, projects, and analytics

Allstacks MCP Server

A comprehensive Model Context Protocol (MCP) server providing AI-ready access to the Allstacks API. Authenticate with either HTTP Basic (username + password) or a Bearer Personal Access Token.

Overview

This MCP server exposes 170 tools organized into 13 categories for comprehensive interaction with Allstacks:

Tool Categories

1. Metrics & Analytics (8 tools): Metrics V2 data, Metrics V2 capitalization preview, templates, labels, tags, and item properties
2. Service Items & Work Items (12 tools): Complete CRUD for work items, parent service items, property keys, estimation methods, and notes
3. Users & Teams (20 tools): Full user management, invites, roles, team tags, personal access tokens, service users
4. Organization & Projects (28 tools): Organizations, projects, settings, services, calendars, time periods, slots, capitalization reports (V2)
5. Dashboards & Widgets (18 tools): Complete dashboard/widget CRUD, shared links, cloning, widget management
6. Employee Analytics (8 tools): Employee metrics, cohorts, work items, timeline, summary, periods
7. Forecasting & Planning (9 tools): V3 forecasts, velocity, scenarios, capacity planning, chart analysis
8. Labels & Tagging (15 tools): Labels, label families, bulk operations, service item label assignment
9. Alerts & Monitoring (13 tools): Alert rules, active alerts, notifications, subscriptions, preferences
10. AI & Intelligence (13 tools): AI reports, Action AI code query, AI metric builder (project), pattern analysis, surveys, DX scores, AI tool usage
11. Work Bundles (12 tools): Selectable work bundle management, forecasting, metrics, cloning
12. Risk Management (12 tools): Risk definitions, project risks, assessment, trends, resolution
13. API Discovery (2 tools, 2 resources): Runtime OpenAPI schema access and lightweight domain-to-tool category mapping

Project Structure

allstacks-mcp-server/
├── allstacks_mcp/
│   ├── __init__.py
│   ├── __main__.py             # python -m allstacks_mcp entry point
│   ├── server.py               # Main entry — 170 tools, resources, arg parsing
│   ├── client.py               # HTTP client (Basic + Bearer auth)
│   └── tools/                  # Tool modules by category
│       ├── __init__.py
│       ├── metrics.py          # 8 metrics tools
│       ├── service_items.py    # 12 service item tools
│       ├── users_teams.py      # 20 user/team tools
│       ├── org_projects.py     # 28 org/project tools
│       ├── dashboards.py       # 18 dashboard tools
│       ├── employee.py         # 8 employee analytics tools
│       ├── forecasting.py      # 9 forecasting tools
│       ├── labels.py           # 15 label management tools
│       ├── alerts.py           # 13 alert/monitoring tools
│       ├── ai_analytics.py     # 13 AI & analytics tools
│       ├── work_bundles.py     # 12 work bundle tools
│       ├── risk_management.py  # 12 risk management tools
│       └── discovery.py        # 2 API discovery tools and 2 resources
├── pyproject.toml
├── uv.lock
└── README.md

Quick Start

Prerequisites

• Python 3.10 or higher
• uv package manager (curl -LsSf https://astral.sh/uv/install.sh | sh)
• Allstacks account with either:
  • Personal Access Token (PAT) from the Allstacks UI — recommended for all users, required for SSO
  • Username + password (only for local accounts, not SSO)

Installation

The simplest way to use the Allstacks MCP server is via uvx, which installs and runs the server in one command:

uvx allstacks-mcp --token YOUR_PAT --base-url https://app.allstacks.com/api/v1/

That's it! The server will start and be ready to accept MCP connections.

See Authentication Modes for the full set of supported auth options (PAT vs. HTTP Basic) and when to use each. For local development or contributing to this project, see the Local Development section below.

Authentication & Security

Authentication Modes

The server supports two authentication modes. Pick one — they are mutually exclusive.

Option A — Bearer auth with a Personal Access Token (recommended; required for SSO users)

Generate a PAT in the Allstacks UI under Personal Access Tokens and pass it with --token:

uvx allstacks-mcp --token YOUR_PAT --base-url https://app.allstacks.com/api/v1/

• ✅ Works for all users, including SSO-only accounts
• ✅ Tokens can be revoked from the UI without changing account credentials
• ✅ More secure than password-based auth
• Token is sent as Authorization: Bearer <token>

Option B — HTTP Basic auth with username + password

Only works for local accounts that have a password set. SSO-only users will get a 401 error.

uvx allstacks-mcp --username [e-mail] --password your-password --base-url https://app.allstacks.com/api/v1/

• ⚠️ Only for local accounts (not SSO users)
• Credentials are sent using HTTP Basic authentication

Base URL: The default is https://app.allstacks.com/api/v1/. Override with --base-url if your deployment uses a different endpoint.

🔒 Security Best Practices

Credential Management

⚠️ IMPORTANT: Your credentials provide full access to your Allstacks account.

1. Prefer Personal Access Tokens over passwords — revocable, scoped, and the only option for SSO users.

2. Keep credentials out of shell history and config files when possible. The server only reads credentials from CLI flags, so if you want to store them in environment variables, expand them into the flags at launch time:

   export ALLSTACKS_TOKEN="your-pat"
   uvx allstacks-mcp --token "$ALLSTACKS_TOKEN"
   
   # or, for Basic auth:
   export ALLSTACKS_USERNAME="your-username"
   export ALLSTACKS_PASSWORD="your-password"
   uvx allstacks-mcp --username "$ALLSTACKS_USERNAME" --password "$ALLSTACKS_PASSWORD"
   

3. Never commit credentials to version control

   • The MCP client config file may contain credentials
   • Keep config files in .gitignore

4. Rotate credentials regularly for enhanced security

Process Security

Note: Command-line arguments (--username, --password, --token) are visible in process lists, including when expanded from environment variables at launch. For production use:

• Restrict access to the host running the server so other users cannot read its process list
• Store credentials in a secure secrets manager and inject them only at launch time
• Use a dedicated Allstacks account or short-lived PAT that can be revoked quickly

Data Access & Privacy

This MCP server acts as a pass-through to the Allstacks API:

• ✅ Does not store or log your credentials
• ✅ Does not cache API responses
• ✅ Does not persist any data locally
• ✅ Returns API data as-is without modification

AI Access: When used with AI assistants (e.g., Claude), the AI will have access to:

• All data accessible via your Allstacks credentials
• The same permissions as your Allstacks user account
• Ability to create, modify, and delete resources (depending on your permissions)

Recommendation: Consider using a dedicated Allstacks account with limited permissions for AI access.

Usage

Token-Efficient Responses

High-volume list and time-series tools accept an optional response_format argument:

• response_format="json" returns the existing pretty-printed JSON output and remains the default for compatibility.
• response_format="toon" returns a compact TOON-style text encoding. Arrays of repeated objects are represented as tables, which removes repeated field names from each row.

Example:

get_org_metrics_v2_data(org_id, config, response_format="toon")
list_service_items(item_type="CARD", limit=100, response_format="toon")
get_capacity_planning(org_id, start_date="2026-06-01", end_date="2026-06-30", response_format="toon")

Measured with synthetic payloads shaped like common API responses, using character count as a tokenizer-independent proxy:

Payload shape	Pretty JSON chars	TOON chars	Reduction
Metric time-series, 90 rows x 4 scalar fields	11,413	2,449	79%
Paginated service-item list, 100 rows x 5 scalar fields	12,357	2,367	81%
Allocation/capacity rows, 60 rows x 6 scalar fields	11,421	2,133	81%

Running the Server Standalone

Bearer / PAT (recommended; required for SSO users):

uvx allstacks-mcp --token YOUR_PAT

Basic / username + password (local accounts only):

uvx allstacks-mcp --username YOUR_USERNAME --password YOUR_PASSWORD

Command-line options:

• --token or -t: Personal Access Token for Bearer auth (alternative to username/password)
• --username or -u: Username for HTTP Basic auth (paired with --password)
• --password or -p: Password for HTTP Basic auth (paired with --username)
• --base-url or -b: Override the default API base URL (default: https://app.allstacks.com/api/v1/)
• --openapi-schema-url: Override the published OpenAPI schema URL (default: <base-url>/schema/)

Pass either --token OR both --username and --password — not both modes at once.

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop's claude_desktop_config.json or Claude Code's mcp.json).

Recommended — PAT / Bearer auth (works for all users, including SSO):

{
    "mcpServers": {
        "allstacks": {
            "command": "uvx",
            "args": [
                "allstacks-mcp",
                "--token",
                "YOUR_PERSONAL_ACCESS_TOKEN",
                "--base-url",
                "https://app.allstacks.com/api/v1/"
            ]
        }
    }
}

Alternative — Username + password (local accounts only):

{
    "mcpServers": {
        "allstacks": {
            "command": "uvx",
            "args": [
                "allstacks-mcp",
                "--username",
                "[e-mail]",
                "--password",
                "your-password",
                "--base-url",
                "https://app.allstacks.com/api/v1/"
            ]
        }
    }
}

Important Notes:

• Replace YOUR_PERSONAL_ACCESS_TOKEN with your actual PAT from the Allstacks UI
• Or replace [e-mail] and your-password with your credentials (local accounts only)
• The --base-url is optional (defaults to https://app.allstacks.com/api/v1/)
• The OpenAPI resource uses <base-url>/schema/ unless --openapi-schema-url is provided
• uvx automatically installs and runs the latest version from PyPI — no manual installation needed!

Using a local clone for development? See the Local Development section for the configuration pattern.

Features

Comprehensive API Coverage

All tools are verified against the official Allstacks OpenAPI specification:

• ✅ All endpoints use correct paths and parameters
• ✅ Detailed parameter descriptions from official API docs
• ✅ Proper error handling and validation
• ✅ Authentication via Bearer token (PAT) or HTTP Basic
• ✅ Async/await for performance

API Discovery Resources

Agents can discover API shape without loading the full tool catalog:

• get_openapi_schema: Fetches the published OpenAPI schema at runtime using the configured credentials
• allstacks://openapi and schema://api: MCP resources exposing the same runtime schema as JSON
• list_tool_categories: Returns a compact domain-to-tool-name map for metrics, allocations, delivery, AI impact, and related domains

Modular Architecture

Tools are organized into logical categories matching the Allstacks API structure:

• Easy to navigate and understand
• Clear separation of concerns
• Consistent patterns across all tools
• Well-documented with OpenAPI references

Rich Tool Descriptions

Every tool includes:

• Purpose and use case
• Required and optional parameters
• Expected return formats
• OpenAPI endpoint reference
• Example usage patterns

Example Tool Usage

Get Metrics V2 Data

# Query Metrics V2 using an inner config object. Use ai_metric_builder first
# when you want to turn a natural-language question into this config shape.
get_project_metrics_v2_data(
    project_id=123,
    config={
        "item_type": "CARD",
        "dimensions": [{"field": "state"}],
        "measures": [{"aggregation": "count"}],
    },
    response_format="toon",
)

List Work Items with Filtering

# List service items with filtering
list_service_items(
    item_type="CARD",
    limit=100,
    offset=0
)

Create AI Report

# Generate AI analysis report
create_ai_report(
    org_id=456,
    report_type="project_health",
    project_id=123
)

Forecast Work Bundle

# Get Monte Carlo forecast for work bundle
get_work_bundle_forecast(
    project_id=123,
    bundle_id=789,
    confidence_level=80
)

API Compatibility

This server is built against the official Allstacks API v1 specification and includes:

• Non-admin endpoints only (no destructive operations)
• Full CRUD for resources where appropriate
• Bulk operations for efficiency
• Proper pagination support
• Query parameter validation

Local Development

If you want to contribute to this project or run from a local clone instead of PyPI:

Setup

1. Clone the repository:

   git clone https://github.com/allstacks/allstacks-mcp-server.git
   cd allstacks-mcp-server
   

2. Install dependencies:

   uv sync
   

Running from Local Clone

Bearer / PAT (recommended):

uv run python -m allstacks_mcp.server --token YOUR_PAT --base-url https://app.allstacks.com/api/v1/

Username + password (local accounts only):

uv run python -m allstacks_mcp.server --username YOUR_USERNAME --password YOUR_PASSWORD --base-url https://app.allstacks.com/api/v1/

MCP Client Configuration (Local Clone)

For Claude Desktop or Claude Code, use this configuration pattern when working with a local clone:

{
    "mcpServers": {
        "allstacks": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/allstacks-mcp-server",
                "run",
                "python",
                "-m",
                "allstacks_mcp.server",
                "--token",
                "YOUR_PAT",
                "--base-url",
                "https://app.allstacks.com/api/v1/"
            ]
        }
    }
}

Replace /ABSOLUTE/PATH/TO/allstacks-mcp-server with the full path to your cloned repository.

Development

Adding New Tools

1. Create or update a tool file in allstacks_mcp/tools/
2. Follow the existing pattern for tool registration
3. Include full docstrings with OpenAPI references
4. Add the module to allstacks_mcp/tools/__init__.py
5. Register it in allstacks_mcp/server.py's register_all_tools() function

Testing

When working on the codebase, run the server in development mode:

# From local clone with Bearer token
uv run python -m allstacks_mcp.server --token YOUR_PAT --base-url https://app.allstacks.com/api/v1/

# Or with a dev/staging environment
uv run python -m allstacks_mcp.server --token YOUR_PAT --base-url https://api-dev.allstacks.com/api/v1/

License

MIT

Support

For issues or questions about the Allstacks API, contact the Allstacks team. For issues specific to this MCP server, please file an issue in the repository.