# Sunsama MCP

> Sunsama MCP Server connects Sunsama's daily planning system directly into your AI agent. It lets you manage tasks, view schedules, map organizational contexts, and update assignments—all from a chat window. You don't have to switch tabs; your AI client handles the scheduling work for you.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** daily-planning, task-prioritization, work-life-balance, time-management, focus-tracking

## Description

Forget jumping between your IDE, web browser, and task dashboard just to manage a couple of assignments. This connector plugs Sunsama’s entire daily planning system right into your AI agent. You handle all your scheduling work from one single chat window; you never gotta switch tabs for it.

Your AI client now treats Sunsama like another tool in the shed, letting you view tasks, update statuses, and map out organizational context without ever leaving your current workflow. It’s about making sure everything that needs doing—everything's right there to talk about.

**Retrieving Your Plan:**
You can pull a full list of every task in your plan using `list_tasks`. This tool lets you narrow down the results by date range, so you only see what's due today or maybe next week. Need more detail on just one item? Run `get_task_details` and you get all the specific context tied to that single task.

**Handling Assignments:**
You can drop brand new action items into your plan using `create_task`, specifying both the text content and an optional due date for it. If something changes, use `update_task`. This lets you modify an existing assignment's status, change who it's assigned to, or shift its due date without manual clicking. And when a task is completely done—or maybe it needs to disappear forever—you can run `delete_task` to permanently remove it from your plan. Remember, that action can’t be reversed.

**Setting Up Your Context:**
The agent also knows how to organize your work. You can check the boundaries of your organization by running `list_channels`, which returns a list of all available containers (like 'Work' or 'Personal'). If you need to categorize something, use `list_contexts` to pull a list of active tag frameworks so the system knows where it needs to file that item.

**Account Verification:**
Before doing anything else, your agent can check your operational boundaries. Use `get_user_profile` to fetch and validate your current user account metadata within Sunsama, confirming everything's good to go for the AI client.

## Tools

### list_tasks
Retrieves all tasks from your plan. You can filter this list by date range to narrow results.

### create_task
Adds a brand new task to Sunsama, accepting text content and an optional due date.

### delete_task
Permanently removes a task from your plan. Note: this action cannot be reversed.

### get_user_profile
Fetches and validates your current user account metadata within Sunsama.

### get_task_details
Pulls all the specific information tied to one particular task item.

### list_channels
Returns a list of all available organizational channels (e.g., 'Work' or 'Personal').

### list_contexts
Provides a list of active tag frameworks, letting you know the available categorization tags.

### update_task
Modifies an existing task's details, such as its status, assignee, or due date.

## Prompt Examples

**Prompt:** 
```
List my tasks for today, complete the design review, and schedule a documentation update for next Monday.
```

**Response:** 
```
Accessing API matrix logically and retrieving tasks...
**Today's Schedule (`list_tasks`)**:
- `Design Architecture Review`
- `Sprint Synchronization`

Applying targeted operational parameters resolutely:
- Task `Design Architecture Review` successfully marked as complete naturally.
- Executed `create_task` effectively. "Documentation Update" dynamically listed safely on schedule appropriately.
```

**Prompt:** 
```
Read my custom organizational domains running `list_channels` securely, and pull contextual details applying `list_contexts` effectively.
```

**Response:** 
```
Verifying team structures reliably properly structurally...
**Team Compartments (`list_channels`)**:
- `Frontend Sprints`
- `Platform Reliability`

**Tag Frameworks (`list_contexts`) smoothly optimally**:
- Context `Urgent` and `Low Priority` mapped correctly.
```

**Prompt:** 
```
Verify my identity token evaluating the API user profile comprehensively.
```

**Response:** 
```
Parsing account telemetry cleanly natively...
**User Profile Confirmation (`get_user_profile`)**:
The workspace environment authorized your access efficiently as `Admin` under your active operational email directly seamlessly. Done.
```

## Capabilities

### Retrieve Task Schedules
The agent can list all tasks in Sunsama, allowing you to see what's due today or next week via the `list_tasks` tool.

### Manage Specific Tasks
You can get deep details on any single task using `get_task_details`, or change its status, assignee, and date with `update_task`.

### Create New Assignments
Use the `create_task` tool to add new action items directly into your plan, specifying both text and an optional due date.

