Connect Penneo to Claude: Create Case Files and Track Status

If you need to connect Penneo to Claude to automate digital signatures, KYC data collection, or case file generation, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Penneo's 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 Penneo to ChatGPT or explore our broader architectural overview on connecting Penneo to AI Agents.

Giving a Large Language Model (LLM) read and write access to a secure, heavily-audited system like Penneo is an engineering challenge. You have to handle OAuth 2.0 token lifecycles, translate complex multipart/form-data requirements into JSON schemas for the MCP tool definitions, and deal with Penneo's asynchronous job queues. Every time Penneo updates an endpoint or changes a document schema, you have to update your server code, redeploy, and test the integration.

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

The Engineering Reality of the Penneo 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 via JSON-RPC 2.0, the reality of implementing it against Penneo's specific API is painful. You are not just integrating a standard CRUD database - you are integrating a document management system with complex asynchronous flows.

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

Asynchronous Document Processing and Polling Penneo does not create case files instantaneously. When you submit a request to create a case file with attached PDFs and signers, Penneo adds the operation to a queue and returns a Job UUID. If you expose a standard "create" tool to Claude without accounting for this, the LLM will assume the document is ready immediately and hallucinate subsequent operations. You have to build explicit polling mechanisms into your MCP tools, forcing the LLM to query the job status until the queue returns a success state. Truto handles this by exposing the create_a_penneo_job_status endpoint as a distinct tool, allowing the agent to manage its own polling loop based on the UUID.

Multipart/Form-Data File Handling LLMs communicate strictly in text-based JSON. Penneo requires binary file uploads via multipart/form-data to attach PDFs to case files. A standard custom MCP server requires you to write extensive middleware to intercept the LLM's Base64 JSON payload, decode it, construct proper multipart boundaries, inject the correct MIME types, and forward it to Penneo. A managed MCP server abstracts this translation, allowing Claude to pass standard JSON tool calls that are automatically converted into the HTTP structure Penneo expects.

Dynamic and Unpredictable Form Schemas Penneo Collect forms allow your users to define custom data collection fields (text inputs, file uploads, dropdowns). When you query the list_all_penneo_casefile_answers endpoint, the shape of the response is entirely dependent on the specific form template. You cannot hardcode a static TypeScript interface or standard JSON Schema for the LLM. Truto's proxy execution layer circumvents this by passing the raw, un-opinionated JSON responses back to the LLM, relying on Claude's inherent ability to parse dynamic, nested document structures on the fly.

Strict Rate Limiting and Error Passthrough Penneo enforces API rate limits to protect its document generation queues. Truto does not retry, throttle, or apply backoff on rate limit errors. When Penneo returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller (the AI agent framework) is entirely responsible for reading these headers and implementing its own retry and exponential backoff logic.

How to Generate a Penneo MCP Server with Truto

Truto's MCP servers are generated dynamically. Rather than hand-coding tool definitions, Truto derives them from the integration's underlying resource definitions and API documentation records. A tool only appears in the MCP server if it has a corresponding documentation entry - acting as a quality gate to ensure Claude only sees well-described endpoints.

Each server is scoped to a single authenticated Penneo account and accessed via a cryptographically secure URL. You can generate this URL in two ways.

Method 1: Via the Truto UI

If you are a system administrator testing a workflow, the UI is the fastest path.

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select your connected Penneo instance.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read methods or apply specific tags).
6. Copy the generated MCP server URL. Keep this URL secure; it contains the authentication token.

Method 2: Via the API

For production deployments where you need to provision AI agents programmatically for your users, use the REST API. This endpoint validates the configuration, generates the server, and returns the connection URL.

// POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp
 
const response = await fetch(`https://api.truto.one/integrated-account/${accountId}/mcp`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TRUTO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Penneo Legal Automation Server",
    config: {
      methods: ["read", "write"], // Expose all CRUD operations
      require_api_token_auth: false
    },
    expires_at: "2025-12-31T23:59:59Z"
  })
});
 
const mcpServer = await response.json();
console.log(mcpServer.url); // The URL Claude needs to connect

How to Connect the MCP Server to Claude

Once you have the Truto MCP server URL, connecting it to Claude requires zero additional code. You can configure it through the UI or via the application configuration file.

