Connect Firma to Claude: Manage Workspaces & Webhook Automations

If you need to connect Firma to Claude to automate e-signature dispatch, manage workspaces, or orchestrate embedded signing JWTs, you need a Model Context Protocol (MCP) server. This infrastructure layer acts as the translation layer between Claude's JSON-RPC tool calls and Firma's REST API endpoints. You can either build and maintain this integration layer from scratch, or you can use a managed platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Firma to ChatGPT or explore our broader architectural overview on connecting Firma to AI Agents.

Granting a Large Language Model (LLM) agent read and write access to a secure document management and e-signature platform is an engineering risk. You must handle token lifecycles, accurately map complex JSON schemas for document generation, and enforce strict state transition rules. Every time the underlying vendor updates an endpoint, you have to refactor your server code, update the tool definitions, and redeploy. This guide details exactly how to use Truto to generate a secure, managed MCP server for Firma, connect it natively to Claude Desktop, and execute complex e-signature workflows using natural language.

The Engineering Reality of the Firma API

A custom MCP server is a self-hosted translation layer. While the open MCP standard provides a predictable interface for LLMs to discover tools, implementing it against specific vendor APIs exposes all of their underlying architectural quirks. You are not just building a protocol translator - you are adopting the operational overhead of the target system.

If you decide to build a custom MCP server for Firma, you own the entire integration lifecycle. Here are the specific challenges you will face when mapping Firma endpoints to AI agent tools:

Mutually Exclusive Payload Constructs Firma strictly enforces payload structures based on the origin of the document. When creating a new signing request, the API requires either a base64-encoded PDF document or an existing template_id. Providing both throws a validation error. Similarly, partial updates to templates and signing requests strictly forbid updating document properties (like expiration hours or settings) and individual recipient data in the same HTTP PATCH call. If you expose these endpoints to Claude without highly constrained JSON schemas, the model will frequently attempt to batch these updates together, resulting in persistent 400 Bad Request errors. Truto's dynamically generated schemas explicitly map these constraints, guiding the model to separate its operations.

Embedded JWT Lifecycle Management Firma allows developers to embed signing request editors directly into their applications using JSON Web Tokens (JWTs). The API provides specific endpoints to generate these tokens, which have strict, non-configurable expiration windows (24 hours for template tokens, 7 days for signing requests). If an AI agent provisions a token but fails to revoke it after a workflow is aborted, you leak active editing sessions. Your custom server must track these state transitions or rely entirely on the LLM to remember to call the revocation endpoints.

Strict State Transition Logic You cannot update or cancel a signing request in Firma after it has been sent, completed, or cancelled. Models lack inherent awareness of these state machines. If a user prompts Claude to "add a new recipient to the NDA and resend it," but the document is already in a sent status, the operation will fail. A reliable MCP integration must provide the model with status-check tools and the context needed to fork the document rather than attempting an illegal mutation.

Rate Limits and Webhook Constraints Firma imposes standard API rate limits across its resources, with exceptionally tight restrictions on security operations. For instance, rotating a webhook secret is hard-capped at one request per hour and invokes a 7-day grace period where both the old and new secrets remain valid.

A factual note on rate limits: Truto does not retry, throttle, or apply backoff logic on rate limit errors. When the Firma 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 HTTP headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The MCP client is entirely responsible for detecting the 429 and implementing appropriate retry and exponential backoff mechanisms.

Generating the Firma MCP Server

Truto eliminates the need to manually code JSON-RPC handlers or build JSON schemas. The platform dynamically generates MCP tools based on the integration's resource definitions and underlying API documentation. If an endpoint is documented, it becomes an available tool automatically.

You can generate the MCP server URL through the Truto user interface or programmatically via the API.

Method 1: Via the Truto UI

For administrators setting up individual environments, the visual interface provides a rapid configuration path.

1. Navigate to the integrated account page for your Firma connection in the Truto dashboard.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can apply method filters (e.g., restricting the server to only read operations) or tag filters to limit the scope of available tools.
5. Copy the generated MCP server URL. This URL contains the cryptographic token required to route JSON-RPC requests to the correct tenant.

Method 2: Via the Truto API

For teams embedding AI capabilities programmatically, you can provision MCP servers on the fly via the Truto API. This is critical for generating short-lived, highly scoped tools for specific automated workflows.

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

