Connect Forecast to Claude: Track Time, Tasks, and Project Phases

If you need to connect Forecast to Claude to automate time tracking, analyze project financials, or orchestrate resource allocation, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Forecast's REST API. You can either build and maintain this integration layer yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on /connect-forecast-to-chatgpt-manage-project-teams-and-resources/, or explore our broader architectural overview on /connect-forecast-to-ai-agents-orchestrate-billing-and-financials/.

Giving a Large Language Model (LLM) read and write access to a sprawling resource and project management ecosystem like Forecast is an engineering challenge. You have to handle API token lifecycles, map massive nested JSON schemas to MCP tool definitions, and deal with Forecast's specific data validation rules. Every time Forecast deprecates a legacy endpoint or updates an API version, you have to rewrite your server code, redeploy, and retest the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Forecast, connect it natively to Claude Desktop, and execute complex project management workflows using natural language.

The Engineering Reality of the Forecast API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable JSON-RPC interface for models to discover tools, the reality of implementing it against specialized B2B APIs is painful. Forecast is built to manage complex organizational hierarchies - clients, projects, phases, tasks, subtasks, and financial milestones - and its API reflects that complexity.

If you decide to build a custom Forecast MCP server, you own the entire API lifecycle. Here are the specific integration challenges you will face:

Fragmented API Versions and Legacy Endpoints Forecast is actively migrating endpoints. For instance, time registrations span legacy V3 endpoints and newer V4 endpoints, each with different schema requirements and query filters. Similarly, legacy "cards" and "subtasks" are deprecated in favor of new "tasks" and "to-dos". An LLM has no context on which API version to use. If you build this yourself, you must build an abstraction layer that presents a curated, unified set of operations to Claude, hiding the underlying endpoint fragmentation so the model does not hallucinate obsolete payloads.

Deeply Nested Relational Dependencies Forecast operations are highly relational. You cannot simply "create an expense" in a vacuum. Modifying a baseline expense requires a project_id, a phase_id, and the expense id. Creating a time registration requires a person_id, the time registered, a specific date format, and exactly one of a project_id, task_id, or non_project_time_id. An LLM will frequently fail to construct these payloads correctly unless the MCP server strictly enforces JSON schemas and explicitly groups required path parameters and body payloads into a flat, understandable input namespace for the model.

Strict Timestamps and Rate Limit Handling Forecast requires highly specific timestamp formatting for filtering - for example, the updated_after parameter expects exactly YYYYMMDDTHHmmss (e.g., 20180216T210047), while date_after expects YYYYMMDD. If the LLM sends standard ISO 8601 strings, the API will reject the request.

Furthermore, API quotas are a reality. It is critical to understand how rate limits work in a managed environment: Truto does not automatically retry, throttle, or apply backoff on rate limit errors. When the upstream Forecast API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller - in this case, the Claude agent orchestrator or your client application - is strictly responsible for inspecting these headers and executing retry and backoff logic.

Step 1: Generating the Forecast MCP Server

Instead of writing and maintaining custom routing logic, handling authentication, and manually coding JSON schemas for every Forecast endpoint, you can use Truto to instantly generate an MCP server.

Truto creates MCP tools dynamically derived from the underlying API documentation. A tool only appears in the MCP server if it has a corresponding documentation schema, which acts as a quality gate ensuring the LLM only sees well-defined operations.

You can generate the MCP server in two ways: via the Truto UI or programmatically via the API.

Method A: Via the Truto UI

1. Navigate to the integrated account page for your connected Forecast instance in the Truto dashboard.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can filter by HTTP methods (e.g., read-only access) or functional tags (e.g., only "time-tracking" tools), and optionally set an expiration date.
5. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method B: Via the API

For automated deployments or dynamic agent provisioning, you can generate the MCP server programmatically. Truto will validate the requested filters, ensure tools exist, and return a cryptographically secure token URL.

// POST /integrated-account/:id/mcp
const response = await fetch('https://api.truto.one/integrated-account/<forecast-account-id>/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_TRUTO_API_TOKEN>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Claude Forecast Agent",
    config: {
      methods: ["read", "write"] // Or restrict to "read" only
    },
    expires_at: null // Optional ISO datetime for automatic expiration
  })
});
 
const data = await response.json();
console.log(data.url); 
// Output: "https://api.truto.one/mcp/a1b2c3d4..."

Step 2: Connecting the MCP Server to Claude

Once you have your Truto MCP URL, connecting it to Claude is a matter of configuration. The server URL contains a cryptographic token that encodes the account, tools, and permissions.

Method A: Via the Claude UI (Desktop/Web)

If you are using the standard Claude interface:

1. Open Claude and navigate to Settings -> Integrations -> Add MCP Server.
2. Paste your Truto MCP URL.
3. Click Add. Claude will immediately execute the JSON-RPC initialize handshake, discover the available tools, and make them available in your chat context.

Method B: Via Manual Config File (Claude Desktop)

If you are configuring Claude Desktop manually via its configuration file, you can use the Server-Sent Events (SSE) transport provided by the Model Context Protocol SDK.

Edit your claude_desktop_config.json file:

{
  "mcpServers": {
    "forecast-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/<YOUR_SECURE_TOKEN>"
      ]
    }
  }
}

Restart Claude Desktop. The application will connect to the Truto MCP router and dynamically load the Forecast tools.

Hero Tools for Forecast Automation

Truto exposes Forecast's extensive API surface area as individual, callable tools. By flattening the input namespace, the MCP router seamlessly splits LLM arguments into the correct query parameters and request bodies based on the underlying integration schemas.

Here are some of the highest-leverage tools available for your AI agents.

list_all_forecast_projects

