clio-api-patterns

name	Clio API Patterns
description	Use this skill when working with the Clio Manage MCP tools — OAuth 2.0 Authorization Code connection via Conduit, the matters-as-hub data model, decision-tree tool navigation, pagination, and the deliberate v1 scope limits (no delete anywhere, documents metadata-only, communications/ calendar/bills read-only). Essential background before touching any other Clio skill.
when_to_use	When connecting to Clio, navigating its MCP tools, or explaining why a Clio operation isn't available. Use when: clio api, clio auth, clio oauth, clio connection, clio region, clio navigate, clio pagination, clio scope, clio permissions, clio read-only, or clio mcp.

Clio API Patterns

Overview

Clio Manage is legal practice management software: matters (case/client files), the people and companies involved in them, time and expense tracking, tasks, documents, calendar, and billing. This is the first legal vertical in this marketplace — every other plugin here is MSP/IT tooling, so nothing about Clio's data model, compliance posture, or connection flow should be assumed to look like a PSA or RMM.

The Clio MCP server exposes tools under clio_{entity}_{operation} (clio_matters_list, clio_activities_create, etc.), fronted by Conduit — no local SDK, proxy, or API key on your machine.

Connection & Authentication

Clio uses OAuth 2.0 Authorization Code flow, not an API key. You never paste a key or secret anywhere:

1. Go to https://conduit.wyre.ai/connect/clio
2. Sign in to Clio and approve the requested scopes
3. Optionally set Clio Region (see below)
4. Conduit stores the resulting OAuth tokens and refreshes them automatically; your MCP client only ever authenticates to Conduit itself

Your MCP client's connection to Conduit (https://conduit.wyre.ai/v1/clio/mcp) is a separate OAuth relationship from Conduit's connection to Clio — you sign in once to Conduit (client-to-gateway), and once to Clio (gateway-to- vendor, via the connect page above). If a tool call fails with an auth error, the fix is almost always in Conduit's connect page, not the MCP client config.

Clio Region

Clio runs separate regional deployments (US, CA, EU, AU; default US). The Clio Region field on the connect page selects which regional API host Conduit talks to.

Known v1 limitation: the region field only changes which regional API host is used — it does not currently guarantee the OAuth Authorization Code flow completes correctly for CA/EU/AU accounts. This is unverified for non-US regions as of this writing; if you're on a non-US Clio instance and the connect flow fails or behaves oddly, that's the known gap, not user error. Don't paper over it — flag it back to the org so it gets tracked against the real limitation instead of re-tried indefinitely.

Tool Navigation

Clio's tools sit behind decision-tree navigation — this is deliberate, not a bug, and it's how the server keeps a large tool surface manageable:

• clio_navigate — move into a domain (matters, contacts, activities, communications, tasks, documents, calendar-entries, bills)
• clio_status — see which domain you're in and what's available from here
• clio_back — return to the top-level navigation state

You cannot call a domain tool (e.g. clio_matters_create) until you've navigated into that domain. If a tool appears to be "missing," check clio_status first — it's very likely just not in scope from the current navigation state.

The Matters-as-Hub Data Model

Matters are the hub. Almost every other object references a matter_id:

• Activities (time/expense entries) are logged against a matter
• Tasks are typically scoped to a matter
• Communications (logged emails/calls/notes) are attached to a matter
• Documents are filed under a matter
• Calendar entries commonly reference a matter
• Bills are generated from a matter's unbilled activities

Contacts are the exception — a contact (person or company) exists independently and can be linked to many matters in different roles (client, opposing party, witness, etc. — see the contacts skill).

Practically: when a user asks "what's going on with Acme's case," resolve the matter first (clio_matters_list / clio_matters_get), then pull whatever domain data you need scoped to that matter_id. See matter-summary for the reference pattern that pulls contacts, tasks, activities, communications, and bills for one matter.

Pagination

List tools (clio_matters_list, clio_contacts_list, clio_activities_list, etc.) accept a limit and return a paging cursor for the next page. Practical guidance:

• Request a reasonable limit (don't default to the max if the user only asked for "a few")
• Check the response for a next-page cursor/token; if present, there are more results than what you're holding — don't report a list as complete just because the first page looked short
• Prefer server-side filters (status, client, date range, matter_id) over pulling everything and filtering client-side — Clio accounts can have years of matters and activities behind them

If a specific tool's exact pagination field names aren't obvious from context, check that tool's input/output schema directly rather than guessing — don't invent parameter names.

Deliberate v1 Scope Limits — Read This Before Assuming Something Is a Bug

Clio holds privileged attorney-client data. The v1 tool surface is conservative by design, not an oversight, and every limitation below exists for a specific reason:

Limitation	Scope	Why
No delete tool on any entity	All domains	Legal records (time entries, matter history, communications) are frequently subject to retention obligations, malpractice-insurance requirements, or discovery. There is no clio_*_delete tool anywhere in this server — full stop. Deletion, when truly needed, happens in Clio directly, by a human, with Clio's own audit trail.
Documents are read-only and metadata-only	documents	clio_documents_list/clio_documents_get return metadata (name, matter, created date, etc.) — never file content. There is no download or upload tool. Document contents are frequently privileged, client-confidential, or subject to matter-specific access restrictions that this integration has no way to evaluate — so it doesn't try.
Communications are read-only	communications	Logged emails/calls/notes on a matter are often the most sensitive record in the file (privileged attorney-client communication). List/get only — no create, update, or delete.
Calendar entries are read-only	calendar-entries	Same reasoning as communications — court dates, deadlines, and appointment details are read for context, never written by the integration.
Bills are read-only	bills	Billing and trust-accounting mutations require rigor (trust accounting rules, IOLTA compliance) that is explicitly out of scope for v1. You can read bill status and amounts; you cannot generate, edit, or void a bill through this integration.
Activities have no update/delete	activities	Time and expense entries can be created (clio_activities_create) but not modified or removed through the integration — corrections happen in Clio directly, preserving Clio's own edit history.

When a user asks for something in one of these categories, don't work around the limitation (e.g. by trying to fabricate a workaround through an unrelated tool) — say plainly what the tool surface does and doesn't do, and point them to Clio directly for the write operation.

Related Skills

• Clio Matters — the core case/client-file object
• Clio Contacts — people and companies
• Clio Time & Billing — activities (time/expense) and read-only bills