How to Use an MCP Task Manager with AI Agents

August 4, 2026

What an MCP task manager changes

An AI assistant can discuss a pasted task list, but that list becomes stale as soon as work moves. An MCP task manager gives a compatible assistant structured tools for reading and changing the planner that you already use.

The important difference is not that the assistant can produce more text. It can request a specific operation such as reading this week, creating one task, moving an existing task, or reviewing planning context. The planner remains the record, and the MCP server remains the controlled bridge.

The WeekOrbit MCP Task Manager is the primary setup and reference page. This guide focuses on the decisions around that setup: permissions, verification, safe operating habits, and when MCP is the right connection method.

MCP, the REST API, and built-in AI are different layers

Choose the lightest layer that solves the job:

  • Built-in AI Planner: best when you want help inside the product and do not need another client.
  • MCP server: best when a compatible AI assistant should discover planner tools and call them by name.
  • REST API: best when your own script or service needs deterministic HTTP requests and response handling.

MCP does not replace the API underneath it, and it is not a workflow prompt library. It presents planner operations in a format an AI client can understand. The client decides when to request a tool call; the server authenticates the request, checks scopes, validates input, and applies product limits.

Before you connect a client

Prepare four things before opening a configuration file:

  1. A WeekOrbit account with a small set of test tasks.
  2. A dedicated API key created for this client.
  3. A compatible MCP client that can run a local stdio server.
  4. A clear first use case, such as reading the current week or creating one test task.

Do not reuse a key from another automation. One key per client makes access easier to understand and revoke. Start with read access when the first workflow only needs context; add write scopes only after the read path works.

Install the published MCP package

The server is distributed as weekorbit-mcp. A client launches it with npx and passes credentials through environment variables. The generic configuration shape is:

{
  "mcpServers": {
    "weekorbit": {
      "command": "npx",
      "args": ["-y", "weekorbit-mcp"],
      "env": {
        "WEEKORBIT_API_URL": "https://weekorbit.com",
        "WEEKORBIT_API_KEY": "paste-your-dedicated-key-here"
      }
    }
  }
}

Use the MCP setup page for the current client-specific commands and troubleshooting notes. Keep the key in the client's secret or environment settings; do not paste it into a prompt, commit it to a repository, or include it in a screenshot.

Verify the connection in three small steps

1. Prove that the client can see the server

Restart the client after saving its configuration. Confirm that the MCP server appears in the client's tool or connection list. If it does not appear, fix the launch command before testing planner permissions.

2. Start with a read-only request

Ask the assistant to list tasks for a narrow date range without making changes. A useful instruction is:

Read my tasks for this week. Summarize the dates and time blocks, but do not create, update, or delete anything.

This checks the server process, API URL, key, and read scope without changing planner data. If optional planning-analysis tools are enabled, test them only after the core read succeeds.

3. Create and clean up one test task

Add write access only when it is needed. Ask the assistant to create a clearly named test task on a specific date, then confirm that the task appears in the visual planner. Update that same task once and remove it when the test is complete.

This small cycle proves more than a long demonstration prompt. It verifies identity, scopes, write behavior, and the connection between the assistant's response and the planner's visible state.

Reproduce the shared-task example

The task operations in the AI weekly planning walkthrough were checked with the public 1.0.0 package and a real local planner API. This check did not evaluate a model's plan generation, its understanding of natural-language approval, or the built-in assistant end to end. Use the task ID returned by create_task, not a title guessed from chat.

Before trying the abbreviated calls below, choose two future dates in your planner's timezone. Replace initial_date with the first date and moved_date with a later date, both in YYYY-MM-DD format. They do not have to fall within the same week.

create_task({ title: "Write landing page copy", date: initial_date, time_block: "morning" })
// Keep the returned id as task_id. In the planner UI, change that task to moved_date.
get_task({ task_id })
// Check: date equals moved_date and completed is false.
update_task({ task_id, completed: true })
get_task({ task_id })
// Check: same id, date still equals moved_date, completed is true.

These abbreviated tool arguments illustrate the verified sequence; task_id is your own returned ID. Refresh the web board after external writes and verify the same result there. In the checked example two other tasks were read back to confirm they were unchanged. This proves a bounded operation, not automatic conflict resolution or live updates in every open tab.

On October 27, 2026, the published 1.0.0 process exposed 19 default tools and 4 more with PLANNING_V2_BACKEND_ENABLED=true. The optional flag also requires backend support. update_task_series exists in newer source but is absent from that public release; it is not needed by the basic example. See the versioned MCP reference before relying on series-edit operations.

A safe operating pattern for AI task management

Use a four-stage pattern for real work:

  1. Read: collect the current tasks and relevant planning context.
  2. Propose: let the assistant explain the intended changes before writing.
  3. Apply: execute the smallest useful set of tool calls.
  4. Verify: read the affected tasks again and inspect the weekly board.

This pattern is especially important for batch updates, recurring series, group changes, and deletions. The MCP server enforces authentication and scopes, but approval prompts are a client feature. Review the client's tool-permission settings instead of assuming every write will trigger the same confirmation screen.

Example: review capacity without handing over the week

A useful first workflow is a bounded capacity review:

  1. Read tasks from Monday through Sunday.
  2. Identify days with too many high-priority or time-blocked tasks.
  3. Propose no more than three moves.
  4. Keep deadlines and recurring rules unchanged.
  5. Apply only the moves that you approve.
  6. Read the changed tasks again and compare them with the weekly view.

This is different from asking the assistant to "optimize everything." The constraints make the result easier to inspect, and the final read catches mistakes before they spread through the plan.

Common connection failures

The server does not appear

Check that Node.js and npx are available to the client process, not only to a separate terminal. Confirm the package name and restart the client after editing its configuration.

The server starts but requests are unauthorized

Check whether the API URL points to https://weekorbit.com, whether the key is active, and whether hidden whitespace was copied with the key. Do not print the key while troubleshooting.

Reads work but writes fail

The key may have read scopes without the corresponding write scope. Add only the missing scope. A 403 is a permissions problem, not a reason to replace the key with unrestricted access.

Requests are rate-limited

MCP and REST API calls share the account's external request allowance. Reduce repeated polling, respect retry guidance, and avoid loops that send the same planning request continuously. Current allowances belong on the pricing page, not in a client configuration.

When the REST API is the better choice

Use MCP when an AI client should discover planner tools and decide which tool to call. Use the Planner REST API when your application needs explicit request construction, its own retry policy, server-to-server execution, or integration tests around a fixed sequence.

If you are still deciding, the Connect overview compares the built-in AI Planner, MCP, and API without duplicating their technical documentation. For planning habits rather than connection setup, read the AI weekly planning workflow.

Keep the planner as the verification layer

The durable value of MCP is not autonomous activity for its own sake. It is the ability to use an external assistant without creating a second, invisible task system.

Start with one read-only workflow, expand scopes deliberately, and verify writes on the same weekly board you use by hand. When you are ready, follow the authoritative WeekOrbit MCP Task Manager guide for the current installation details.

Ready to start planning?

WeekOrbit helps you see your whole week at a glance.

Try for Free