Connect Planful to Claude: Sync GL Data & Manage Model Hierarchies

If your finance team needs to connect Planful to Claude to automate month-end close reporting, execute complex data load rules, or manage analytic model hierarchies, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Planful's complex corporate performance management (CPM) APIs.

You can either build and maintain this infrastructure yourself, dealing with Planful's dual authentication schemes and strict pagination, or you can use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our sibling guide on connecting Planful to ChatGPT, or explore our broader architectural overview on connecting Planful to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling financial ecosystem like Planful is a heavy engineering lift. Every time a finance admin wants to append a new dimension member or execute a calc script, the underlying API expects highly specific identifiers and strictly typed payloads.

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

The Engineering Reality of the Planful API

A custom MCP server is essentially a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against a CPM platform like Planful is painful.

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

The Split-Brain Authentication Model Planful operates with a split API architecture. The standard REST API - used for Data Load Rules (DLRs), user management, and transactional data - requires an Access ID and Access Key for authorization. However, if you want to interact with Master and Analytic models - tasks like clearing leaf data, appending model members, or running calculations - you enter the "Dynamic Planning" domain. This secondary domain completely ignores the Access ID and Key, requiring an X-Access-Token instead. A raw integration forces the LLM to guess which auth header to use for which endpoint. A managed MCP handles this credential mapping upstream, presenting a unified interface to the model.

Complex Data Load Rules (DLR) and Chunking Pushing financial data into Planful is not a simple POST request. Batched data transfers require orchestrating a stateful sequence. You must send chunks of data (capped at 40MB per request), monitor chunk responses, and strictly on the final batch, you must inject an IsLoadCompleted=true header so Planful knows to close the load and process the queue. Furthermore, execution is asynchronous. You receive an ExecutionId that must be repeatedly polled via a separate status endpoint to verify if the data actually landed.

Strict OData Filtering for GL Extracts Extracting General Ledger (GL) data from Planful is highly constrained. The API mandates specific query parameters just to execute the call - for example, querying Actual scenarios requires a mandatory FiscalYear parameter. Additionally, filtering segments requires precise OData $filter syntax. If your LLM hallucinates standard REST query parameters instead of OData strings, the request will fail.

Managed MCP servers solve these problems by mapping these rigid constraints into strictly typed JSON Schemas, guiding Claude to construct valid payloads every time.

How to Generate the Planful MCP Server

Truto derives MCP tools dynamically from the API documentation and resource schemas defined in your Planful integration. You do not write boilerplate code to map endpoints to tools. Instead, you create a server tied to a specific authenticated tenant.

You can generate this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For internal teams and quick testing, the UI is the fastest path:

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select your connected Planful account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., allowing only read operations for a read-only financial agent).
6. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

For production deployments where you need to spin up temporary or scoped access for user-facing agents, use the REST API.

Make an authenticated POST request to generate the server. The response will return the tokenized URL.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Planful Financial Analyst Agent",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The API returns a fully qualified JSON-RPC 2.0 endpoint ready for Claude to consume.

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with your Claude client. You can do this visually or via the configuration file.

Method A: Via the Claude UI (or ChatGPT Developer Mode)

If you are using a UI that supports direct connector additions:

1. Open your client settings (e.g., in Claude Desktop: Settings -> Integrations -> Add MCP Server).
2. Name the integration "Planful ERP".
3. Paste the Truto MCP URL.
4. Click Add. The client will automatically send an initialize request to the URL, discover the tools, and make them available to the model.

Method B: Via the Claude Config File

For developer environments, you can configure Claude Desktop manually by editing your claude_desktop_config.json file. Because Truto MCP servers use the SSE (Server-Sent Events) transport for remote connections, you will use the official @modelcontextprotocol/server-sse package to proxy the connection.

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

Restart Claude Desktop. The agent now has direct, authenticated access to the Planful toolset.

Planful Hero Tools for AI Agents

Truto exposes the entirety of the Planful API, but when building financial agents, certain endpoints provide massive leverage. Here are the hero tools your agent will use to automate core CPM workflows.

1. create_a_planful_data_transferfile

This tool handles file-based data ingestion. It transfers CSV or ZIP files directly into Planful through a defined Data Load Rule (DLR). Because the payload accepts base64-encoded strings, Claude can generate or transform financial data, encode it, and execute the load in a single step.

"I have a CSV string containing this month's department expenses. Encode it as base64 and upload it to Planful using the DLR named 'Monthly_Opex_Load' with a comma delimiter."

2. list_all_planful_running_data_load_status

Because Planful data transfers run asynchronously, you cannot assume a successful POST means the data is available. This tool requires only the DLR name to fetch detailed execution status (e.g., Uploading, Processing, Processed, Failed), allowing the agent to poll and verify load completion before proceeding to report generation.

"Check the running data load status for 'Monthly_Opex_Load'. If it is still processing, wait 30 seconds and check again. Let me know when it returns 'Processed' and tell me how many records were received."

3. list_all_planful_gl_data

This is the core extraction tool for financial analysis. It retrieves General Ledger data for leaf-level members. The schema explicitly maps mandatory requirements - if the agent requests the "Actual" scenario, it knows it must also pass the FiscalYear parameter.

"Fetch the GL data for the 'Actual' scenario for Fiscal Year 2025. Once you have the results, aggregate the amounts by Segment2 (Department) and give me a summary table of the top spenders."

4. create_a_planful_model_calculation_run

Calculations in Planful's Dynamic Planning module drive the actual financial logic (allocations, currency translations, forecasting). This tool invokes a named calculation script against a specific Master or Analytic model.

