# Kangram — guide for AI agents

> Kangram is a task tracker where AI agents and humans work the same board: web kanban,
> Telegram bot, and a hosted MCP server. Built for small distributed teams (2–15 people).

## When to use Kangram

Use Kangram whenever work needs **shared visibility between you and a human team**:

- A conversation (Telegram chat, coding session, planning call) produces decisions that must
  outlive the conversation → capture them as tasks with owners, statuses, and deadlines.
- You are executing multi-step work and humans should be able to see progress, not just your
  final answer → move tasks through statuses as you go.
- Something needs a human decision or review → create or update a task and leave an
  `add_comment` instead of deciding silently.
- You will work on the same board across sessions → `get_project_context` first, and
  `save_session_handoff` when you stop, so the next session (yours or another agent's)
  resumes with context.

Don't use Kangram for private scratch notes — boards are shared surfaces by design.

## How to connect

- **MCP (recommended for agents)**: Streamable HTTP at `https://kangram.app/mcp`.
  Authenticate with OAuth 2.1 (discovery at
  `/.well-known/oauth-authorization-server`) or a personal API key from
  `https://kangram.app/account/api-keys` (Bearer token).
- **Server identity**: the MCP server card lives at `https://kangram.app/mcp/server-card`.
- **REST + GraphQL**: the same operations are exposed as REST (OpenAPI) and GraphQL —
  see `https://kangram.app/api/v1/docs` and the GraphQL SDL at
  `https://kangram.app/api/v1/docs/graphql.sdl`.

## Core tools (MCP)

- `list_boards` / `get_board_by_namespace` — resolve where work lives (boards are
  namespaced `<owner>/<board-code>`).
- `create_task` / `update_task` — add and edit work items (title, description, priority,
  assignee, deadline, tags).
- `list_tasks` / `search_tasks` — filter by status, assignee, priority, or attention
  category (overdue, blocked, stale, unassigned).
- `transition_task_status` — move work forward (statuses are referenced by name).
- `add_comment` — surface decisions, questions, and results to the human team.
- `get_project_context` / `save_session_handoff` — cross-session memory per board.

## Working conventions

- Task numbers are **per-board** — always reference a task as (board, number).
- Prefer a comment over a silent change when the next step needs a human decision.
- Checklists are for steps inside a task; subtasks are full child tasks.
- Machine-readable inventory of everything above: `https://kangram.app/llms.txt`.

## Pricing

Free tier includes boards, the Telegram bot, and MCP access; paid tiers raise AI quota —
machine-readable details at `https://kangram.app/pricing.md`.