# Archion MCP Server

Connect AI agents like **Claude Desktop**, **Cursor**, **Windsurf**, and **VS Code Copilot** to [Archion](https://archionapp.com) — the AI-powered goal breakdown and task tracking app.

Use MCP (Model Context Protocol) to let your AI assistant read your goals, check pending tasks, mark tasks as done, report blockers, and more — all from your editor or chat.

## Prerequisites

- An [Archion](https://archionapp.com) account with a **Pro** or **Team** plan
- An API key (generate one in **Dashboard → Settings → API Keys**)

## Setup

### Claude Desktop

Add to `~/.claude/claude_desktop_config.json`:

```json
{
	"mcpServers": {
		"archion": {
			"url": "https://archionapp.com/api/mcp",
			"headers": {
				"Authorization": "Bearer YOUR_API_KEY"
			}
		}
	}
}
```

### Cursor

1. Open **Settings → MCP Servers**
2. Click **Add Server**
3. Set:
   - **Name**: `archion`
   - **Type**: `HTTP`
   - **URL**: `https://archionapp.com/api/mcp`
   - **Headers**: `Authorization: Bearer YOUR_API_KEY`

### VS Code (GitHub Copilot)

Add to `.vscode/mcp.json` in your project:

```json
{
	"servers": {
		"archion": {
			"type": "http",
			"url": "https://archionapp.com/api/mcp",
			"headers": {
				"Authorization": "Bearer YOUR_API_KEY"
			}
		}
	}
}
```

### Windsurf

Add to `~/.windsurf/mcp_config.json`:

```json
{
	"mcpServers": {
		"archion": {
			"serverUrl": "https://archionapp.com/api/mcp",
			"headers": {
				"Authorization": "Bearer YOUR_API_KEY"
			}
		}
	}
}
```

## Available Tools

| Tool                   | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `list_goals`           | List all goals with progress summary                |
| `list_team_goals`      | List all team goals from organizations              |
| `get_goal_detail`      | Get a goal with all phases and tasks                |
| `create_goal`          | Create a goal with phases, tasks, and optional approach |
| `get_pending_tasks`    | Get incomplete tasks, optionally filtered by goal   |
| `add_task`             | Add a new task to a phase                           |
| `assign_task`          | Assign a task to a team member                      |
| `complete_task`        | Mark a task as done with optional result summary    |
| `update_task_result`   | Update the result/output of a completed task        |
| `uncomplete_task`      | Mark a task as not done                             |
| `report_blocker`       | Report a blocker on a task                          |
| `clear_blocker`        | Clear a blocker from a task                         |
| `get_task_context`     | Get a full mission briefing context for a goal      |
| `export_goal_markdown` | Export a goal as a markdown document                |
| `get_analytics`        | Get productivity analytics (velocity, rates, etc.)  |
| `get_blockers_summary` | Get a summary of all active blockers across goals   |
| `search_tasks`         | Search tasks by keyword across all goals            |
| `get_activity_log`     | Get recent agent activity log                       |

## Example Prompts

Once connected, try these in your AI assistant:

- _"What are my current goals?"_
- _"Show me my pending tasks"_
- _"Mark task X as done"_
- _"What tasks have blockers?"_
- _"Export my goal as markdown"_
- _"Add a task 'Write unit tests' to the Development phase"_
- _"Create a goal to launch a SaaS with approach: use Next.js + Supabase"_
- _"Show me my productivity analytics"_
- _"Search for tasks related to 'auth'"_

## Strategic Approach

Goals can include an optional **approach** — a strategic guideline that shapes how tasks are generated and how AI agents work on the goal.

When you create a goal with an approach (e.g., _"Use Next.js + Supabase, focus on SEO first"_), this context is:

1. **Passed to the AI planner** — generated phases and tasks will follow the chosen strategy
2. **Included in `get_task_context`** — agents reading the mission briefing will see the approach and work within its boundaries
3. **Stored permanently** — the approach acts as persistent agent instructions (like a lightweight "Fat Skill")

You can set an approach via:
- The dashboard UI (Step 2 of goal creation, with AI-suggested options)
- The `create_goal` MCP tool (`approach` parameter)

## REST API

Archion also offers a REST API for custom integrations.

### Endpoints

```
GET  /api/v1/goals              # List all goals with progress
GET  /api/v1/goals/:id          # Get goal detail
GET  /api/v1/goals/:id/export   # Export goal as markdown
GET  /api/v1/tasks              # List tasks (filters: ?done=false&blocked=true&goal_id=)
GET  /api/v1/tasks/:id          # Get task detail
PATCH /api/v1/tasks/:id         # Update task (done, title, blocker_note)
```

### Authentication

All requests require an API key:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://archionapp.com/api/v1/goals
```

Or use the `x-api-key` header:

```bash
curl -H "x-api-key: YOUR_API_KEY" \
  https://archionapp.com/api/v1/goals
```

### Examples

```bash
# List pending tasks
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://archionapp.com/api/v1/tasks?done=false"

# Complete a task
curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"done": true}' \
  https://archionapp.com/api/v1/tasks/TASK_ID

# Report a blocker
curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"blocker_note": "Waiting for design review"}' \
  https://archionapp.com/api/v1/tasks/TASK_ID

# Export goal as markdown file
curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/markdown" \
  https://archionapp.com/api/v1/goals/GOAL_ID/export -o goal.md
```

## API Key Limits

| Plan | API Keys |
| ---- | -------- |
| Free | —        |
| Pro  | 2        |
| Team | 10       |

## Links

- [Archion App](https://archionapp.com)
- [Get Started](https://archionapp.com/signup)

## License

MIT