clio-mcp

MCP (Model Context Protocol) server for Clio Manage -- matters, contacts, activities, communications, tasks, documents, calendar entries, and bills. Built on @wyre-technology/node-clio.

Compliance note. This server proxies access to attorney-client privileged data (matters, communications, documents). It does not log or persist any request or response content anywhere -- the structured stderr logger (src/utils/logger.ts) only ever emits level, timestamp, and a small context object such as a tool name or an error message, never tool arguments or result bodies. Document tools (clio_documents_list / clio_documents_get) return metadata only -- name, filename, size, content type, parent folder, associated matter/contact -- and never document content; the underlying SDK has no download/upload capability.

Install

npm install
npm run build

Requires Node.js >= 20. This package depends on @wyre-technology/node-clio, published to GitHub Packages -- see .npmrc (registry + token) if installing outside CI.

Running

npm run start        # stdio transport, reads CLIO_* env vars
npm run start:http    # HTTP streaming transport (gateway mode), reads X-Clio-* headers per request

Credentials

Clio is OAuth-only -- there is no static API key. This server never performs the OAuth authorize/token dance itself; something upstream (the WYRE MCP gateway, or your own OAuth client) does that and hands this server a bearer access token.

Gateway mode (AUTH_MODE=gateway, MCP_TRANSPORT=http -- the Docker image's default): credentials are read from request headers, per request:

A request with no X-Clio-Access-Token header is not rejected outright -- initialize and tools/list still work (so the gateway can discover tools before a user has connected), but any tools/call will fail with a clear "No Clio credentials configured" error.

stdio mode (local/CLI use, a single set of credentials for the whole process): set environment variables instead:

export CLIO_ACCESS_TOKEN=...
export CLIO_REFRESH_TOKEN=...   # optional
export CLIO_CLIENT_ID=...       # optional, required alongside a refresh token
export CLIO_CLIENT_SECRET=...   # optional, required alongside a refresh token
export CLIO_REGION=us           # optional, defaults to us

Clio runs four separate regional deployments (us/ca/eu/au) -- a token minted for one region is not valid against another, and a Clio developer app registration is itself region-specific. Get an access token via the Clio OAuth flow for the region you need; @wyre-technology/node-clio exports buildAuthorizationUrl / exchangeAuthorizationCode helpers for that.

Tool navigation

This server uses decision-tree navigation instead of exposing all tools flat. Initially only two tools are visible:

• clio_navigate -- switch into one of the eight domains below; the domain's tools (plus clio_back) then appear in the next tools/list.
• clio_status -- check credential/connection status and see the list of domains.

Once inside a domain, clio_back returns to the navigation menu.

Tool reference

Every tool is named clio_{entity}_{operation}. Read-only tools (_list/_get) never mutate Clio data and are marked readOnlyHint: true. Tools that create or update records are marked readOnlyHint: false. No tool in this server is destructive/irreversible -- the underlying SDK has no delete() on any resource, so there is nothing to warn about at that tier.

Every _list tool called with no filters at all will ask (via MCP elicitation) for a search term, date range, or similar before running what would otherwise be an unbounded query across the whole account. If the client doesn't support elicitation, or the user doesn't answer, the tool proceeds unfiltered anyway -- elicitation is purely additive and never blocks the call.

matters

contacts

activities

Time entries and expense entries logged against matters.

There is no clio_activities_update -- the SDK has no activities.update().

communications (read-only)

Logged emails and phone calls. Read-only in the underlying SDK -- there is no create/update/delete, by design, since this data routinely contains privileged attorney-client content.

tasks

documents (read-only, metadata only)

Metadata only -- does not return document content. The underlying SDK deliberately does not implement document upload/download; documents are the highest-sensitivity object in a legal practice-management system and content transfer is out of scope pending its own dedicated review.

calendar-entries (read-only)

bills (read-only)

Invoices. Billing/trust-accounting mutations touch regulated funds-handling workflows and are out of scope for the underlying SDK.

Architecture

src/
├── index.ts          # Entry point -- picks stdio or HTTP transport
├── server.ts          # Server setup, decision-tree tool routing
├── http.ts            # HTTP streaming transport (gateway mode)
├── utils/
│   ├── client.ts       # Credential parsing + ClioClient cache/invalidation
│   ├── logger.ts        # Structured stderr-only logger
│   ├── server-ref.ts     # Shared Server reference for elicitation
│   ├── elicitation.ts     # elicitText / elicitSelection / elicitConfirmation
│   └── types.ts           # DomainHandler interface, shared result helpers
├── domains/            # One file per Clio SDK resource
│   ├── index.ts          # Lazy-loaded domain registry
│   ├── navigation.ts      # clio_navigate / clio_status / clio_back
│   ├── matters.ts
│   ├── contacts.ts
│   ├── activities.ts
│   ├── communications.ts
│   ├── tasks.ts
│   ├── documents.ts
│   ├── calendar-entries.ts
│   └── bills.ts
└── __tests__/

Every HTTP request gets a fresh Server + StreamableHTTPServerTransport pair (stateless, no session ID) -- the gateway sends separate requests for initialize, tools/list, and tools/call, and a shared server would reject the second initialize. Per-request tenant credentials are carried in an AsyncLocalStorage context opened for the duration of that one request, so two concurrent requests bearing different tenants' tokens can never see each other's credentials.

Testing

npm test

Tests mock the @wyre-technology/node-clio client and the MCP server's elicitInput -- no live Clio credentials are needed. Coverage: every domain's tool-definition shape (valid inputSchema, correct readOnlyHint per read vs. mutate), credential header parsing and client cache invalidation, and handler routing/elicitation behavior for representative tools in each domain.

License

Apache-2.0. See LICENSE.