# Clio MCP Server

An [MCP](https://modelcontextprotocol.io) server for the [Clio Manage](https://www.clio.com)
API (v4), the practice-management platform used by law firms. It lets an AI agent read a
firm's matters, contacts, time and expense entries, tasks, logged communications, document
metadata, calendar entries and bills, and, on explicit request, create or update matters,
contacts, tasks and time / expense entries.

- Transport: MCP Streamable HTTP at `POST /mcp`, health probe at `GET /health`
- Stateless and multi-tenant: credentials arrive on every request as HTTP headers and are
  never stored; every tool is listed from the first `tools/list`
- Python 3.12, [uv](https://docs.astral.sh/uv/), FastMCP, httpx
- License: Apache-2.0, Copyright 2026 MSPbots.ai

<div align="center">

## MSPbots Connector

**The MCP Gateway built for MSPs: visible, controlled, and your data stays where it belongs.**

[**Get started at connect.mspbots.ai →**](https://connect.mspbots.ai)

</div>

---

MSPbots Connector gives your AI clients one MCP URL to reach your entire MSP stack (RMM, PSA, documentation, security, finance), and gives you control over who can call which tool and a record of everything that was called.

**Hosted service: [connect.mspbots.ai](https://connect.mspbots.ai)** · Free to use.

### Why Connector

![MSPbots Connector](https://stgoss.mspbots.ai/files/mcp/mspbots-mcp.png)

| | |
|---|---|
| **Visible** | Every tool call is logged: who, which vendor, when. Usage dashboard, CSV export, SIEM streaming. |
| **Controlled** | Role-based, per-tool allowlist. Deny by default. |
| **Protected** | Credentials encrypted per record. AI clients never see your vendor passwords or tokens. |
| **MSP-native** | Built for the MSP stack only: RMM, PSA, documentation, security, finance. |

### Quick start

1. **Sign up** at [connect.mspbots.ai](https://connect.mspbots.ai).
2. **Connect your vendors.** Pick from 150+ connectors and authorize each one on the vendor's own page, or bring your own API keys. No extra vendor accounts needed.
3. **Set access.** Create roles and decide which tools each role may call. Nothing is allowed until you allow it.
4. **Add your MCP URL to your AI client.** Copy the URL from your Connector dashboard into Claude, ChatGPT, Cursor, VS Code, Gemini, Codex, or any MCP-capable client.
5. **Ask your AI to do real work**, and watch every call appear in the audit log.

### Features

**Unified gateway**
- One MCP URL for all your AI clients
- 150+ connectors across the MSP stack
- Custom MCP servers supported, free
- Authorization happens on each vendor's own page; the AI never sees passwords or tokens
- Bring your own credentials: use the vendor API keys you already have
- Multiple accounts per app; connect once, reuse across AI clients
- Tool search: finds the right action for the task
- One sign-in; vendor credentials are injected behind the scenes and OAuth tokens refresh automatically

**Visibility**
- Audit log for every tool call (who, which vendor, when)
- Usage dashboard: call volume, top vendors, error rate, per-user activity
- Export audit logs to CSV, or stream to Loki, Graylog, or LogScale (SIEM)
- Optional recording of tool arguments and result summaries (off by default, enabled per organization)

**Control**
- Per-role, per-tool allowlist, deny by default
- owner / admin / member roles
- SCIM provisioning with Entra ID, Okta, JumpCloud, and Google Workspace

**Security**
- Credentials encrypted one record at a time (AES-256-GCM, per-record key)
- AI clients authenticate with OAuth 2.1 + PKCE
- Vendor responses are scanned for prompt-injection patterns and returned as structured data. This is one layer of defense, not a guarantee against every attack.
- Static egress IP for customer firewall and API allowlisting

### Pricing

**Free.**

Links: [connect.mspbots.ai](https://connect.mspbots.ai) · [mspbots.ai](https://mspbots.ai)

---

## Authentication headers

Send **either** `X-Clio-Access-Token` **or** `X-Clio-Refresh-Token` + `X-Clio-Client-Id` +
`X-Clio-Client-Secret`. Sending all four is best: the access token is used directly and is
refreshed automatically when Clio rejects it.

| Header | Required | Type | Default | Allowed values | Description | Example |
|---|---|---|---|---|---|---|
| `X-Clio-Access-Token` | One of | string | none | - | Clio OAuth access token (a leading `Bearer ` is accepted and ignored) | `your-access-token` |
| `X-Clio-Refresh-Token` | One of | string | none | - | Clio OAuth refresh token, used to obtain a new access token | `your-refresh-token` |
| `X-Clio-Client-Id` | With refresh token | string | none | - | Client id (app key) of the Clio developer application | `your-client-id` |
| `X-Clio-Client-Secret` | With refresh token | string | none | - | Client secret (app secret) of the Clio developer application | `your-client-secret` |
| `X-Clio-Region` | No | string | `us` | `us`, `ca`, `eu`, `au` | Region that hosts the Clio account | `us` |

Where to get them:

- In the Clio **Developer Portal** of the account's region (`developers.clio.com`,
  `ca.developers.clio.com`, `eu.developers.clio.com` or `au.developers.clio.com`) create an
  application and note its **App Key** (client id) and **App Secret** (client secret). Give it
  read access to Matters, Contacts, Activities, Tasks, Communications, Documents, Calendars and
  Bills, and write access only to the areas the agent should change.
- Authorise the application for the firm's Clio account with the standard OAuth
  authorisation-code flow (`/oauth/authorize` then `/oauth/token` on the region's host). The
  token response contains the access token (valid for 30 days) and the refresh token (does
  not expire). Tokens from one region do not work in another.
- The region is the one in the account's Clio URL: `app.clio.com` = `us`, `ca.app.clio.com` =
  `ca`, `eu.app.clio.com` = `eu`, `au.app.clio.com` = `au`.

How credentials are sent to Clio: every call is `Authorization: Bearer <access token>` to
`https://{region host}/api/v4/...`. When Clio answers 401 (or no access token was sent) and a
refresh token with client id / secret is present, the server calls
`POST https://{region host}/oauth/token` with `grant_type=refresh_token` once and retries. The
refreshed token lives only for that request. Values that look like unresolved templates
(`${...}`) are treated as missing.

A request to `/mcp` without usable credentials gets HTTP 401 listing the accepted header sets.
An unknown region does not block `tools/list`; tool calls then return an `invalid_argument`
error naming the allowed regions.

## Tools

All tools return a JSON string. Records are referenced by numeric Clio ids. List tools return
`{items, count, total, has_more, next_page_token}` and take the paging parameters `fields`,
`limit` (1-200, default 50), `page_token` and `order`, plus `created_since` / `updated_since`
where Clio supports them. Without `fields`, every list and get tool returns a useful default
field set (Clio itself returns only `id` and `etag`); pass `fields` with Clio's nested syntax,
for example `id,display_number,client{id,name}`, to choose your own.

| Tool | Purpose | Parameters (required in **bold**) |
|---|---|---|
| `clio_navigate` | Describe the tools of one Clio area (changes nothing) | **domain** (`matters`, `contacts`, `activities`, `communications`, `tasks`, `documents`, `calendar-entries`, `bills`) |
| `clio_back` | List every Clio area and its tools (changes nothing) | - |
| `clio_status` | Check the Clio connection: signed-in user, region and whether the token can be refreshed | - |
| `clio_matters_list` | List matters (cases/files) with number, description, status, client and responsible attorney | query, status, client_id, practice_area_id, responsible_attorney_id, billable, + paging |
| `clio_matters_get` | Get one matter by id, including attorneys, stage, billing method and dates | **id**, fields |
| `clio_matters_create` | Create a matter for a client (**write**) | **description**, client_id, client_name, status (`open`, `pending`, `closed`), practice_area_id, responsible_attorney_id, originating_attorney_id, billable, open_date, client_reference |
| `clio_matters_update` | Change fields of a matter; only the fields given change (**write**) | **id**, description, status (`open`, `pending`, `closed`), client_id, practice_area_id, responsible_attorney_id, originating_attorney_id, billable, close_date |
| `clio_contacts_list` | List contacts (people and companies) with type, primary email/phone and client flag | query, type (`Person`, `Company`), client_only, initial, + paging |
| `clio_contacts_get` | Get one contact by id, including all email addresses, phone numbers and addresses | **id**, fields |
| `clio_contacts_create` | Create a person or company contact (**write**) | **name**, **type** (`Person`, `Company`), first_name, last_name, company_id, email, phone |
| `clio_contacts_update` | Change a contact; only the fields given change (**write**) | **id**, name, first_name, last_name, email, phone |
| `clio_activities_list` | List time and expense entries with date, hours, rate, total, note and matter | query, matter_id, user_id, task_id, type (`TimeEntry`, `ExpenseEntry`, `HardCostEntry`, `SoftCostEntry`), status (`billed`, `draft`, `unbilled`, `non_billable`, `billable`, `written_off`), start_date, end_date, + paging |
| `clio_activities_get` | Get one time or expense entry by id | **id**, fields |
| `clio_activities_create` | Log a time or expense entry; billable entries can end up on a client bill (**write**) | **date**, **type** (`TimeEntry`, `ExpenseEntry`, `HardCostEntry`, `SoftCostEntry`), matter_id, note, price, quantity, non_billable |
| `clio_communications_list` | List logged emails and phone calls with subject, date, matter and participants (no body) | query, matter_id, contact_id, user_id, type (`EmailCommunication`, `PhoneCommunication`), date, + paging |
| `clio_communications_get` | Get one logged email or phone call by id, including its body | **id**, fields |
| `clio_tasks_list` | List tasks with status, priority, due date, assignee and matter | query, matter_id, assignee_id, assignee_type (`user`, `contact`), status (`pending`, `in_progress`, `in_review`, `complete`, `draft`), priority (`high`, `normal`, `low`), complete, due_at_from, due_at_to, + paging |
| `clio_tasks_get` | Get one task by id, including its description | **id**, fields |
| `clio_tasks_create` | Create a task and assign it (**write**) | **name**, **description**, **assignee_id**, assignee_type (`User`, `Contact`), matter_id, due_at, priority (`High`, `Normal`, `Low`), status (`pending`, `in_progress`, `in_review`, `complete`, `draft`) |
| `clio_tasks_update` | Change a task; only the fields given change (**write**) | **id**, name, description, status (`pending`, `in_progress`, `in_review`, `complete`, `draft`), priority (`High`, `Normal`, `Low`), due_at, assignee_id, assignee_type (`User`, `Contact`) |
| `clio_documents_list` | List document metadata: name, file name, size, type, folder, matter and contact | query, matter_id, contact_id, document_category_id, parent_id, scope (`children`, `descendants`), include_deleted, + paging |
| `clio_documents_get` | Get one document's metadata by id | **id**, fields |
| `clio_calendar_entries_list` | List calendar entries with title, time, location, matter and calendar owner | query, matter_id, calendar_id, from, to, is_all_day, + paging |
| `clio_calendar_entries_get` | Get one calendar entry by id, including its description and recurrence | **id**, fields |
| `clio_bills_list` | List bills (invoices) with number, state, dates, total, paid, balance due, client and matters | client_id, matter_id, state (`draft`, `awaiting_approval`, `awaiting_payment`, `paid`, `void`, `deleted`), type (`revenue`, `trust`), overdue_only, due_after, due_before, issued_after, issued_before, + paging |
| `clio_bills_get` | Get one bill by id, including subject, memo, billing period and tax totals | **id**, fields |

Errors come back as a JSON envelope instead of an exception:

```json
{"error": {"code": "unauthorized", "message": "Clio returned HTTP 401 for matters: ...", "retryable": false}}
```

`code` is one of `not_configured`, `unauthorized`, `not_found`, `invalid_argument`,
`rate_limited`, `upstream_error`; Clio validation errors name the offending fields. Clio
allows about 50 requests per minute per access token. Reads are retried with backoff on 429,
5xx and network errors (honouring `Retry-After`); writes are retried only on 429, so a write
never runs twice.

## Run locally

```bash
uv sync
uv run python -m clio_mcp          # listens on 0.0.0.0:8080
```

or with Docker:

```bash
docker build --platform linux/amd64 -t clio-mcp:dev .
docker run --rm -p 8080:8080 clio-mcp:dev
```

Configuration (environment variables, all optional): `MCP_HTTP_HOST` (default `0.0.0.0`),
`MCP_HTTP_PORT` (default `8080`), `LOG_LEVEL` (default `INFO`). Credentials are never read
from the environment.

## Testing example

```bash
# list tools
curl -s http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Clio-Access-Token: your-access-token" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# open matters of one client
curl -s http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Clio-Access-Token: your-access-token" \
  -H "X-Clio-Region: us" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"clio_matters_list","arguments":{"client_id":123,"status":"open","limit":10}}}'
```

Unit tests (no network access needed):

```bash
uv run pytest
```

## Delivery notes

- **All tools always listed.** Older versions only listed navigation tools until one was
  called. Behind a stateless gateway that hid every other tool, so this version lists all 26
  tools up front. `clio_navigate` and `clio_back` remain for compatibility and only describe
  the tools.
- **No interactive prompts.** Older versions asked the user for missing values mid-call,
  which a stateless gateway cannot relay. The values Clio needs are now required parameters
  (`clio_matters_create.description`, `clio_contacts_create.name` / `type`,
  `clio_activities_create.date` / `type`, `clio_tasks_create.name` / `description` /
  `assignee_id`). A `client_name` that matches several contacts returns the candidates so the
  agent can ask the user and pass `client_id`.
- **Default fields.** List and get tools return a useful default field set instead of Clio's
  bare `id` / `etag`, and lists return a `next_page_token` for the next page.
- **Contact updates.** A new `email` / `phone` replaces the contact's primary entry in place
  instead of adding another entry on every update.
- **Write tools.** The 7 tools marked **write** change the firm's live records; their
  descriptions tell the agent to use them only on explicit request. Time entries take
  `quantity` in seconds. There are no delete, billing or document-content tools.

## License

Apache License 2.0 - see [LICENSE](LICENSE) and [NOTICE](NOTICE).