Skip to content

Connect Docketwise to ChatGPT: Manage Legal Cases and Documents

Learn how to connect Docketwise to ChatGPT using a managed MCP server. Automate legal matter creation, client intake, document uploads, and invoicing.

Yuvraj Muley Yuvraj Muley · · 9 min read
Connect Docketwise to ChatGPT: Manage Legal Cases and Documents

If you want to connect Docketwise to ChatGPT so your AI agents can automate client intake, track immigration matters, upload legal documents, and generate invoices, you need a Model Context Protocol (MCP) server. This server acts as a standardized translation layer between ChatGPT's JSON-RPC tool calls and the Docketwise REST API.

If your team uses Claude, check out our guide on connecting Docketwise to Claude or explore our broader architectural overview on connecting Docketwise to AI Agents.

Giving a Large Language Model (LLM) read and write access to a specialized legal practice management system is a significant engineering challenge. You must handle strictly nested data payloads, one-hour expiring document URLs, and base64 file encodings. Every time you want to expose a new endpoint, a custom MCP server requires manual schema writing, redeployment, and testing.

This guide breaks down exactly how to use Truto to generate a secure, authenticated MCP server for Docketwise, connect it natively to ChatGPT, and execute complex law firm workflows using natural language.

The Engineering Reality of the Docketwise API

Building a custom MCP server means owning the entire API integration lifecycle. While the open MCP standard provides a predictable way for ChatGPT to discover tools, implementing it against the Docketwise API introduces several domain-specific quirks that break standard CRUD assumptions.

Here are the specific challenges you face when building an AI integration for Docketwise:

Nested Payload Root Keys

Unlike modern REST APIs that accept flat JSON bodies, Docketwise strictly requires nested root keys for resource creation and updates. When creating a contact, you cannot simply send {"first_name": "John"}. The API requires {"contact": {"first_name": "John"}}. Furthermore, sub-attributes like addresses_attributes or phone_numbers_attributes require a nested data key for each item. An LLM natively struggles with these highly specific nesting rules unless your MCP tool schemas explicitly enforce the root key structure.

Base64 Document Handling and Ephemeral URLs

The document lifecycle in Docketwise is not a simple file push. To upload a document, the API requires strict base64 encoding sent as a string within the base64_data field, alongside the explicit filename (including extension). When downloading, the API does not return the file directly; it returns a public download URL that is only valid for exactly 1 hour. Your agentic workflows must be designed to fetch and utilize this URL immediately before it expires.

Mandatory Relational Cross-Referencing

Legal matters do not exist in a vacuum, and the API enforces this at the endpoint level. If you update an existing invoice, you must include the contact_id in the payload - even if you are only changing the amount. Similarly, updating a matter requires the client_id. If you are attaching a note, the endpoint expects either a matter_id or client_id in the query, but the body itself is bare (no root key). Your MCP server must inject these relational requirements into the tool schemas so ChatGPT knows exactly which IDs to fetch first.

Pagination and Rate Limits

Docketwise handles pagination via the X-Pagination HTTP header, returning up to 200 records per page. Your MCP server must extract this header to provide next_cursor logic to the LLM.

Regarding rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Docketwise 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 headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) following the IETF specification. The caller (your agent or application) is strictly responsible for implementing its own retry and backoff logic based on these headers.

Creating the Docketwise MCP Server

Truto automatically generates MCP tools dynamically from the underlying Docketwise API documentation and resource schemas. You can generate a dedicated MCP server for a specific law firm's account using either the Truto UI or the REST API.

Method 1: Via the Truto UI

If you prefer a visual setup, you can generate the server directly from the dashboard:

  1. Log into Truto and navigate to the Integrated Accounts page.
  2. Select the specific Docketwise connected account.
  3. Click the MCP Servers tab.
  4. Click Create MCP Server.
  5. Configure your server settings (assign a name, filter by methods like read or write, or filter by tags like matters or invoices).
  6. Click Save and copy the generated MCP server URL. It will look like https://api.truto.one/mcp/a1b2c3d4....

Method 2: Via the Truto API

For automated deployments or multi-tenant agent architectures, you can provision MCP servers programmatically. Make an authenticated POST request to the /integrated-account/:id/mcp endpoint.

curl -X POST https://api.truto.one/integrated-account/<INTEGRATED_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docketwise ChatGPT Server",
    "config": {
      "methods": ["read", "write"],
      "tags": ["matters", "contacts", "invoices"]
    }
  }'

API Response:

