MCP server (add-on)

Overview

The MCP server add-on lets an AI assistant work with a firm's Matterly data: look up clients, matters and invoices, read Smart Form responses, add a client or send a form for signature. It uses the Model Context Protocol, which Claude, Cursor and other assistants support.

The assistant signs in with one of the firm's API keys, and the key's permissions decide what it can see and do. A key with only clients:read and invoices:read, for example, can look things up but never change anything.

Needs Matterly 1.5 and API access in the firm's plan.

Install

Super Admin → Modules: install MCP server.
Plans & Pricing → Modules included: tick it for the plans that should have it (or give it to one firm under Firms → Extra modules).

Connect an assistant

In the firm, Settings → API → API keys: create a key for the assistant with the permissions it should have.
Point the assistant at the firm's address, sending the key as a header:

URL:     https://your-site/matterly-mcp/firms/{your-firm}
Header:  Authorization: Bearer sp_…

Claude Code:

claude mcp add --transport http matterly https://your-site/matterly-mcp/firms/your-firm --header "Authorization: Bearer sp_…"

Clients configured with JSON (Cursor and others):

{
  "mcpServers": {
    "matterly": {
      "url": "https://your-site/matterly-mcp/firms/your-firm",
      "headers": { "Authorization": "Bearer sp_…" }
    }
  }
}

The assistant must be able to send a custom header with the key; assistants that only connect with OAuth can't use this add-on.

Tools

Tool	What it does	Key permission
`list_clients`, `get_client`	Find clients (by email) and read one	`clients:read`
`create_client`	Add a client, or return the existing one with that email	`clients:write`
`list_matters`, `get_matter`	Find matters (by status or client) and read one	`matters:read`
`list_invoices`, `get_invoice`	Find client invoices and read one	`invoices:read`
`list_smart_forms`	The firm's Smart Forms and their signer roles	`forms:read`
`list_form_submissions`, `get_form_submission`	Responses with answers, signers and extras	`forms:read`
`send_smart_form`	Send a form, or start signing by several people	`forms:send`

The assistant only sees the tools its key allows. Every call goes through the same checks as the API, so it can never reach another firm's data or do more than the key permits.

Good to know

Revoking the key in Settings → API disconnects the assistant at once.
Calls count towards the key's 120 requests a minute.
The assistant decides what to call from your instructions. Review anything it proposes to send to a client.