curl -X POST https://api.truto.one/integrated-account/<FIRMA_INTEGRATED_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer <TRUTO_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Firma Ops Assistant",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The API returns a payload containing the secure URL:

{
  "id": "mcp_abc123",
  "name": "Firma Ops Assistant",
  "config": { "methods": ["read", "write", "custom"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to Claude

Once you have the Truto MCP server URL, you must connect it to your Claude environment. All communication happens over HTTP POST utilizing JSON-RPC 2.0 messages.

Method 1: Via the Claude UI

If you are using Claude Desktop or the web interface with Custom Connector capabilities:

1. Open Claude and navigate to Settings.
2. Select Integrations (or Connectors depending on your plan tier).
3. Click Add MCP Server.
4. Paste the URL provided by Truto and save.

Claude will immediately execute an initialize handshake, request the tools/list, and populate the agent's context with the available Firma capabilities.

Method 2: Via Configuration File

For programmatic deployments or customized Claude Desktop setups, you can define the server in your claude_desktop_config.json file. Because Truto provides an HTTP endpoint, you must use the Server-Sent Events (SSE) transport wrapper provided by the official MCP SDK.

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

Restart Claude Desktop after updating this file. The model will automatically read the configuration and establish the connection to the Truto router.

graph TD
    A["Claude Agent<br>(MCP Client)"] -->|"JSON-RPC over HTTP"| B["Truto MCP Router<br>(/mcp/:token)"]
    B -->|"Token Validation<br>Schema Extraction"| C["Truto Proxy API Layer"]
    C -->|"Authenticated REST Calls"| D["Firma API"]

Available Firma Hero Tools

When Claude connects to the server, Truto dynamically exposes Firma operations based on the platform's API documentation. The arguments provided by Claude arrive as a single flat object, which the Truto router intelligently splits into query parameters and body payloads based on the generated schemas.

Here are 6 high-leverage hero tools your AI agent can utilize.

list_all_firma_workspaces

Retrieves all workspaces for the authenticated Firma company. This tool is critical for operations that require a workspace_id before provisioning new templates or configuring webhooks. It supports filtering by name, protected status, and creation date.

"Fetch a list of all non-protected workspaces created in Firma over the last 30 days. Format the response as a markdown table showing the workspace name and creation date."

create_a_firma_signing_request

Creates a new signing request. The model must supply either a base64-encoded PDF document or a template_id. If passing a document directly, the allow_editing_before_sending flag is automatically configured.

"Create a new signing request in Firma using template ID tmp_98765. Set the expiration to 48 hours and add a description noting that this is a standard vendor NDA."

firma_signing_requests_partial_update

Partially updates an existing signing request via an HTTP PATCH operation. Due to Firma's payload rules, Claude must use this tool to update document metadata (like expiration hours) separately from adding or updating recipient definitions.

"Update the signing request sig_12345. Change the description to 'Updated Terms of Service' and adjust the expiration window to 72 hours. Do not modify the recipients in this step."

list_all_firma_signing_request_fields

Retrieves the comprehensive list of fields configured for a specific signing request, including their completion status and active values. This allows the AI agent to audit document progress without downloading the raw PDF.

"Audit the fields for signing request sig_12345. Return a list of all required fields that have not yet been completed, and identify which recipient they are assigned to."

create_a_firma_webhooks_rotate_secret

Triggers a rotation of the webhook signing secret for the company. This tool generates a new secret while keeping the old one active for a 7-day migration window. Be aware this is hard-limited to one execution per hour by the upstream API.

"Rotate the webhook signing secret for our Firma account. Provide me with the new secret and confirm the exact timestamp when the legacy secret will expire."

create_a_firma_jwt_generate_signing_request

Generates a specialized JSON Web Token designed specifically for embedding a Firma signing request editor into a host application. This token grants access to the editing interface and automatically expires after 7 days.

"Generate an embedded signing request JWT for document sig_99999. Output the raw token string so I can inject it into our frontend development testing suite."

For the complete inventory of available tools, required fields, and schema definitions, review the Firma integration page.

Workflows in Action

Connecting Claude to Firma transforms static API documentation into an active, conversational interface. Below are concrete examples of how distinct technical personas can orchestrate complex operations.

Scenario 1: Automated E-Signature Dispatch

Persona: Sales Operations Manager

"I need to send an NDA to a new vendor. Create a signing request using the standard NDA template. Once created, add 'vendor@example.com' as the primary signer, and then immediately dispatch the request."

Execution Steps:

1. Claude calls create_a_firma_signing_request, passing the known template_id for the standard NDA. Firma returns the newly generated signing_request_id in a draft status.
2. Claude executes firma_signing_requests_partial_update, passing the signing_request_id and injecting the new recipient ('vendor@example.com') into the user array.
3. Claude calls firma_signing_requests_send, executing the dispatch operation and moving the document state from draft to sent.

Result: The user receives confirmation that the signing request has been compiled, the recipient attached, and the email dispatched by the Firma delivery system.

Scenario 2: Webhook Secret Migration

Persona: DevSecOps Engineer

"Check the status of our webhook secrets in Firma. If a secret exists and hasn't been rotated in the last 90 days, trigger a rotation and give me the new key payload."

Execution Steps:

1. Claude calls list_all_firma_webhooks_secret_status to evaluate the current security posture. It checks the last_rotated_at timestamp.
2. Recognizing the delta exceeds 90 days, Claude executes create_a_firma_webhooks_rotate_secret.
3. The Truto proxy passes the request, and Firma returns the new_secret alongside the old_secret_expires_at timestamp.

Result: The engineer receives the newly generated cryptographic secret along with the exact date they must finish migrating the application servers before the legacy secret is invalidated.

sequenceDiagram
    participant Dev as DevSecOps Prompt
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Firma as Firma API
    Dev->>Claude: "Rotate webhook secrets if older than 90 days"
    Claude->>MCP: Call list_all_firma_webhooks_secret_status
    MCP->>Firma: GET /webhooks/secret/status
    Firma-->>MCP: Return last_rotated_at
    MCP-->>Claude: JSON-RPC Result
    Claude->>MCP: Call create_a_firma_webhooks_rotate_secret
    MCP->>Firma: POST /webhooks/secret/rotate
    Firma-->>MCP: Return new secret & 7-day grace expiry
    MCP-->>Claude: JSON-RPC Result
    Claude-->>Dev: Present new secret

Scenario 3: Embedded Editor Provisioning

Persona: Product Engineer

"I am testing the embedded UI. Create a new dummy workspace in Firma, generate a test signing request inside it using the placeholder document, and issue an embedded JWT for the editor."

Execution Steps:

1. Claude calls create_a_firma_workspace with the name "Frontend Test Sandbox". Firma returns the workspace_id.
2. Claude executes create_a_firma_signing_request, passing a base64 string for the document payload.
3. With the new document ID, Claude calls create_a_firma_jwt_generate_signing_request to provision the scoped access token.

Result: The engineer is provided with the raw JWT required to bootstrap the frontend component, without having to manually execute a chain of cURL requests or interact with the Firma dashboard.

Security and Access Control

Deploying an MCP server that interacts with secure document platforms requires strict governance. Truto implements multiple control layers to secure your Firma instance.

• Method Filtering: You can enforce read-only access by passing methods: ["read"] during server creation. This prevents the agent from executing tools that modify data, create documents, or send emails.
• Tag Filtering: Restrict the server to specific operational domains. By specifying tags: ["webhooks"], the agent will only have access to infrastructure operations, masking all document and template tools.
• Secondary Authentication: Enabling require_api_token_auth: true on the MCP configuration requires the client to pass a valid Truto API token in the Authorization header. URL possession alone becomes insufficient to execute tools.
• Automatic Expiration: You can provision temporary access for contractors or automated tests by setting an expires_at ISO datetime. Once this threshold is crossed, Truto's underlying distributed key-value store automatically purges the routing token.

Moving Forward

Building custom tool handlers for the Firma API introduces maintenance burdens that scale poorly as your AI initiatives grow. Mutually exclusive payload validation, token lifecycle management, and rate limit normalization consume engineering cycles better spent on application logic. By utilizing Truto's dynamically generated MCP servers, you can connect Claude directly to Firma in minutes, providing your agents with robust, schema-validated tools backed by a managed infrastructure layer.