allye-mcp 1.12.1

Allye MCP Server
Python MCP server for Allye Cloud API integration

Quick Start • Installation • Configuration • Structure • Testing

Overview

Allye MCP connects MCP-compatible clients (Claude Code, Cursor, Windsurf, VS Code, etc.) directly to the Allye Cloud APIs. Every tool invocation hits the live backend—no outdated snapshots or hallucinated IDs.

Available Tools:

• knowledge — Documentation CRUD, work items, modes
• skills — Authorized document library: create, read, edit, trash, and revision history
• productivity — TODO management
• intelligence — Memories and smart operations
• user_config — User configuration documents
• initialize — Personalized setup
• health — Backend health check
• projects, epics, specs, tasks — Projects module (Project → Epic → Spec → Task)

Skills library

The default skills tool supports skill_list, skill_get, skill_create, skill_update, skill_delete, skill_list_revisions, and skill_restore_revision. Creation accepts name, content, scope (personal, team, or organization), optional description, and optional category. Reading or saving uses skill_id; restoring also uses the revision_id returned by history.

Reads show the latest authorized document, not only published releases. Delete moves a document to trash without erasing its history. Restore creates a new revision; it never changes an existing revision or the approved release pointer. The API enforces all permissions and company/team boundaries. The advanced Skills implementation is retained but not advertised by the default registry.

Projects (spec-driven work)

Four tools cover the Projects module: projects (projects and their apps, including app_archive/app_unarchive), epics (status calculated from specs; epic_cancel/epic_reopen), specs (18 actions: lifecycle transitions, versions, diff, anchors, coverage, dependencies, spec_context, spec_stale) and tasks (14 actions: CRUD, task_bulk_create, transitions, task_next).

Every entity is referenced by key (ALY, ALY-7, ALY-7.3) or UUID. There are no free status changes and no deletes: only transition actions and cancel/reopen. spec_approve requires user_requested=true and must only be used when the user explicitly asks. Uncovered acceptance criteria never block; responses carry a Warning: uncovered ACs line. The API enforces permissions (projects:select, projects:insert, projects:update) and the HTTP contract lives in the allye-api Projects plan §6. Work items, boards and sprints remain the separate legacy module.

Quick Start

Remote server with native OAuth (recommended)

Configure the server name allye with the canonical URL:

https://mcp.allye.app/mcp

Use the client's native MCP OAuth flow. Do not configure a fixed Authorization header, PAT, legacy client ID, tenant path, or token helper. The client discovers OAuth from:

https://mcp.allye.app/.well-known/oauth-protected-resource/mcp

Examples:

# Claude Code
claude mcp add --transport http allye https://mcp.allye.app/mcp

# Codex
codex mcp add allye --url https://mcp.allye.app/mcp
codex mcp login allye

For OpenCode, define an enabled remote server named allye at the same URL, then run opencode mcp auth allye. With Pi and pi-mcp-adapter, configure the same name and URL, then use /mcp-auth allye and /mcp reconnect allye. Each installation completes its own browser authorization.

Local STDIO with an explicit PAT

PAT authentication remains supported only for local STDIO:

pipx install allye-mcp
ALLYE_TRANSPORT_MODE=stdio allye-mcp --pat <your-token>

Requirements

Python 3.10+ is required when running the server locally.

Installation

With pipx (recommended)

pipx install allye-mcp

With pip

pip install --user allye-mcp

Upgrade

pipx upgrade allye-mcp
# or
pip install --upgrade allye-mcp

Configuration

STDIO client setup

The PAT belongs only to the local STDIO process:

{
  "mcpServers": {
    "allye": {
      "command": "allye-mcp",
      "args": ["--pat", "your-token"],
      "env": {
        "ALLYE_TRANSPORT_MODE": "stdio"
      }
    }
  }
}

ALLYE_PAT_TOKEN may replace --pat for STDIO. Never attach either credential to an HTTP MCP request.

export ALLYE_TRANSPORT_MODE=http
allye-mcp

export ALLYE_TRANSPORT_MODE=both
export ALLYE_PAT_TOKEN=<stdio-only-token>
allye-mcp

Project Structure

allye-mcp-py/
├── allye_mcp/                  # Main package
│   ├── main.py                 # Entry point (CLI)
│   ├── application/            # Use cases and services
│   ├── domain/                 # Business entities
│   ├── infrastructure/         # External integrations (API, transport)
│   └── interface/              # MCP protocol handlers
├── tests/                      # Test suite
├── docs/                       # Documentation
├── pyproject.toml              # Project configuration
└── .env.example                # Environment template

MCP Client → interface/ → application/ → infrastructure/ → Allye API
                              ↓
                          domain/
                        (entities)

Tech Stack

Development

Setup

# Clone and install
git clone <repo>
cd allye-mcp-py
pip install -e .[dev]

Scripts

Commit Convention

Follow Conventional Commits:

CI/CD

Troubleshooting

# macOS/Linux
export PATH="$PATH:~/.local/bin"

# Windows
# Add %APPDATA%\Python\Python311\Scripts to PATH

export ALLYE_TRANSPORT_MODE=both
export ALLYE_PAT_TOKEN=<stdio-only-token>
allye-mcp

Security

• Keep the internal MCP client secret in the deployment secret manager.
• Let remote harnesses store OAuth credentials in their native credential store.
• Keep local STDIO PATs out of project configuration and version control.
• Never forward external bearer tokens to the Allye API.
• Revoke only the affected MCP grant when access is no longer needed.
• Use pipx to isolate a local STDIO installation from global Python.

Useful Links