Connect Pigment to Claude: Sync Model Data and Manage Import Jobs

If you need to connect Pigment to Claude to automate financial modeling, trigger data flow pipelines, or manage bulk CSV and Looker imports, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's function calling capabilities and Pigment's complex REST APIs. You can either build and maintain this infrastructure 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 connecting Pigment to ChatGPT or explore our broader architectural overview on connecting Pigment to AI Agents.

Giving a Large Language Model (LLM) read and write access to an enterprise business planning platform like Pigment requires careful engineering. You are dealing with massive datasets, asynchronous data pipelines, strict concurrency limits, and a specialized domain model consisting of blocks, lists, metrics, and views. Every time you want an agent to interact with a model, you have to ensure it understands the underlying job execution state.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Pigment, connect it natively to Claude, and execute complex FP&A (Financial Planning and Analysis) workflows using natural language.

The Engineering Reality of the Pigment API

A custom MCP server is 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 specialized enterprise planning APIs is difficult. Pigment is designed to handle complex multidimensional data. Its API reflects the need to ingest, calculate, and export high volumes of data asynchronously.

If you decide to build a custom Pigment MCP server, here are the specific integration challenges you will face:

Asynchronous Pipeline Orchestration Pigment does not process large data imports synchronously. If you push a CSV or trigger a Looker integration, the API does not block and return the ingested data. Instead, it returns a 202 Accepted response with an importId or dataFlowExecutionId. An LLM naturally expects a synchronous response (e.g., "I uploaded the file, here is the updated row count"). To make this work with an agent, your MCP server must expose discrete tools for triggering the action and separate tools for polling the status. You must also rely on prompt engineering to teach the LLM to enter a polling loop until the status returns Completed.

Granular Export Constraints Extracting data from Pigment is highly specific. You cannot just issue a generic "get data" query. Pigment requires you to export specific block types - Views, Lists, Metrics, or Tables - and it returns this data as raw CSV payloads (text/csv). Passing a massive CSV payload directly back into a conversational LLM context window will immediately consume token limits. An effective MCP implementation must either compress this payload, stream it to a secondary storage location, or strictly limit the rows returned.

Strict Concurrency and Rate Limiting Pigment enforces strict limits on concurrent data flow executions. If an agent tries to trigger multiple heavy calculation pipelines simultaneously, the API will reject the requests with an HTTP 429 (Too Many Requests).

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the Pigment API returns an HTTP 429, Truto passes that error directly to the MCP caller. Truto normalizes upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller - your agent or orchestration framework - is entirely responsible for interpreting these headers and executing the appropriate retry and backoff logic.

How to Create the Pigment MCP Server

Truto dynamically generates MCP tools based on the existing documentation and resource definitions of your connected Pigment account. Tools are not hand-coded or statically cached; they are derived at runtime when the Claude client calls tools/list.

There are two ways to generate an MCP server for Pigment using Truto.

Method 1: Via the Truto UI