"Run the calculation script named 'Q3_Forecast_Allocation' on the 'Corporate_Finance' model. Verify the request succeeds, then check the calculation status to ensure it completes without errors."

5. create_a_planful_model_member_append

Organizations constantly evolve, requiring updates to dimension hierarchies (e.g., adding a new cost center). This tool appends dimension members to models. Truto handles routing this through the Dynamic Planning access token under the hood.

"We added a new marketing sub-department. Append a new dimension member to the 'Department' dimension in the 'Corporate_Finance' model. The new member code is 'MKT-400' under the parent hierarchy 'Marketing'."

6. planful_report_data_search

Extracting structured reports directly from the system ensures the LLM is reasoning over the exact figures presented to the executive team. This tool retrieves both metadata (row/column headers) and the actual data matrix from financial reports generated within Planful.

"Retrieve the report data for the report code 'Q3_Board_Summary'. Parse the row and column headers, map them to the data matrix, and write a two-paragraph executive summary on our net revenue performance."

For the complete inventory of Planful tools, schemas, and parameter requirements, see the Planful integration page.

Workflows in Action

Exposing individual tools is only the first step. The true power of an MCP integration emerges when Claude orchestrates multi-step financial workflows automatically.

Workflow 1: Month-End Close Execution and Verification

During month-end close, financial controllers waste hours loading data, waiting for confirmation, and pulling extracts to verify the numbers tie out. An AI agent can automate this entirely.

"Execute the 'End_Of_Month_Actuals' data load rule with the attached CSV data. Monitor the job until it is fully processed. Once complete, pull the GL data for the Actual scenario for FY2025 and confirm that total revenue matches $4.2M."

How the agent executes this:

1. Calls create_a_planful_data_transferfile to submit the payload and receives an ExecutionId.
2. Enters a polling loop using list_all_planful_running_data_load_status to monitor the DLR name until the status returns Processed.
3. Calls list_all_planful_gl_data passing Scenario=Actual and FiscalYear=2025.
4. Parses the returned JSON, aggregates the revenue accounts, and verifies the total against the user's prompt.

sequenceDiagram
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Planful as Planful API

    Claude->>Truto: call create_a_planful_data_transferfile
    Truto->>Planful: POST /DataTransfer (Access Key)
    Planful-->>Truto: ExecutionId returned
    Truto-->>Claude: Status payload
    Claude->>Truto: call list_all_planful_running_data_load_status
    Truto->>Planful: GET /RunningStatus
    Planful-->>Truto: Status: "Processing"
    Truto-->>Claude: Status update
    Claude->>Truto: call list_all_planful_gl_data
    Truto->>Planful: GET /GLDataExtract
    Planful-->>Truto: GL Data JSON
    Truto-->>Claude: Aggregates and verifies totals

Workflow 2: Dynamic Planning Hierarchy Adjustments

When a company reorganizes, financial models must be updated immediately to reflect new rollups, followed by recalculating the forecasts.

"We are splitting the Engineering cost center. Append a new member 'ENG-QA' to the Department dimension in the 'OpEx_Model'. Then, execute the 'Reallocate_Overhead' calculation script on that model to distribute the costs."

How the agent executes this:

1. Calls create_a_planful_model_member_append passing the modelName, dimensionName, and the new hierarchy structure. (Truto handles injecting the X-Access-Token required for Dynamic Planning APIs).
2. Calls create_a_planful_model_calculation_run passing the model and the calcScriptName.
3. Optionally calls planful_model_calculation_statuses_search to verify the math engine completed the reallocation successfully.

Handling Rate Limits

Planful enforces API rate limits to protect infrastructure, especially during heavy data loading periods.

It is critical to note that Truto does not retry, throttle, or apply automatic backoff on rate limit errors. When the upstream Planful API returns an HTTP 429 Too Many Requests, Truto passes that exact error directly back to the caller.

To help your agents handle this gracefully, Truto normalizes the upstream rate limit information into standardized headers following the IETF specification:

• ratelimit-limit: The maximum number of requests permitted in the window.
• ratelimit-remaining: Requests remaining in the current window.
• ratelimit-reset: The time at which the current rate limit window resets.

Your AI agent, LangGraph orchestrator, or client application is strictly responsible for interpreting these headers and executing its own backoff logic before retrying the tool call.

Security and Access Control

Giving an LLM access to corporate financial data requires strict governance. Truto MCP servers support configuration filters that allow you to lock down what the model can see and do:

• Method Filtering: You can strictly enforce read-only access by passing methods: ["read"] during server creation. This exposes only get and list operations, ensuring the agent cannot execute calculations or append hierarchy data.
• Tag Filtering: Restrict the server to specific domains. For example, passing tags: ["dynamic_planning"] will only expose tools related to Master and Analytic models, hiding user administration endpoints.
• Require API Token Auth: By setting require_api_token_auth: true, possession of the MCP URL is no longer enough. The client must also pass a valid Truto API token in the Authorization header, adding a second layer of identity verification.
• Expiration: Use the expires_at field to create ephemeral servers. This is perfect for giving an external consultant or temporary AI agent access to run a specific reporting workflow for a 24-hour window, after which the server auto-destructs.

Wrapping Up

Integrating Planful with Claude transforms a static CPM platform into an interactive, agentic financial analyst. By utilizing a managed MCP architecture, engineering teams bypass the grueling work of managing dual authentication schemes, parsing OData filters, and orchestrating stateful Data Load Rules.

Instead of maintaining abstraction layers and reading API documentation, your team can focus on designing the system prompts and guardrails that allow your AI agents to close the books faster, reallocate budgets dynamically, and extract board-ready financial insights with zero code.