{
  "id": "mcp-7a8b9c",
  "name": "Docketwise ChatGPT Server",
  "config": {
    "methods": ["read", "write"],
    "tags": ["matters", "contacts", "invoices"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

This URL contains a cryptographic token securely tied to the specific Docketwise tenant. Keep this URL secure, as it handles both routing and authentication for the tool session.

Connecting the MCP Server to ChatGPT

Once you have your Truto MCP server URL, you must register it with your ChatGPT environment. You can do this via the ChatGPT UI or a local configuration file if you are running custom local agent clients.

Method A: Via the ChatGPT UI

ChatGPT supports custom MCP connectors for Pro, Plus, Business, Enterprise, and Education accounts.

  1. Open ChatGPT and navigate to Settings.
  2. Click on Apps and go to Advanced settings.
  3. Toggle on Developer mode (MCP features are located here).
  4. Under MCP servers / Custom connectors, click Add new server.
  5. Enter a recognizable name (e.g., "Docketwise via Truto").
  6. Paste your generated Truto MCP url into the Server URL field.
  7. Click Save.

ChatGPT will perform the JSON-RPC initialization handshake, discover the available Docketwise tools, and make them available to your current chat session.

Method B: Via Manual Config File

If you are using a local agent framework, Cursor, or Claude Desktop, you can connect using a standard JSON configuration file utilizing the Server-Sent Events (SSE) transport approach.

Add the following to your mcp_config.json:

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

Restart your agent framework, and it will automatically list and map the available Docketwise endpoints.

Security and Access Control

Exposing an entire law firm's database to an LLM is a massive security risk without proper boundaries. Truto provides four distinct configuration levers to lock down your Docketwise MCP server:

  • Method Filtering: Restrict the agent to specific HTTP actions. By passing methods: ["read"] during server creation, ChatGPT can only execute get or list operations, physically preventing it from deleting matters or altering invoices.
  • Tag Filtering: Group tools by functional area. Passing tags: ["invoices"] limits the server to only billing endpoints, keeping the agent away from sensitive case notes or contact directories.
  • Require API Token Auth: By setting require_api_token_auth: true, the URL token alone is no longer enough to execute a tool. The MCP client must also pass a valid Truto API token in the Authorization header, enforcing a double-layer middleware check.
  • Time-to-Live (TTL): Pass an ISO datetime to expires_at to create a temporary server. Cloudflare KV and durable alarms will automatically purge the credentials and invalidate the URL the moment the timestamp is reached.

Docketwise Hero Tools for AI Agents

Truto dynamically generates schemas for the entire Docketwise API surface. Rather than overwhelming your LLM with every endpoint, here are 6 high-leverage "hero tools" specifically curated for legal AI workflows.

list_all_docketwise_matters

Fetches a paginated list of the firm's legal matters. The agent can parse this to find case IDs, current statuses, and assigned clients. The tool supports the X-Pagination header, translating it into a next_cursor the LLM can use to page through large case lists.

"Get me a list of all active immigration matters in the system. If there are more than 200, please paginate to the next set."

create_a_docketwise_contact

Creates a new person or institution in the CRM. The schema strictly enforces the {"contact": {...}} root key wrapper. The agent must format addresses as lists containing a data key object.

"Create a new contact for Maria Garcia. Her phone number is 555-0199 and her email is maria@example.com."

create_a_docketwise_matter

Opens a new case. The LLM must supply the client_id (usually fetched via the contacts list first) and nest the payload under {"matter": {...}}.

"Open a new H-1B Visa matter for Maria Garcia. Assign it to our corporate immigration queue."

create_a_docketwise_note

Attaches a note to an existing matter or contact. This tool is unique because it requires either a matter_id or client_id in the query, but takes a bare body payload without a root wrapper.

"Add a note to Maria Garcia's H-1B matter stating that we are waiting on her university transcripts."

get_single_docketwise_document_download_url_by_id

Retrieves a secure, temporary URL to download a file. The LLM receives {"url": "..."} which is strictly valid for only 1 hour.

"Get the download URL for document ID 88472 and extract the summary text from the provided link."

create_a_docketwise_invoice

Generates a new invoice. The tool schema enforces the requirement that invoice.contact_id must be provided, ensuring the invoice is properly tied to a billed entity.

"Generate a new invoice for $1,500 for the initial consultation with Maria Garcia. Set the due date to next Friday."

To see the complete inventory of available endpoints, request schemas, and pagination mechanics, review the Docketwise integration page.

Workflows in Action

Individual tools are useful, but MCP servers unlock their true power when ChatGPT orchestrates multi-step workflows. Here are two concrete examples of how an AI agent interacts with the Docketwise API to solve real legal operations tasks.

Scenario 1: Automated Client Intake and Matter Initialization

The Prompt:

"We just signed a new client named David Chen (david.c@example.com). Create a contact record for him, open a new 'L-1A Transfer' matter under his profile, and add a note to the matter indicating that the initial retainer has been requested."

How the Agent Executes It:

sequenceDiagram
  autonumber
  participant User as User
  participant ChatGPT as ChatGPT
  participant Truto as Truto MCP Server
  participant Upstream as "Docketwise API"

  User->>ChatGPT: "Create contact, open matter, add note..."
  
  ChatGPT->>Truto: Call create_a_docketwise_contact<br>{"contact": {"first_name": "David", "last_name": "Chen", "email": "david.c@example.com"}}
  Truto->>Upstream: POST /api/v1/contacts
  Upstream-->>Truto: 201 Created (id: 40992)
  Truto-->>ChatGPT: Returns Contact ID 40992

  ChatGPT->>Truto: Call create_a_docketwise_matter<br>{"matter": {"title": "L-1A Transfer", "client_id": 40992}}
  Truto->>Upstream: POST /api/v1/matters
  Upstream-->>Truto: 201 Created (id: 71004)
  Truto-->>ChatGPT: Returns Matter ID 71004

  ChatGPT->>Truto: Call create_a_docketwise_note<br>{"matter_id": 71004, "content": "Initial retainer requested."}
  Truto->>Upstream: POST /api/v1/notes
  Upstream-->>Truto: 201 Created
  Truto-->>ChatGPT: Success confirmation

  ChatGPT-->>User: "David Chen is in the system. Matter created (ID: 71004) and note attached."

Explanation: ChatGPT understands the relational dependency. It knows it cannot create a matter without a client_id, so it executes create_a_docketwise_contact first. It parses the ID from the response, injects it into create_a_docketwise_matter, and finally uses the resulting matter ID to attach the note.

Scenario 2: Document Processing and Invoice Generation

The Prompt:

"Upload this PDF as 'visa_application.pdf' to matter ID 71004. Once uploaded, generate a $500 invoice for the filing fee assigned to the client associated with that matter."

How the Agent Executes It:

flowchart TD
  A["Parse user<br>prompt & file"] --> B["Encode PDF to<br>strict base64"]
  B --> C["Call create_a_docketwise_document<br>(matter_id: 71004, filename: visa_application.pdf)"]
  C --> D["Call get_single_docketwise_matter_by_id<br>(id: 71004)"]
  D --> E["Extract client_id<br>from matter response"]
  E --> F["Call create_a_docketwise_invoice<br>(contact_id: extracted_id, amount: 500)"]
  F --> G["Return success<br>to user"]

Explanation: The agent must fulfill Docketwise's strict file upload requirements. It encodes the file to base64, packages it under the document root key, and uploads it. Next, because creating an invoice requires a contact_id (not a matter_id), the agent explicitly calls get_single_docketwise_matter_by_id to look up which client owns matter 71004. Once it has the client ID, it successfully posts the $500 invoice payload.

Connecting an LLM to a highly structured system like Docketwise requires more than just knowing the endpoints. You must parse documentation into JSON Schema, enforce nested root keys, handle ephemeral document URLs, and standardize HTTP 429 rate limit errors for agent backoff logic.

Building this custom MCP server from scratch is a massive distraction for your engineering team. Truto solves this by dynamically deriving precise, AI-ready tools from existing integration definitions. You get a production-ready, highly filtered, and secure MCP server url in one API call.

FAQ

How does the Docketwise MCP server handle document uploads?
The MCP tool requires the document to be strictly base64 encoded and passed within a `base64_data` field, nested under a `document` root key, alongside the explicit filename.
Does Truto automatically retry Docketwise API rate limits?
No. Truto passes HTTP 429 errors directly back to the caller and standardizes the upstream rate limit data into standard `ratelimit-*` headers. The calling agent must handle its own retry and backoff logic.
Can I prevent ChatGPT from deleting matters in Docketwise?
Yes. When provisioning the MCP server, you can apply a method filter (e.g., `methods: ["read"]` or `methods: ["read", "write"]` excluding deletes) to strictly limit the available tools.
How does the agent handle pagination for large contact lists?
Docketwise uses the `X-Pagination` header. Truto translates this data into a standardized `next_cursor` property in the tool schema, allowing ChatGPT to paginate through batches of 200 records.

More from our Blog