Method 1: Via the Claude UI

If you are using Claude Desktop or Claude Web (depending on your Anthropic plan tier):

1. Open Claude and navigate to Settings.
2. Click on Integrations or Connectors.
3. Select Add MCP Server.
4. Paste the Truto MCP URL generated in the previous step.
5. Click Add. Claude will immediately perform a handshake, call the tools/list endpoint, and populate the model's context with the available Penneo operations.

Method 2: Via Manual Config File

For headless deployments, custom agent frameworks, or local Claude Desktop installations, you can define the server in your claude_desktop_config.json file. Truto provides an SSE (Server-Sent Events) transport bridge for standard MCP clients.

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

Restart Claude Desktop after updating this file. The model will automatically read the configuration and establish the JSON-RPC connection.

Penneo Hero Tools for Claude

The Truto proxy exposes Penneo's API surface as a flat, predictable set of tools. When Claude invokes a tool, Truto maps the flat JSON arguments back into the appropriate query parameters and body schemas required by Penneo. Here are the highest-leverage tools available for legal and compliance automation.

create_a_penneo_casefile

Initiates the creation of a new Penneo case file. This is the primary entry point for document workflows. Because this operation is asynchronous and handles document processing, it returns a job reference rather than the final case file data.

"Draft a standard mutual NDA based on our corporate template, then create a new Penneo case file named 'Acme Corp Mutual NDA'. Attach the generated document and set John Doe (john@acme.com) as the primary signer. Give me the job UUID when the request is queued."

create_a_penneo_job_status

Polls the Penneo queue to check the status of an asynchronous job (like case file creation or large document processing). This tool is critical for multi-step agent workflows where the LLM must wait for Penneo's backend to finish processing before proceeding to send signature requests.

"Take the job UUID from the case file creation step and check its status. If it's still pending, wait 10 seconds and check again. If it failed, give me the specific error message. If it succeeded, extract the final casefile ID."

list_all_penneo_forms

Retrieves the list of available Penneo Collect forms (templates) in the workspace. Useful for discovering the correct form ID before sending a KYC or onboarding request to a new client.

"List all active Penneo forms in the workspace. Find the one titled 'European Union KYC Onboarding v2' and return its internal ID and language configuration."

create_a_penneo_form_request

Generates a prefilled form request for a specific form. This allows you to programmatically distribute questionnaires or data collection forms with known data already populated, saving end-users time.

"Create a form request for the EU KYC Onboarding form. Prefill the 'Company Name' field with 'Acme Corp' and the 'Registration Number' with '12345678'. Send the request and confirm it was created."

list_all_penneo_casefile_answers

Extracts the submitted data from a completed case file form. The LLM uses this to ingest unstructured or highly nested form answers back into its context window for analysis or summary.

"Fetch the submission answers for casefile ID 98765. Extract the responses related to 'Beneficial Ownership' and format them into a markdown table for the compliance review team."

list_all_penneo_casefile_files

Lists the metadata for all files attached to a specific case file. Use this to verify that all required supporting documents (like passports or articles of incorporation) were successfully appended to the case.

"Check casefile ID 98765 and list all attached files. Verify that a document matching the description of 'Signed Articles of Incorporation' is present and note its creation timestamp."

For the complete inventory of available tools, query parameters, and schema definitions, view the Penneo integration page.

Workflows in Action

Exposing these tools to an LLM transforms Penneo from a static document repository into an active participant in your business logic. Here is how Claude orchestrates multi-step processes.

Workflow 1: Autonomous Case File Generation and Polling

Creating case files programmatically requires strict adherence to asynchronous processing rules. In this workflow, Claude acts as a legal operations assistant, drafting a document, sending it to Penneo, and managing the polling loop to ensure it was successfully processed.

"I need to onboard a new contractor, Sarah Connor (sarah.connor@sky.net). Generate a standard independent contractor agreement. Once generated, create a Penneo case file for it, poll the job status until it completes, and then verify the file was attached correctly."

