Sunsama MCP
Access Sunsama via MCP (Model Context Protocol) with managed authentication.
Quick Start
CODEBLOCK0
Base URL
CODEBLOCK1
Replace {tool-name} with the MCP tool name (e.g., search_tasks). The gateway proxies requests to Sunsama's MCP server and automatically injects your credentials.
Authentication
All requests require the Maton API key:
CODEBLOCK2
Environment Variable: Set your API key as MATON_API_KEY:
CODEBLOCK3
Getting Your API Key
- 1. Sign in or create an account at maton.ai
- Go to maton.ai/settings
- Copy your API key
Connection Management
Manage your Sunsama MCP connections at https://ctrl.maton.ai.
List Connections
CODEBLOCK4
Create Connection
CODEBLOCK5
Get Connection
CODEBLOCK6
Response:
CODEBLOCK7
Open the returned url in a browser to complete OAuth authorization.
Delete Connection
CODEBLOCK8
MCP Reference
All MCP tools use POST method:
Task Management
| Tool | Description | Schema |
|---|
| INLINECODE6 | Search tasks by term | schema |
| INLINECODE7 |
Create a new task |
schema |
|
edit_task_title | Update task title |
schema |
|
delete_task | Delete a task |
schema |
|
mark_task_as_completed | Mark task complete |
schema |
|
mark_task_as_incomplete | Mark task incomplete |
schema |
|
append_task_notes | Add notes to task |
schema |
|
edit_task_time_estimate | Set time estimate |
schema |
|
edit_task_recurrence_rule | Set recurrence |
schema |
|
get_task_time_estimate | Get AI time estimate |
schema |
|
restore_task | Restore deleted task |
schema |
Subtasks
| Tool | Description | Schema |
|---|
| INLINECODE17 | Add subtasks | schema |
| INLINECODE18 |
Update subtask title |
schema |
|
mark_subtask_as_completed | Mark subtask complete |
schema |
|
mark_subtask_as_incomplete | Mark subtask incomplete |
schema |
Backlog
| Tool | Description | Schema |
|---|
| INLINECODE21 | List backlog tasks | schema |
| INLINECODE22 |
Move task to backlog |
schema |
|
move_task_from_backlog | Move from backlog to day |
schema |
|
reposition_task_in_backlog | Reorder backlog task |
schema |
|
change_backlog_folder | Change task folder |
schema |
|
create_braindump_task | Create backlog task |
schema |
Scheduling
| Tool | Description | Schema |
|---|
| INLINECODE27 | Reschedule task | schema |
| INLINECODE28 |
Reorder day's tasks |
schema |
|
timebox_a_task_to_calendar | Block time for task |
schema |
|
set_shutdown_time | Set daily end time |
schema |
Calendar Events
| Tool | Description | Schema |
|---|
| INLINECODE31 | Create calendar event | schema |
| INLINECODE32 |
Delete calendar event |
schema |
|
move_calendar_event | Reschedule event |
schema |
|
import_task_from_calendar_event | Import event as task |
schema |
|
set_calendar_event_allow_task_projections | Toggle task overlap |
schema |
|
accept_meeting_invite | Accept meeting |
schema |
|
decline_meeting_invite | Decline meeting |
schema |
Time Tracking
| Tool | Description | Schema |
|---|
| INLINECODE38 | Start timer | schema |
| INLINECODE39 |
Stop timer |
schema |
Channels & Objectives
| Tool | Description | Schema |
|---|
| INLINECODE40 | Create channel/context | schema |
| INLINECODE41 |
Assign task to channel |
schema |
|
create_weekly_objective | Create weekly goal |
schema |
|
align_task_with_objective | Link task to objective |
schema |
Archive
| Tool | Description | Schema |
|---|
| INLINECODE44 | List archived tasks | schema |
| INLINECODE45 |
Restore archived task |
schema |
Email Integration
| Tool | Description | Schema |
|---|
| INLINECODE46 | List email threads | schema |
| INLINECODE47 |
Create task from email |
schema |
|
delete_email_thread | Delete email thread |
schema |
|
mark_email_thread_as_read | Mark email as read |
schema |
Recurring Tasks
| Tool | Description | Schema |
|---|
| INLINECODE50 | Delete future recurrences | schema |
| INLINECODE51 |
Update future recurrences |
schema |
Settings & Preferences
| Tool | Description | Schema |
|---|
| INLINECODE52 | Toggle event auto-import | schema |
| INLINECODE53 |
Update calendar settings |
schema |
|
update_import_event_filters | Set event filters |
schema |
|
log_user_feedback | Submit feedback |
schema |
Common Endpoints
Search Tasks
Search for tasks by keyword:
CODEBLOCK9
Response:
CODEBLOCK10
Create Task
Create a new task scheduled for a specific day:
CODEBLOCK11
Response:
CODEBLOCK12
Get Backlog Tasks
List all tasks in the backlog:
CODEBLOCK13
Response:
CODEBLOCK14
Mark Task as Completed
CODEBLOCK15
Add Subtasks to Task
CODEBLOCK16
Create Calendar Event
CODEBLOCK17
Move Task to Day
Reschedule a task to a different day:
CODEBLOCK18
Timebox Task to Calendar
Block time for a task on your calendar:
CODEBLOCK19
Create Weekly Objective
CODEBLOCK20
Create Braindump Task (Backlog)
Add a task to backlog with time bucket:
CODEBLOCK21
Time bucket options:
- - INLINECODE56
- INLINECODE57
- INLINECODE58
- INLINECODE59
- INLINECODE60
- INLINECODE61
Start/Stop Task Timer
CODEBLOCK22
CODEBLOCK23
Set Shutdown Time
Set when your workday ends:
CODEBLOCK24
Code Examples
JavaScript
CODEBLOCK25
Python
CODEBLOCK26
Error Handling
| Status | Meaning |
|---|
| 400 | Missing MCP connection or invalid tool name |
| 401 |
Invalid or missing Maton API key |
| 429 | Rate limited |
Troubleshooting: API Key Issues
- 1. Check that the
MATON_API_KEY environment variable is set:
CODEBLOCK27
- 2. Verify the API key is valid by listing connections:
CODEBLOCK28
Notes
- - All task IDs are MongoDB ObjectIds (24-character hex strings)
- Date format:
YYYY-MM-DD for days, ISO 8601 for datetimes - MCP tool responses wrap content in
{"content": [{"type": "text", "text": "..."}], "isError": false} format - The
text field contains JSON-stringified data that should be parsed - Time estimates are returned as human-readable strings (e.g., "20 minutes")
Resources
Sunsama MCP
通过MCP（模型上下文协议）访问Sunsama，并支持托管认证。
快速开始
bash
python <
import urllib.request, os, json
data = json.dumps({searchTerm: meeting}).encode()
req = urllib.request.Request(https://gateway.maton.ai/sunsama/search_tasks, data=data, method=POST)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Content-Type, application/json)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
基础URL
https://gateway.maton.ai/sunsama/{tool-name}
将{tool-name}替换为MCP工具名称（例如search_tasks）。网关会将请求代理到Sunsama的MCP服务器，并自动注入您的凭据。
认证
所有请求都需要Maton API密钥：
Authorization: Bearer $MATONAPIKEY
环境变量： 将您的API密钥设置为MATONAPIKEY：
bash
export MATONAPIKEY=YOURAPIKEY
获取您的API密钥
- 1. 在maton.ai登录或创建账户
- 前往maton.ai/settings
- 复制您的API密钥
连接管理
在https://ctrl.maton.ai管理您的Sunsama MCP连接。
列出连接
bash
python <
import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections?app=sunsama&method=MCP&status=ACTIVE)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
创建连接
bash
python <
import urllib.request, os, json
data = json.dumps({app: sunsama, method: MCP}).encode()
req = urllib.request.Request(https://ctrl.maton.ai/connections, data=data, method=POST)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Content-Type, application/json)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
获取连接
bash
python <
import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections/{connection_id})
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
响应：
json
{
connection: {
connection_id: 313c5234-8ddb-4be6-b0f2-836a864bed9f,
status: PENDING,
creation_time: 2026-03-03T10:44:23.480898Z,
url: https://connect.maton.ai/?session_token=...,
app: sunsama,
method: MCP,
metadata: {}
}
}
在浏览器中打开返回的url以完成OAuth授权。
删除连接
bash
python <
import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections/{connection_id}, method=DELETE)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
MCP参考
所有MCP工具均使用POST方法：
任务管理
| 工具 | 描述 | 模式 |
|---|
| searchtasks | 按关键词搜索任务 | schema |
| createtask |
创建新任务 |
schema |
| edit
tasktitle | 更新任务标题 |
schema |
| delete
task | 删除任务 | schema |
| marktaskascompleted | 标记任务完成 | schema |
| marktaskasincomplete | 标记任务未完成 | schema |
| appendtasknotes | 添加任务备注 | schema |
| edittasktimeestimate | 设置时间估算 | schema |
| edittaskrecurrencerule | 设置重复规则 | schema |
| gettasktimeestimate | 获取AI时间估算 | schema |
| restoretask | 恢复已删除任务 | schema |
子任务
| 工具 | 描述 | 模式 |
|---|
| addsubtaskstotask | 添加子任务 | schema |
| editsubtasktitle |
更新子任务标题 | schema |
| marksubtaskascompleted | 标记子任务完成 | schema |
| marksubtaskasincomplete | 标记子任务未完成 | schema |
待办箱
| 工具 | 描述 | 模式 |
|---|
| getbacklogtasks | 列出待办箱任务 | schema |
| movetasktobacklog |
将任务移至待办箱 | schema |
| movetaskfrombacklog | 从待办箱移至某天 | schema |
| repositiontaskinbacklog | 重新排序待办箱任务 | schema |
| changebacklogfolder | 更改任务文件夹 | schema |
| createbraindumptask | 创建待办箱任务 | schema |
日程安排
| 工具 | 描述 | 模式 |
|---|
| movetasktoday | 重新安排任务 | schema |
| reordertasks |
重新排序当天任务 | schema |
| timeboxatasktocalendar | 为任务预留时间块 | schema |
| setshutdowntime | 设置每日结束时间 | schema |
日历事件
| 工具 | 描述 | 模式 |
|---|
| createcalendarevent | 创建日历事件 | schema |
| deletecalendarevent |
删除日历事件 | schema |
| movecalendarevent | 重新安排事件 | schema |
| importtaskfromcalendarevent | 将事件导入为任务 | schema |
| setcalendareventallowtaskprojections | 切换任务重叠显示 | schema |
| acceptmeetinginvite | 接受会议邀请 | schema |
| declinemeetinginvite | 拒绝会议邀请 | schema |
时间追踪
| 工具 | 描述 | 模式 |
|---|
| starttasktimer | 启动计时器 | schema |
| stoptasktimer |
停止计时器 | schema |
频道与目标
创建