Retrieves all projects in the Forecast environment. This is typically the starting point for any agentic workflow, allowing the LLM to discover project IDs, stages, statuses, and budgets. You can also retrieve progress metrics by instructing the model to pass the correct query flags.

"List all active projects in Forecast, and include their current progress and budget status."

get_single_forecast_task_by_id

Fetches deep details about a specific task, including its title, description, parent project, estimates, workflow column, assigned personnel, and labels.

"Get the details for task ID 45892. Who is assigned to it, what is the estimate, and what sprint is it currently in?"

create_a_forecast_time_registration

Logs a new time entry via the modern V4 endpoints. The tool schema enforces the requirement that a person ID, time registered, date, and exactly one contextual ID (project, task, or non-project time) are provided.

"Log 120 minutes of time for person ID 883 on task ID 45892 for today's date. Mark it as billable."

update_a_forecast_project_phase_by_id

Modifies an existing project phase. This is critical for agents acting as automated project managers, allowing them to shift start dates, end dates, and baseline dates when dependencies change.

"Update the 'Design' phase on project ID 102. Push the end date back by 5 days and update the baseline end date to match."

forecast_financials_get_financial_numbers

Extracts aggregated financial metrics for a specific date range, breaking down revenue recognition, baselines, planned vs actuals, forecasts to complete, and total at completion. This tool turns Claude into an instant financial analyst.

"Get the aggregated financial numbers for project ID 102 from January 1st to January 31st, grouped by month."

list_all_forecast_person_utilization

Retrieves utilization data for all company personnel over a specific timespan. It returns available minutes, allocated task minutes, idle time, and time-off.

"Pull the utilization data for all personnel next week. Identify anyone who has more than 10% idle time allocated."

For the complete inventory of available Forecast tools and their exact JSON schemas, visit the Forecast Integration Page.

Workflows in Action

An AI agent is only as powerful as the sequence of tools it can string together. Here is how Claude handles complex, multi-step operations using the Truto MCP server.

Scenario 1: Automated Financial and Capacity Review

Project managers constantly balance burn rates against team capacity. You can prompt Claude to audit a project's financials and immediately check if the team has the bandwidth to course-correct.

"Review the financials for project ID 102 for the current month. Compare the actual revenue to the planned revenue. If we are behind plan, check the utilization data for all personnel on that project for next week and tell me who has available capacity to take on more task hours."

How the agent executes this:

1. Calls forecast_financials_get_financial_numbers passing the startDate and endDate for the current month, filtered to project_id=102.
2. Analyzes the returned payload, noting the delta between planned and actual.
3. If behind plan, calls list_all_forecast_project_team_members to get the list of people on the project.
4. Calls list_all_forecast_person_utilization passing the date range for next week.
5. Correlates the team members with the utilization payload to highlight users with high idle_time_minutes_allocated or unallocated minutes_available.

Scenario 2: Developer Time Logging and Status Update

Developers hate leaving their IDEs to update tracking software. By integrating this MCP server into an IDE-based client like Cursor (or using Claude Desktop alongside your editor), developers can manage their Forecast tasks conversationally.

"I just finished the database migration script. Please log 4 hours to my assigned task for 'Database Migration' on the 'Backend Refactor' project, and then move that task to the 'Done' workflow column."

How the agent executes this:

sequenceDiagram
    participant Dev as Developer
    participant Agent as Claude
    participant MCP as Truto MCP Server
    participant API as Forecast API

    Dev->>Agent: "Log 4 hrs to Database Migration task..."
    Agent->>MCP: tools/call (list_all_forecast_tasks, {search: "Database Migration"})
    MCP->>API: GET /v3/tasks
    API-->>MCP: Returns task ID 9942
    MCP-->>Agent: Task ID 9942 data
    Agent->>MCP: tools/call (create_a_forecast_time_registration, {person: ..., task: 9942, time_registered: 240, date: "20231025"})
    MCP->>API: POST /v4/time_registrations
    API-->>MCP: 201 Created
    MCP-->>Agent: Success confirmation
    Agent->>MCP: tools/call (update_a_forecast_task_by_id, {id: 9942, workflow_column: "Done"})
    MCP->>API: PUT /v3/tasks/9942
    API-->>MCP: 200 OK
    MCP-->>Agent: Task updated
    Agent-->>Dev: "Logged 4 hours and moved task to Done."

Security and Access Control

Exposing an enterprise resource planning tool to an AI model requires strict governance. Truto provides multiple layers of security at the MCP token level:

• Method Filtering: You can enforce immutability by restricting an MCP server to methods: ["read"]. This ensures the LLM can call list and get endpoints but will be explicitly denied from calling create, update, or delete operations.
• Tag Filtering: Integrations can be grouped by tags. You can configure an MCP server to only expose tools tagged with time_tracking or reporting, hiding sensitive operations like user administration.
• Dual-Layer Authentication: By setting require_api_token_auth: true during server creation, possession of the MCP URL is no longer enough. The client must also pass a valid Truto API token in the Authorization header, meaning the end-user must actually be authenticated in your system to invoke the tools.
• Ephemeral Access: Using the expires_at property, you can generate short-lived MCP servers that automatically self-destruct. This is ideal for granting an AI agent temporary access to complete a specific batch job.

Escaping the Custom Integration Trap

Building a custom MCP server for Forecast means writing API wrappers, dealing with OAuth or API key lifecycles, and manually updating JSON schemas every time the vendor deprecates a V3 endpoint in favor of V4. It is a massive drain on engineering resources.

By leveraging Truto, you abstract away the underlying infrastructure. Truto handles the dynamic generation of schemas from documentation, routes the JSON-RPC protocol calls to the correct REST endpoints, and manages the lifecycle of the connection. Your AI agents get immediate, secure access to the tools they need to actually accomplish work, and your engineering team gets to focus on building your core product.