For administrators and non-developers, the UI provides a fast way to generate a secure server URL.

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your active Pigment connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can optionally filter by methods (e.g., only read operations) or specify tags to group tools.
5. Copy the generated MCP server URL. (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

For platform engineering teams dynamically provisioning agent infrastructure, you can generate the MCP server programmatically.

Make an authenticated POST request to /integrated-account/:id/mcp.

curl -X POST https://api.truto.one/integrated-account/YOUR_PIGMENT_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pigment FP&A Agent",
    "config": {
      "methods": ["read", "write", "custom"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API validates that the integration has documented tools available, generates a secure cryptographically hashed token stored in Cloudflare KV, and returns the endpoint details.

{
  "id": "mcp-789-pigment",
  "name": "Pigment FP&A Agent",
  "config": { "methods": ["read", "write", "custom"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to Claude

Once you have the url from Truto, you need to configure Claude Desktop (or your custom agent framework) to use it.

Via the Claude UI (Settings)

If you are using the consumer-facing Claude desktop or enterprise web application:

1. Open Claude and navigate to Settings -> Integrations (or Connectors).
2. Click Add MCP Server.
3. Name the connection (e.g., "Pigment Truto").
4. Paste the Truto MCP URL into the connection field and save.

Claude will immediately call the initialize and tools/list endpoints, making the Pigment capabilities available in your chat interface.

Via Manual Configuration File

If you are running Claude Desktop locally for development, you can configure it via the claude_desktop_config.json file. Because Truto provides an SSE (Server-Sent Events) based remote server, you will use the official @modelcontextprotocol/server-sse package to proxy the connection.

Add the following to your configuration file:

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

Restart Claude Desktop. The agent is now securely authenticated to your Pigment environment.

Hero Tools for Pigment

Truto automatically derives highly descriptive snake_case tool names from Pigment's integration resources. The query and body parameters share a flat input namespace, which Truto safely maps to the upstream API using standardized JSON schema properties.

Here are the most high-leverage hero tools your agent will use to orchestrate Pigment.

list_all_pigment_data_flows

Before an agent can trigger a data pipeline, it needs to know what pipelines exist. This tool lists all configured Data Flows in a specific application.

Usage note: The agent must provide the application_id. You can instruct the agent to retrieve application IDs via the list_all_pigment_applications tool first if it does not have the context.

"List all data flows currently configured for the Q4 Financial Planning application."

create_a_pigment_data_flow_trigger

Executes a predefined data flow within Pigment. This is critical for forcing recalculations after new data is uploaded.

Usage note: This is an asynchronous operation. It returns a dataFlowExecutionId. The LLM must be instructed to expect an ID, not the final processed result. If the API returns a 429 due to too many concurrent executions, the agent must implement backoff before retrying.

"Trigger the 'Global Salary Recalculation' data flow using its ID, and give me the execution ID so we can track it."

get_single_pigment_data_flow_status_by_id

Polls the status of a previously triggered Data Flow.

Usage note: Returns statuses like InProgress, Completed, PartialFailure, or Failed. Your agent workflow should use this tool in a while-loop until a terminal state is reached.

"Check the status of data flow execution ID exec-4059. If it is still in progress, wait 10 seconds and check again."

create_a_pigment_push_csv

Pushes a raw CSV file payload to a specific Pigment import configuration.

Usage note: Requires the configuration_id and the file contents. Because it handles multipart form-data natively through the proxy API layer, the LLM just needs to provide the stringified CSV data in the correct parameter field.

"Push this CSV payload of new Q3 marketing hires into the Headcount Import configuration."

create_a_pigment_import_trigger

Triggers an automated integration-based import, list data copy, or metric data copy based on a configuration ID.

Usage note: Use this when data already exists in a connected external system (like Snowflake or Salesforce) and you need Pigment to pull it in. It returns an importId that must be tracked.

"Trigger the automated Salesforce Closed-Won Deals import into the Revenue model."

get_single_pigment_export_view_by_id

Exports the calculated data of a specific Pigment view as a CSV file.

Usage note: Returns raw text/csv. Be extremely careful asking Claude to return massive views directly to the screen. Always instruct the agent to summarize the output or limit its request to highly filtered views.

"Export the 'Executive Summary Dashboard' view and summarize the total ARR by region for the current quarter."

For the complete tool inventory and detailed schema requirements, review the Pigment integration page.

Workflows in Action

Connecting tools is only half the battle. You have to prompt Claude correctly to handle the asynchronous reality of Pigment's backend. Here are real-world operational workflows.

Workflow 1: Triggering and Monitoring a Model Recalculation

Financial teams often update external headcount systems and then need Pigment to recalculate the forecasted burn rate. An agent can automate the entire sync and calculation chain.

"Trigger the Headcount Sync data flow in the Core Planning app. Check its status until it finishes. If it completes successfully, let me know the completion time."

Execution Steps:

1. Claude calls list_all_pigment_applications to find the "Core Planning" app ID.
2. Claude calls list_all_pigment_data_flows using the app ID to find the ID for "Headcount Sync".
3. Claude calls create_a_pigment_data_flow_trigger and receives dataFlowExecutionId: "df-8821".
4. Claude enters a loop, calling get_single_pigment_data_flow_status_by_id with "df-8821".
5. Once the status returns Completed, Claude outputs the success message to the user.

sequenceDiagram
    participant User
    participant Claude as Claude Agent
    participant MCP as Truto MCP
    participant Pigment as Pigment API
    
    User->>Claude: Trigger Headcount Sync
    Claude->>MCP: create_a_pigment_data_flow_trigger(id)
    MCP->>Pigment: POST /api/dataflows/id/trigger
    Pigment-->>MCP: 202 (dataFlowExecutionId)
    MCP-->>Claude: executionId
    
    loop Poll Status
        Claude->>MCP: get_single_pigment_data_flow_status_by_id
        MCP->>Pigment: GET /api/dataflows/execution/id
        Pigment-->>MCP: Status: InProgress
        MCP-->>Claude: Status: InProgress
    end
    
    Pigment-->>MCP: Status: Completed
    MCP-->>Claude: Status: Completed
    Claude->>User: Data flow finished successfully.

Workflow 2: Auditing Import Errors

When automated imports fail, RevOps engineers need to know why without digging through the Pigment UI.

"Find the recent import jobs for the SFDC integration configuration. Check the status of the latest one, and if it failed, provide the detailed error report."

Execution Steps:

1. Claude calls list_all_pigment_import_configurations to find the SFDC integration ID.
2. (Assuming the user or previous context provided the specific import run), Claude calls get_single_pigment_import_status_by_id with included_detailed_report=true.
3. The tool returns the payload containing importStatus: "Failed" along with errorsDetails.
4. Claude parses the error details (e.g., "Data type mismatch on column ARR") and summarizes the root cause for the engineer.

Security and Access Control

Giving AI agents control over core financial models requires strict governance. Truto MCP servers enforce boundaries at the infrastructure level, preventing the LLM from hallucinating unauthorized actions.

• Method Filtering: You can restrict a server strictly to read-only operations by passing config: { methods: ["read"] } during creation. If the agent hallucinates a request to create_a_pigment_push_csv, the MCP router blocks it before it ever hits Pigment.
• Tag Filtering: Limit the MCP server to specific functional areas by passing tags. Only resources whose config.tool_tags intersect with the requested tags will be exposed to the LLM.
• require_api_token_auth: By default, possessing the MCP URL grants access. By enabling require_api_token_auth: true, you force the client to supply a valid Truto API token in the headers, adding a secondary authentication layer.
• Time-to-Live (expires_at): Assign an expiration timestamp (expires_at) when creating the server. Once the time is reached, Cloudflare KV drops the token and a Durable Object alarm hard-deletes the database record, instantly severing the LLM's access to Pigment.

Building AI agents that interact with complex B2B platforms like Pigment doesn't mean you have to write custom polling loops, manage OAuth token refreshes, or manually map JSON schemas to MCP tools. By relying on dynamic, documentation-driven MCP generation, you can focus on building agent intelligence while the infrastructure handles the integration reality.