The Complete Beyond Time MCP Tools Reference: Every Tool, Every Prompt
The canonical Beyond Time MCP tools reference: every tool, every parameter, every example prompt. Bookmark this developer-grade guide and ship faster.
If you're building an agent or automation on top of Beyond Time, you need exact answers. This is the canonical reference for Beyond Time MCP tools: every tool, every parameter, and a working example prompt for each one. Whether you're wiring Beyond Time into Claude Desktop or Claude Code, this covers everything you need to read, write, schedule, and reflect on a user's plan.
The endpoint is https://beyondtime.ai/mcp. Authenticate once with OAuth, register the server in your client, and every tool below becomes callable. For the conceptual primer, see why personal AI changes the goal-achievement game and the Beyond Time MCP server launch notes.
Quick start
Connect once at https://beyondtime.ai/mcp via OAuth, then start with beyondtime_setup to confirm your session, and beyondtime_get_dashboard to load the user's full plan into the model's context.
How do You authenticate before calling these tools?
Your MCP client connects to https://beyondtime.ai/mcp, completes OAuth, and every subsequent call is authenticated against that session. There is no separate API key.
- Write tools require an active session. An unauthenticated call returns
Not authenticatedwithisError: true. - Data access is scoped per user. Every tool call respects the same access controls as the web app — you only ever touch your own data.
Start each session with beyondtime_setup as a health check, then beyondtime_get_dashboard to load the full planning surface in one round-trip.
How do Goal tools work?
Goals (objectives in the database) are the top of Beyond Time's hierarchy. Everything else hangs off a goal. There's no archive tool — is_active: false covers that. For background on the OKR framing, see the complete guide to personal OKRs.
How does beyondtime_list_goals work?
Returns active, non-deleted goals for the current user, newest first. A lighter payload than the dashboard.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) | — | — | Takes no input. |
"Show me all my active goals on Beyond Time."
How does beyondtime_create_goal work?
Inserts a new goal (is_active: true, is_deleted: false). Title is the only required field.
| Parameter | Type | Required | Description |
|---|---|---|---|
title | string | yes | The title of the goal |
"Create a new Beyond Time goal called 'Run a sub-2-hour half marathon by October'."
How does beyondtime_update_goal work?
Patches title or active state. Both optional.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Goal ID |
title | string | no | New title |
is_active | boolean | no | Whether the goal is active |
"Rename my 'Get fit' goal to 'Run a sub-2-hour half marathon' and keep it active."
How does beyondtime_delete_goal work?
Soft-deletes (is_deleted: true, is_active: false). Child milestones and actions remain in the database but stop appearing in lists.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Goal ID to delete |
"Delete the goal with id
abc-123from my Beyond Time plan."
Try the Beyond Time app first
The MCP server mirrors the same goals, milestones, and actions you can manage in the app. See it before you wire it up.
Open Beyond TimeHow do Milestone tools work?
Milestones are stored as key_results server-side. They belong to a goal (objective_id) and carry progress, a done flag, and an optional target date. Three CRUD tools plus an AI suggester.
How does beyondtime_list_milestones work?
Returns non-deleted milestones, optionally filtered by goal. Includes progress, is_done, target_date, and ai_suggested.
| Parameter | Type | Required | Description |
|---|---|---|---|
goal_id | string | no | Filter by goal ID |
"List all milestones under my half-marathon goal."
How does beyondtime_create_milestone work?
Creates a milestone under a goal. Initializes progress: 0, is_done: false. Target date is ISO and optional.
| Parameter | Type | Required | Description |
|---|---|---|---|
goal_id | string | yes | The goal ID this milestone belongs to |
title | string | yes | Milestone title |
target_date | string | no | Target date (ISO format) |
"Add a milestone 'Complete a 10K race' to my half-marathon goal with target date 2026-07-15."
How does beyondtime_update_milestone work?
Patches title, progress (0–100), completion, or target date. Setting is_done: true without progress forces progress to 100 — handy for "mark done" intents.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Milestone ID |
title | string | no | New title |
progress | number | no | Progress percentage (0-100) |
is_done | boolean | no | Whether the milestone is completed |
target_date | string | no | New target date (ISO format) |
"Mark the '10K race' milestone as done."
How does beyondtime_suggest_milestones work?
Returns a numbered list of AI-generated milestone candidates given a goal title and the user's personal context. Read-only — call beyondtime_create_milestone to save chosen items.
| Parameter | Type | Required | Description |
|---|---|---|---|
goal_title | string | yes | The goal title to get suggestions for |
"Suggest milestones for my new goal 'Launch a paid newsletter by Q3'."
How do Habit tools work?
Habits are repeating intentions. Frequency is "daily" or a comma-separated weekday list like "mon,wed,fri". Four habit tools plus an AI suggester.
How does beyondtime_list_habits work?
Returns active, non-deleted habits with title, frequency, and ai_suggested. Newest first.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) | — | — | Takes no input. |
"What habits am I tracking on Beyond Time right now?"
How does beyondtime_create_habit work?
Creates a habit. Frequency defaults to "daily". Use weekday codes (mon,tue,wed,thu,fri,sat,sun) for partial-week habits.
| Parameter | Type | Required | Description |
|---|---|---|---|
title | string | yes | The habit title |
frequency_type | string | no (default "daily") | Frequency: "daily" or comma-separated days like "mon,wed,fri" |
"Add a habit 'Strength training' on mon, wed, fri."
How does beyondtime_update_habit work?
Patches title, frequency, or active state. Flipping is_active: false hides the habit without deleting it.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Habit ID |
title | string | no | New title |
frequency_type | string | no | New frequency |
is_active | boolean | no | Whether the habit is active |
"Change my 'Strength training' habit to mon, thu only."
How does beyondtime_delete_habit work?
Soft-deletes the habit (is_deleted: true, is_active: false). Historical completion data is preserved.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Habit ID |
"Delete my 'Cold shower' habit, I'm done with that experiment."
How does beyondtime_suggest_habits work?
Returns habit suggestions tailored to the user's goals and context, filtering out existing habits. Read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) | — | — | Takes no input. |
"Suggest habits I should add given my current Beyond Time goals."
How do Routine tools work?
Routines are reusable blocks of behavior, categorized as Health, Life, Sleep, or Work. Unlike habits, they aren't time-stamped — they're patterns you pull into a day. The category enum is strict.
How does beyondtime_list_routines work?
Returns active, non-deleted routines. Optionally filters by category.
| Parameter | Type | Required | Description |
|---|---|---|---|
category | enum (Health | Life | Sleep | Work) | no | Filter by category |
"Show me my Sleep routines."
How does beyondtime_create_routine work?
Creates a routine. Category defaults to Life if omitted.
| Parameter | Type | Required | Description |
|---|---|---|---|
title | string | yes | Routine title |
category_id | enum (Health | Life | Sleep | Work) | no | Category: Health, Life, Sleep, or Work |
"Add a Sleep routine called 'Phone in another room by 10pm'."
How does beyondtime_update_routine work?
Patches title, category, or active state.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Routine ID |
title | string | no | New title |
category_id | enum (Health | Life | Sleep | Work) | no | New category |
is_active | boolean | no | Whether the routine is active |
"Move my 'Walk after lunch' routine from Life to Health."
How does beyondtime_delete_routine work?
Soft-deletes the routine.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Routine ID |
"Delete the 'Sunday meal prep' routine — I've replaced it."
How does beyondtime_suggest_routines work?
Suggests routines for a category, conditioned on goals, context, and existing routines.
| Parameter | Type | Required | Description |
|---|---|---|---|
category | enum (Health | Life | Sleep | Work) | yes | Category to get suggestions for |
"Suggest some Work routines for me."
See routines and habits in action
Beyond Time Pro unlocks deeper AI suggestions across goals, milestones, habits, and routines.
Explore Beyond Time ProHow do Action (daily task) tools work?
Actions are concrete to-dos hanging off a milestone (key_result_id). Dates are stored as yyyyMMdd integers (e.g. 20260417 for April 17, 2026), which makes filtering cheap. Six tools cover the full lifecycle.
How does beyondtime_list_actions work?
Returns non-deleted actions, ordered by scheduled_day ASC (nulls last), then ordering, then creation. Filters compose freely.
| Parameter | Type | Required | Description |
|---|---|---|---|
key_result_id | string | no | Filter by key result ID |
scheduled_day | int (yyyyMMdd) | no | Filter by scheduled day (yyyyMMdd) |
is_done | boolean | no | Filter by completion state |
is_active | boolean | no | Filter by active state |
"List all my unfinished actions scheduled for 20260417."
How does beyondtime_create_action work?
Creates an action under a milestone. Priority defaults to normal. The cheapest call is just key_result_id + title.
| Parameter | Type | Required | Description |
|---|---|---|---|
key_result_id | string | yes | The key result ID this action belongs to |
title | string | yes | Action title |
notes | string | no | Optional action notes |
deadline | int (yyyyMMdd) | no | Optional deadline (yyyyMMdd) |
scheduled_day | int (yyyyMMdd) | no | Optional planned day (yyyyMMdd) |
estimated_minutes | int (0–1440) | no | Optional duration estimate in minutes |
priority | enum (high | normal) | no | Action priority: high or normal |
ordering | int (≥0) | no | Optional sort order within the key result |
ai_suggested | boolean | no | Whether this action was AI suggested |
"Add a high-priority action 'Draft the launch email' under milestone
kr-789, scheduled for 20260418, 45 minutes."
How does beyondtime_update_action work?
The most flexible tool. All fields optional except id. notes, deadline, scheduled_day, and estimated_minutes accept null to explicitly clear (vs. leaving untouched). Setting is_done also stamps completed_at.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Action ID |
title | string | no | New title |
notes | string | null | no | New notes, or null to clear |
deadline | int | null | no | New deadline (yyyyMMdd), or null to clear |
scheduled_day | int | null | no | New scheduled day (yyyyMMdd), or null to clear |
estimated_minutes | int | null | no | New estimated minutes, or null to clear |
priority | enum (high | normal) | no | New priority |
is_done | boolean | no | Whether the action is completed |
is_active | boolean | no | Whether the action is active |
ordering | int (≥0) | no | New sort order |
"Change action
act-42to high priority and clear its deadline."
How does beyondtime_complete_action work?
Sets is_done: true and stamps completed_at. Equivalent to update-with-is_done, but cheaper to express in a prompt.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Action ID |
"Mark action
act-42complete."
How does beyondtime_schedule_action work?
Schedules or unschedules an action onto a specific day, optionally updating the estimate and deadline at the same time. Pass scheduled_day: null to unschedule.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Action ID |
scheduled_day | int | null | yes | Scheduled day (yyyyMMdd), or null to unschedule |
estimated_minutes | int | null | no | Optional estimate in minutes, or null to clear |
deadline | int | null | no | Optional deadline (yyyyMMdd), or null to clear |
"Move action
act-42to 20260420 and set the estimate to 30 minutes."
How does beyondtime_delete_action work?
Soft-deletes the action. The completion stamp, if any, is preserved.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Action ID |
"Delete action
act-99— it duplicates another task."
How do Personal context tools work?
Personal context (memories server-side) is how Beyond Time personalizes everything. Items are short statements — "I am a software engineer", "I wake up at 6am" — that the AI suggesters read before generating output. Three tools: list, create, delete. No update tool by design — if a fact changes, delete and re-add.
How does beyondtime_list_personal_contexts work?
Returns every active, non-deleted personal context item for the user.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) | — | — | Takes no input. |
"What personal context does Beyond Time know about me?"
How does beyondtime_create_personal_context work?
Adds a single context item. Max 3000 chars (~400 words). Suggester quality is best when items are short and atomic.
| Parameter | Type | Required | Description |
|---|---|---|---|
title | string (1–3000) | yes | The personal context item (max ~400 words) |
"Add personal context: 'I'm a software engineer with two kids and I wake up at 6am'."
How does beyondtime_delete_personal_context work?
Soft-deletes a personal context item.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Personal context ID |
"Remove the personal context item with id
mem-12."
How do AI helper tools work?
Two AI tools generate motivational and reflective content keyed to the user's goals and context. Both take no parameters.
How does beyondtime_daily_quote work?
Returns a personalized quote tailored to the user's active goals and context. The handler injects a random seed letter and date for variety. Output includes the quote, author (when available), and a short relevance reason.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) | — | — | Takes no input. |
"Give me my Beyond Time daily quote."
How does beyondtime_daily_reflection work?
Generates an AI critique over planned goals and context. Useful as the closing call in an end-of-day agent.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) | — | — | Takes no input. |
"Write me a daily reflection on how I'm pacing against my goals."
How does The dashboard tool work?
Two tools sit apart from the CRUD families: a setup check and a composite read for the entire plan. Both are designed as the first calls in a session.
How does beyondtime_setup work?
Verifies the OAuth session and returns connection details: display name, email, timezone, plan, main goal, focus areas. Pure connection check, no goal or action reads.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) | — | — | Takes no input. |
"Check my Beyond Time connection and show my profile."
How does beyondtime_get_dashboard work?
The most efficient read in the API. Loads goals, milestones, actions, habits, routines, and personal context in parallel, then returns a structured summary with per-goal counts, per-milestone progress, routines grouped by category, and a flat list of personal context titles. Start here — it saves five or six round trips.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) | — | — | Takes no input. |
"Pull my full Beyond Time dashboard so you have full context before we plan."
Composite reads beat chained reads
beyondtime_get_dashboard returns a denormalized view of the entire plan in a single response. For agents that reason across goals and actions in one turn, this is dramatically cheaper than chaining list calls.
What patterns work well across multiple tools?
Soft deletes everywhere. Every delete tool sets is_deleted: true and is_active: false. Suggesters filter soft-deleted items out immediately. No undelete — recreate if you need it back.
Active flag for pause-without-delete. is_active: false is the state for "not relevant now but I might return." List tools filter on is_active: true; the dashboard returns everything.
Suggesters never write. The three *_suggest_* tools return text only. Call the matching create_* tool to persist suggestions.
Dates as integers. Action scheduled_day and deadline are yyyyMMdd integers. Milestone target_date is ISO.
Read once, write many. Call beyondtime_get_dashboard, plan in the model, then batch creates and schedules.
Pro vs Free parity. All MCP tools are available on both plans. Differences show up in app-side AI quotas only.
Frequently Asked Questions
Where do I connect to the Beyond Time MCP server?
The endpoint is https://beyondtime.ai/mcp. Add it to your MCP client as a remote server, complete OAuth, and every tool above becomes callable.
Do these tools work the same on Free and Pro plans?
Yes. The full set of MCP tools is available on every plan. Pro changes app-side AI usage but does not gate the MCP surface. See Beyond Time Pro.
Why are some entities called goals in docs but objectives in the database?
A deliberate split. Goals and milestones are user-facing; objectives and key_results are the OKR-rooted database names. Tool names use the user-facing terms — you only see the server-side names in raw beyondtime_get_dashboard rows where joins use objective_id and key_result_id.
How do I batch-create a week's worth of actions efficiently?
Call beyondtime_get_dashboard to load the plan, then issue parallel beyondtime_create_action calls and layer scheduling on top with beyondtime_schedule_action. Much cheaper than chaining list calls per milestone.
Can the AI suggester tools write directly to my plan?
No. The three suggesters are pure read tools — they generate text, never persist. To save a suggestion, follow up with the matching create_* tool.
What happens if I call a tool while not authenticated?
Write tools return Not authenticated with isError: true. Re-run OAuth in your MCP client. beyondtime_setup is the cheapest health check before a longer agent run.
Is there a hard-delete option?
No. All delete tools soft-delete (is_deleted: true, is_active: false), preserving history. To purge data, use your account settings in the Beyond Time app.
How do These tools fit into a real workflow?
A typical agent loop: beyondtime_setup to verify auth, then beyondtime_get_dashboard to load the full plan, then a focused sequence of writes — create a milestone, schedule three actions, suggest a couple of habits, mark yesterday's actions complete, finish with beyondtime_daily_reflection.
Every tool composes cleanly into that loop: small inputs, structured outputs, soft deletes, and AI helpers that never write without confirmation. Start with one goal and one action in the Beyond Time app, then call beyondtime_get_dashboard to confirm the data round-trips correctly.
Start building on Beyond Time
Connect your MCP client to https://beyondtime.ai/mcp and start automating your goals, milestones, and daily actions in minutes.
Get Started FreeResearch and Further Reading
For deeper background on the ideas referenced in this post:
Related Articles
How to Track Your Goals From Claude (Step-by-Step MCP Setup Guide)
Learn how to track goals from Claude with this step-by-step MCP setup guide. Connect Claude Desktop to Beyond Time and manage goals straight from chat.
Scattered Goals to Focused Action: Setup Guide
Turn your list of scattered goals into a focused action system in under an hour. This step-by-step setup guide walks you through the entire process.
How to Plan Your Quarter in 30 Minutes with Beyond Time
Learn how to create a complete quarterly plan in just 30 minutes. Beyond Time's AI milestones and OKR framework make 90-day planning fast and actionable.
The Student's Guide to Using Beyond Time for Academic Success
Learn how to use Beyond Time to set academic goals, build study habits, and create routines. Discover the system behind your best semester yet.
AI-Native Goal Tracking: What It Is and Why It Wins
AI-native goal tracking replaces forms and dashboards with conversation, memory, and proactive moves. See what the shift means and how to try it today.
Goal Tracking With MCP: The Future of Productivity
Goal tracking MCP turns your AI assistant into a real coach. See how Model Context Protocol rewires personal productivity around open, agentic workflows.