1. Claude generates the text of the agreement internally based on its context.
2. Claude calls create_a_penneo_casefile, passing the required metadata, the document payload, and the signer details for Sarah Connor.
3. Truto executes the request and returns a job_uuid (e.g., 550e8400-e29b-41d4-a716-446655440000).
4. Claude calls create_a_penneo_job_status using the UUID. If the API returns a status of "processing", Claude's internal instructions dictate it must wait and try again.
5. Claude calls create_a_penneo_job_status again. The API returns "completed" along with the final casefile_id.
6. Claude calls list_all_penneo_casefile_files using the casefile_id to confirm the document metadata is present on the finalized case.
7. Claude reports back to the user: "The case file has been successfully generated and the document is attached. The casefile ID is 445566."

sequenceDiagram
    participant Claude as Claude
    participant TrutoMCP as Truto MCP Server
    participant PenneoAPI as Penneo API
    Claude->>TrutoMCP: Call create_a_penneo_casefile
    TrutoMCP->>PenneoAPI: POST /v3/casefiles
    PenneoAPI-->>TrutoMCP: 202 Accepted (Job UUID)
    TrutoMCP-->>Claude: Returns Job UUID
    loop Polling
        Claude->>TrutoMCP: Call create_a_penneo_job_status
        TrutoMCP->>PenneoAPI: GET /v3/jobs/{uuid}
        PenneoAPI-->>TrutoMCP: 200 OK (Status: Processing)
        TrutoMCP-->>Claude: Status Processing
    end
    Claude->>TrutoMCP: Call create_a_penneo_job_status
    TrutoMCP->>PenneoAPI: GET /v3/jobs/{uuid}
    PenneoAPI-->>TrutoMCP: 200 OK (Status: Completed, Case ID)
    TrutoMCP-->>Claude: Status Completed (Case ID)
    Claude->>TrutoMCP: Call list_all_penneo_casefile_files

Workflow 2: Automated KYC Data Extraction

Compliance teams spend hours manually reading submitted KYC forms to extract beneficial ownership data. By giving Claude access to Penneo Collect data, you can automate the extraction and summarization of dynamic form data.

"Review the recent KYC submission for casefile ID 10293. Extract the names of all ultimate beneficial owners (UBOs), their listed ownership percentages, and flag any missing required identification documents."

1. Claude calls list_all_penneo_casefile_answers with the provided casefile ID.
2. Truto queries Penneo and returns a highly nested JSON object containing the custom fields specific to the KYC form template.
3. Claude parses the raw JSON payload, navigating the nested arrays to find the UBO fields.
4. Claude extracts the names and ownership percentages.
5. Claude calls list_all_penneo_casefile_files to retrieve the metadata for attached identification documents.
6. Claude cross-references the list of required documents against the attached files.
7. Claude returns a structured markdown summary to the user, identifying the UBOs and noting that one passport file is missing.

Security and Access Control

Exposing an enterprise platform like Penneo to an AI agent requires strict security boundaries. Truto provides several configuration flags when generating the MCP server to restrict what the LLM can access.

• Method Filtering (config.methods): You can restrict the MCP server to specific operation types. For a reporting agent, setting methods: ["read"] ensures the LLM can only execute get and list operations, preventing it from accidentally creating or deleting case files.
• Tag Filtering (config.tags): Penneo endpoints can be grouped by functional tags. If you only want an agent to manage forms (and not touch case files or OAuth settings), you can filter the server to only expose tools tagged with forms.
• Double Authentication (require_api_token_auth): By default, possessing the MCP URL grants access to the tools. Setting this flag to true forces the MCP client to also pass a valid Truto API token in the Authorization header, adding a required secondary auth layer for high-security environments.
• Time-to-Live (expires_at): You can configure the MCP server to automatically destruct at a specific ISO datetime. The token is removed from the edge runtime and the database record is purged, ensuring temporary access for external contractors or short-lived agent sessions is safely revoked.

Architecting for Agentic Document Management

Connecting Penneo to Claude is not just about translating REST API calls into JSON-RPC. It is about bridging the gap between an LLM's predictive text generation and the rigid, asynchronous reality of enterprise document processing.

By utilizing a managed MCP server, you eliminate the need to write polling middleware, manage multipart boundary parsing, or constantly update JSON schemas as Penneo changes its API. You provide Claude with a normalized, securely bounded set of tools that allow it to interact with Penneo exactly as an operations team would - autonomously, accurately, and at scale.