The Complete Beyond Time MCP Tools Reference: Every Tool, Every Prompt

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, Cursor, or a custom client, these Beyond Time MCP tools are 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. We'll walk through goals, milestones, habits, routines, daily actions, personal context, AI helpers, and the dashboard — with the level of detail you'd expect from good API docs.

This reference is aimed at power users automating their own life on the Beyond Time app, developers building integrations on top of Beyond Time Pro, and anyone curious how a planning surface should expose itself to LLMs. For the conceptual primer, see why personal AI changes the goal-achievement game and the Beyond Time MCP server launch notes.

How do you authenticate before calling these tools?

Every Beyond Time MCP tool runs against an authenticated Supabase session — the same session that powers the web app. Your MCP client connects to https://beyondtime.ai/mcp, completes OAuth, and the server attaches your user ID to every call. There is no separate API key.

• Write tools require an active session. If supabase.auth.getUser() returns no user, the tool responds with Not authenticated and isError: true.
• Row-level security is enforced server-side. You only ever touch your own data.

Call beyondtime_setup first as a sanity check, then beyondtime_get_dashboard to load the entire planning surface into one response. For broader context on the agentic stack, see the best AI productivity apps of 2026.

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.

"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.

"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.

"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.

"Delete the goal with id abc-123 from my Beyond Time plan."

How 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.

"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.

"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.

"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.

"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.

"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.

"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.

"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.

"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.

"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.

"Show me my Sleep routines."

How does beyondtime_create_routine work?

Creates a routine. Category defaults to Life if omitted.

"Add a Sleep routine called 'Phone in another room by 10pm'."

How does beyondtime_update_routine work?

Patches title, category, or active state.

"Move my 'Walk after lunch' routine from Life to Health."

How does beyondtime_delete_routine work?

Soft-deletes the routine.

"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.

"Suggest some Work routines for me."

How 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.

"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.

"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.

"Change action act-42 to 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.

"Mark action act-42 complete."

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.

"Move action act-42 to 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.

"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.

"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.

"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.

"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.

"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.

"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.

"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.

"Pull my full Beyond Time dashboard so you have full context before we plan."

What patterns work well across multiple tools?

A few patterns recur across these Beyond Time MCP 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 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 Beyond Time MCP tools fit into a real workflow?

The whole point of these Beyond Time MCP tools is to make a structured planning surface controllable by any agent the user already trusts. A typical loop: beyondtime_setup, then beyondtime_get_dashboard, 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 here composes cleanly into that loop — small inputs, structured outputs, soft deletes, and AI helpers that never write without confirmation. Open the Beyond Time app, create one goal and one action, reconnect via MCP, and run beyondtime_get_dashboard to see the same data come back as structured JSON.

Related Articles

Tutorials

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.

Apr 9, 202615 min read

AI

AI-Native Goal Tracking: What It Means, Why It Wins, and How to Try It Today

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.

Apr 1, 202616 min read

AI

Goal Tracking With MCP: Why Model Context Protocol Is the Future of Personal Productivity

Goal tracking MCP turns your AI assistant into a real coach. See how Model Context Protocol rewires personal productivity around open, agentic workflows.

Mar 19, 202618 min read

View all articles