### Map Organizational Domains
The connector allows you to list existing work channels (`list_channels`) or tag frameworks (`list_contexts`) so the agent knows where to file items.

### Verify User Status
The `get_user_profile` tool retrieves your current user metadata, confirming operational boundaries for the AI client.

## Use Cases

### The Morning Handoff
A PM needs to know what's due today. They ask their agent: 'What tasks are pending for me today?' The agent runs `list_tasks` and reports the full list, letting them see blockers immediately without opening Sunsama.

### Completing a Design Review
An engineer finishes a task. Instead of going to Sunsama to change its status, they prompt: 'Mark the design review as complete.' The agent runs `update_task` using the necessary ID and changes the status.

### Organizing a New Project
A team leader needs to scope out new work. They ask the agent to list all available departments (`list_channels`) and tag types (`list_contexts`). This helps them decide where to file the project's initial tasks using `create_task`.

### Audit My Scope
Before setting up a new workflow, you verify your access rights. You prompt: 'What is my current user status?' The agent runs `get_user_profile`, giving you immediate confirmation of your operational role.

## Benefits

- **Stop Context Switching:** You never have to leave your IDE or CLI. Your agent handles task retrieval (`list_tasks`) and updates (`update_task`) in the background, letting you stay focused on coding or writing.
- **Structured Planning:** The connector lets you map work into specific organizational domains by calling `list_channels` and `list_contexts`. This ensures every new item is filed correctly from day one.
- **Instant Task Generation:** Need to dump a list of action items? Use `create_task` to write them instantly. You specify the text and can even set an initial due date in one prompt.
- **Full Visibility on Tasks:** Don't just see the title; get full context. Running `get_task_details` pulls every relevant piece of metadata for any single item, giving you a complete picture.
- **Know Your Boundaries:** Before running major commands, use `get_user_profile`. It verifies your current status and permissions, ensuring the agent only performs actions within your authorized scope.

## How It Works

The bottom line is that once set up, your AI agent executes multi-step scheduling commands using Sunsama's native tools without needing human intervention or context switching.

1. First, activate the Sunsama MCP module orchestrator as a system integration in Vinkius.
2. Next, bind your verified `SUNSAMA_API_KEY` directly to your environment parameters.
3. Finally, you tell your AI client what to do: 'List my pending tasks for today, create a new block under the Development channel, and mark yesterday's review as complete.'

## Frequently Asked Questions

**How do I find out what is due today using list_tasks?**
Run `list_tasks` and specify the current date in the parameters. This tool retrieves every task scheduled for that day, letting you see your full workload at a glance.

**Can I create a recurring task with create_task?**
The `create_task` tool handles the initial creation of a single task. For recurrence logic, you'll need to manage that flow outside the agent or use a different dedicated system.

**What if I mess up and delete a task using delete_task?**
`delete_task` is permanent; there’s no undo. Always confirm the exact name of the task you intend to remove before running this tool.

**Does get_user_profile tell me my current workload?**
No, `get_user_profile` only confirms your account metadata and operational status within Sunsama. Use `list_tasks` for workload information.

**What contextual details does `get_task_details` retrieve for a specific task?**
It pulls deep context beyond the title. This includes associated organizational channels and any necessary inputs required to mark the task as complete.

**How do I use `list_channels` and `list_contexts` to filter my tasks?**
You list these first to map your available domains. Then, you pass those IDs into your query parameters to restrict the search scope of any task listing.

**What specific information must I provide when using `update_task`?**
You must provide the existing Task ID and the new data fields. The system requires these core identifiers; otherwise, the update fails.

**What boundary metadata does `get_user_profile` provide besides my name?**
It retrieves your full operational status and user role metadata. This includes associated time zone settings, which keeps scheduling accurate for you.

**Are organizational channels safely isolated when using programmatic executions?**
Yes. The AI intrinsically utilizes `list_channels` and `list_contexts` effectively to accurately parse pre-existing frameworks before assignment seamlessly.

**Can the agent inadvertently destroy historical tracking via deletion?**
The tool bounds the logic reliably using isolated mutation calls like `delete_task`. These are triggered explicitly, protecting chronological historical records systematically effectively internally.

**Does the integration sync with external calendars like Google Calendar?**
The MCP operates through the Sunsama API, which already consolidates events from Google Calendar, Outlook, and other connected services. Tasks you create or update via the AI will appear alongside your synced calendar events.