Connect your AI Agents to SmartAdvocate in minutes
Available tools
list_case_appointments
List every calendar appointment on one case by internal case ID. Not paginated — returns the case's full appointment history. Use search_appointments for a firm-wide or date-filtered view.
list_appointments_by_case_number
List every calendar appointment on one case by its human-readable case number. Use listcaseappointments when you already have the internal case ID.
search_appointments
Search appointments across cases for firm-wide calendars and deadline reports. The modified-date window is required; narrow further by the dates the appointments fall on, by case number, or by owning staff user.
create_appointment
Schedule an appointment on a case — a hearing, deposition, meeting, or reminder. Call listappointmenttypes, listappointmentactivitytypes, and listappointment_statuses first; those IDs are per-firm configuration.
list_appointment_types
List the firm's appointment types, e.g. Deposition or Trial. Call this before create_appointment — type IDs are per-firm configuration.
list_appointment_activity_types
List the firm's appointment activity types — the secondary classification on an appointment. Call this before create_appointment.
list_appointment_statuses
List the firm's appointment statuses, e.g. Scheduled or Cancelled. Call this before create_appointment.
list_case_calls
List the calls logged on one case — remote party, number, direction, date, and summary. Page with pageinfo.nextpage.
create_call
Log a phone call on a case. direction is true for outbound and false for inbound. Use listcasecontacts or lookup_contacts to find the remote party's contact ID. summary accepts HTML.
update_call
Replace a logged call in full. Every field you want kept must be supplied — omitted fields are cleared. Use patch_call to change one field.
patch_call
Change selected fields on a logged call, leaving the others untouched. Pass fields as a mapping of API field name to new value, e.g. summary. Use update_call to replace the whole record.
delete_call
Delete a logged call from a case permanently. This cannot be undone.
get_case
Get one case by its internal case ID, including parties, staff, tags, and incident summary. Use getcaseinfo instead when you only have the human-readable case number. Find case IDs with searchcases or listactive_cases.
get_case_info
Get a case by its human-readable case number, e.g. 9000002. Use get_case instead when you already have the internal case ID. Optionally include full contact details and referral source information.
search_cases
Search cases modified within a date range, optionally narrowed by case number, case type, case group, or tag. The date window is required. Use listcasegroups, listcasetypes, and listtags to resolve filter IDs. Page with pageinfo.next_page.
list_active_cases
List open cases assigned to one staff member, for workload or dashboard views. Use listcasestaff on a known case to find staff contact IDs. Set primary_only to return only cases where they are the primary assignee.
create_case
Open a new case from intake details. Call listcasegroups and listcasetypes first — group and type IDs are per-firm configuration and cannot be guessed. At least one of email or phone is required. Pass plaintiffcontactid to attach an existing contact, or omit it to have SmartAdvocate create one from the name fields.
update_case_number
Change a case's human-readable case number. The firm must have case-number editing enabled in SmartAdvocate and the new number must be unused, or the call is rejected. Documents already stored keep their existing folder paths.
list_case_contacts
List every contact linked to a case with the role each one holds — plaintiff, defendant, witness, adjuster, and so on. Also the way to see which role names this firm uses before calling addcasecontact.
add_case_contact
Link an existing contact to a case in a role. Find the contact ID with lookupcontacts or searchcontacts, or create one with createcontact. Role names are per-firm; call listcase_contacts on a similar case to see the ones in use.
update_case_contact
Replace a case-contact link's role and comments. This is a full replacement — any field left unset is cleared. Use patchcasecontact to change one field and leave the rest alone.
patch_case_contact
Change selected fields on a case-contact link, leaving the others untouched. Pass fields as a mapping of field name to new value. Use updatecasecontact to replace the whole link instead.
delete_case_contact
Unlink a contact from a case. This removes the case-contact relationship only; the contact record itself is left in place.
list_related_cases
List cases linked to this one as related matters — consolidated cases, companion cases, or other cases involving the same parties.
list_case_groups
List the firm's case groups — the top-level case classification, e.g. Personal Injury. Call this before createcase or searchcases: group IDs are per-firm configuration. Feed a group ID to listcasetypes.
list_case_types
List the case types inside one case group — the second-level classification. Get the group ID from listcasegroups. Feed a type ID to listcasesubtypes or create_case.
list_case_subtypes
List the subtypes inside one case type — the third-level classification. Get the case type ID from listcasetypes. Returns an empty list when the type defines no subtypes.
get_contact
Get a contact's core details by contact ID — name, primary address, phone, and email. Use getcontactfull for the complete record with every address, email, and phone.
get_contact_full
Get a contact's complete record, including all addresses, emails, phones, and classification fields. Heavier than get_contact — use that one when the core fields are enough.
search_contacts
Search contacts by modified-date window, optionally restricted to those linked to given case numbers. The date window is required. Use lookup_contacts to search by name or phone instead.
lookup_contacts
Find contacts by name or phone number — the way to resolve a person to a contact ID before addcasecontact, addplaintiff, or createcall. With no filters it returns a full paginated contact list. Note first_page is one-based.
create_contact
Create a contact. Call listcontacttypes first — category and type IDs are per-firm configuration. Give firstname and lastname for a person, or other_name for an organization. Addresses, emails, and phones can be included inline.
patch_contact
Change selected fields on a contact, leaving the others untouched. Pass fields as a mapping of API field name to new value. Addresses, emails, and phones have their own tools — this route does not reach them.
list_related_contacts
List contacts related to a given contact, with the relationship each one holds — family members, employers, and similar links.
list_contact_addresses
List a contact's postal addresses. Returns the address IDs patchcontactaddress and deletecontactaddress take.
add_contact_addresses
Add one or more postal addresses to a contact. Pass a list even for a single address. Use listincidentstates for valid two-letter state codes.
patch_contact_address
Change selected fields on one of a contact's addresses. Get the address ID from listcontactaddresses. Pass fields as a mapping of API field name to new value.
delete_contact_address
Delete one address from a contact permanently. This cannot be undone.
list_contact_emails
List a contact's email addresses. The address itself is in the name field. Returns the email IDs patchcontactemail and deletecontactemail take.
add_contact_emails
Add one or more email addresses to a contact. Pass a list even for a single address. Set preventautocontact to stop automated messages going to it.
patch_contact_email
Change selected fields on one of a contact's email addresses. The address itself is the name field. Get the email ID from listcontactemails.
delete_contact_email
Delete one email address from a contact permanently. This cannot be undone.
list_contact_phones
List a contact's phone numbers with their labels and texting flags. Returns the phone IDs patchcontactphone and deletecontactphone take.
add_contact_phones
Add one or more phone numbers to a contact. Pass a list even for a single number. Use listphonetypes for the labels this firm uses, e.g. Mobile Phone.
patch_contact_phone
Change selected fields on one of a contact's phone numbers. Get the phone ID from listcontactphones. Pass fields as a mapping of API field name to new value.
delete_contact_phone
Delete one phone number from a contact permanently. This cannot be undone.
list_contact_types
List the firm's contact types for a contact category. Call this before create_contact — the category and type IDs are per-firm configuration.
list_address_types
List the firm's address types for a contact category, for labelling addresses on a contact.
list_phone_types
List the firm's phone types, e.g. Mobile Phone or Work Phone. Use one of these as the name when calling addcontactphones.
list_contact_subcategories
List the firm's contact subcategories. Feeds contactsubcategoryid on createcontact.
list_case_documents
List document metadata for one case, filtered server-side by category, subcategory, or originating/destination contact. Returns metadata only — use downloaddocument for file content. Use listdocument_categories to resolve IDs.
list_documents_by_case_number
List document metadata for one case by its human-readable case number, with the same category and contact filters. Use listcasedocuments when you already have the internal case ID.
get_document
Get one document's metadata by document ID — name, category, dates, and review state. Returns no file content; use download_document for that.
search_documents
Search document metadata across cases by modified-date window, narrowed by case number, category, subcategory, or contact. The date window is required. Returns metadata only — use download_document for content.
create_document
Create a document metadata record on a case. This moves no bytes — call uploaddocumentcontent with the returned document ID to attach the file. Call listdocumentcategories first; category IDs are per-firm configuration.
update_document
Replace a document's metadata in full. Every field you want kept must be supplied — omitted fields are cleared. Use patch_document to change one field. Neither tool touches the file content.
patch_document
Change selected metadata fields on a document, leaving the others untouched. Pass fields as a mapping of API field name to new value. Use update_document to replace the whole record.
download_document
Download a document's file content by document ID. Returns UTF-8 text as text and anything else as base64 — check the 'encoding' field before use. Files over maxbytes (10 MB default) come back flagged truncated with no content; set returndownload_url=true for a download link instead, which handles larger files.
upload_document_content
Attach file content to an existing document record. Pass the bytes as base64 in contentbase64, or a filereference from the file upload API (POST /api/v1/files/) for large files, which never enter the model's context. Create the record first with create_document. If this fails, retry against the same document ID rather than creating another record.
list_document_categories
List the firm's document categories with their subcategories, one row per category/subcategory pair. Call this before create_document or the document list filters — these IDs are per-firm configuration.
list_document_folders
List the document folders configured on one case. Use a folder name as documentfolder on createdocument to file a document into it.
list_document_tags
List the firm's document tags. Call this before createdocument to pass valid tagids.
get_case_incident
Get a case's incident record — the facts of what happened plus structured details like date, state, and county. Returns the incident ID that updateincident and patchincident need.
get_incident_by_case_number
Get a case's incident record by its human-readable case number. Use getcaseincident when you already have the internal case ID.
search_incidents
Search incident records across cases by modified-date window, optionally restricted to specific case numbers. The date window is required.
update_incident
Replace a case's incident facts and structured details. Get the incident ID from getcaseincident. Supplying incidentdetails replaces the existing detail rows, so include every one you want kept; use patchincident to change just the facts.
patch_incident
Change selected fields on a case's incident record, leaving the others untouched. Pass fields as a mapping of API field name to new value, e.g. incidentFacts.
list_incident_states
List the states available on incident records. Call this before update_incident to get a valid state ID, or to resolve a two-letter state code.
list_incident_counties
List the counties available on incident records. This is a large reference list covering every state; call it before update_incident to get a valid county ID.
list_liability_codes
List the firm's liability codes for incident records. Call this before update_incident — these IDs are per-firm configuration.
list_case_injuries
List the injury records on a case, one per injured plaintiff. Returns the injury IDs the injury-detail tools take. Use listinjurydetails for the individual body-part and treatment rows under an injury.
get_injury
Get one injury record on a case, including its summaries and confinement details. Use listcaseinjuries to find injury IDs.
search_injuries
Search injury records across cases by modified-date window, optionally restricted to specific case numbers. The date window is required.
create_injury
Create an injury record for one plaintiff on a case. plaintiffid is the plaintiff RECORD id from listplaintiffs, not the contact ID. Add body parts and treatments afterwards with createinjurydetail.
update_injury
Replace an injury record's summaries, confinement details, and comments. Fields left unset are cleared, so supply everything you want kept.
delete_injury
Delete an injury record from a case permanently, along with its detail rows. This cannot be undone.
list_injury_details
List the detail rows under one injury — each a body part with its treatments and sequelae. Returns the detail row IDs the update and delete tools take.
get_injury_detail
Get one injury detail row by its ID. Use listinjurydetails to find row IDs.
create_injury_detail
Add a body-part detail row to an injury. Call listbodyparts first, then listtreatments and listsequelae with that body part ID — all three are per-firm reference data.
update_injury_detail
Replace an injury detail row. Fields left unset are cleared, so supply everything you want kept. Use patchinjurydetail to change one field.
patch_injury_detail
Change selected fields on an injury detail row, leaving the others untouched. Pass fields as a mapping of API field name to new value.
delete_injury_detail
Delete one injury detail row permanently. This cannot be undone.
add_injury_details_by_icd
Add injury detail rows from ICD diagnosis codes, letting SmartAdvocate map each code to the right body part and injury. Faster than createinjurydetail when you already have coded diagnoses.
add_injury_details_by_cpt
Add procedure detail rows to an injury from CPT procedure codes, letting SmartAdvocate map each code to the right treatment.
list_body_parts
List the body parts available on injury detail rows. Call this first when building a detail row, then feed the ID to listtreatments and listsequelae.
list_sequelae
List the sequelae — follow-on conditions — recorded for one body part. Feeds sequelaeids on createinjurydetail. Use listbody_parts to get the body part ID.
list_treatments
List the treatments available for one body part. Feeds treatmentids on createinjurydetail. Use listbody_parts to get the body part ID.
list_injury_names
List the firm's catalogue of injury names. This is a large reference list; use it to resolve an injury description to a known name.
list_case_insurance
List the insurance policies on a case for one side. party is required: 'P' for plaintiff-side coverage, 'D' for defendant-side — they are separate lists, so check both to see all policies.
list_insurance_by_case_number
List insurance policies for one side of a case by its human-readable case number. Use listcaseinsurance when you already have the internal case ID.
get_insurance
Get one insurance policy on a case by its insurance record ID, including carrier, adjuster, limits, and claim number.
create_insurance
Record an insurance policy on a case. Set party to 'P' or 'D' and pass the matching plaintiffid or defendantid from listplaintiffs / listdefendants. Use listinsurancetypes and lookup_contacts for the type and carrier IDs.
update_insurance
Replace an insurance policy in full. Fields left unset are cleared, so supply everything you want kept, including party and the matching party ID. Use patch_insurance to change one field.
patch_insurance
Change selected fields on an insurance policy, leaving the others untouched. Pass fields as a mapping of API field name to new value, e.g. policyNo. party is still required so SmartAdvocate scopes the record correctly.
delete_insurance
Delete an insurance policy from a case permanently. This cannot be undone.
list_insurance_types
List the firm's insurance types, e.g. auto liability or health. Call this before create_insurance — these IDs are per-firm configuration.
list_case_notes
List the notes on one case by internal case ID, newest first. Use listnotesbycasenumber when you only have the case number, or searchnotes to look across cases by date. Page with pageinfo.next_page.
list_notes_by_case_number
List the notes on one case by its human-readable case number. Use listcasenotes when you already have the internal case ID.
get_note
Get one case note by its note ID, including full body text and sharing settings.
search_notes
Search notes across cases by modified-date window, optionally restricted to specific case numbers. The date window is required. Use listcasenotes for the notes on one known case.
create_note
Add a note to a case. Call listnotetypes first — note type IDs are per-firm configuration. note_text accepts HTML. Returns the new note ID.
update_note
Replace a note in full — type, body, date, subject, contact, priority and sharing. Every field left unset is cleared, so read the current note with getnote first. Use patchnote to change one field and leave the rest alone.
patch_note
Change selected fields on a note, leaving the others untouched. Pass fields as a mapping of API field name to new value, e.g. noteText or isSharedinCP. Use update_note to replace the whole note.
list_note_types
List the firm's note types. Call this before createnote or updatenote — note type IDs are per-firm configuration and cannot be guessed.
list_plaintiffs
List the plaintiffs on a case with their roles and contact IDs. Set addcontactinfo to include full contact details, or table_type to read the Other or Non-Party tables instead of the main one.
list_defendants
List the defendants on a case with their roles and contact IDs.
add_plaintiff
Add a plaintiff to a case. Call listplaintiffroles first with the case's type ID — role IDs are per-firm configuration. The contact must already exist; use lookupcontacts or createcontact.
patch_plaintiff
Change selected fields on a plaintiff record, leaving the others untouched. Pass fields as a mapping of API field name to new value. Use list_plaintiffs to find the plaintiff record ID.
list_plaintiff_roles
List the plaintiff roles available for a case type, e.g. Passenger or Driver. Call this before add_plaintiff — role IDs are per-firm configuration. Pass 0 for roles across all case types.
lookup_cases
Look up cases by a single criterion, e.g. every case with a given status. Pass the value as criteria and what it refers to as searchtype, such as CASESTATUS. Use searchcases for date-window and multi-filter searches.
list_case_staff
List the staff assigned to one case with their roles. This is the discovery tool for staff IDs: it returns the contact ID listactivecases takes and the user ID task and appointment writes take.
list_staff_by_case_number
List staff assignments by case number. Accepts % as a wildcard, so '1%' returns assignments for every case whose number starts with 1. Use listcasestaff for a single known case ID.
search_case_staff
Search staff assignments across cases by modified-date window, optionally restricted to specific case numbers. The date window is required. Useful for finding reassignments in a period.
list_case_statuses
List a case's status history by internal case ID — each record with its type, value, and effective dates. A record with no to_date is still active.
list_statuses_by_case_number
List a case's status history by its human-readable case number. Use listcasestatuses when you already have the internal case ID.
get_case_status
Get one case status record by its status record ID, with dates and comments.
search_case_statuses
Search case status records across cases by modified-date window, optionally restricted to specific case numbers. The date window is required.
create_case_status
Add a status record to a case. Call liststatustypes first — both the status type ID and the status value ID within it are per-firm configuration. Use terminatecasestatus to close out an active status instead of replacing it.
update_status_comment
Change the comment on an existing case status record. Only the comment can be edited; use createcasestatus to record a new status.
terminate_case_status
Close out the active status of a given type on a case by stamping its end date. Nothing is deleted — the record stays in the case's status history. Use listcasestatuses to see which types are currently active.
list_status_types
List the firm's case status types and the status values inside each one. Call this before createcasestatus or terminatecasestatus — both IDs are per-firm configuration. Narrow with statustypeid to see one type's values.
list_tags
List every tag defined in the firm, with its active state and any case-group or case-type restrictions. Use listavailablecase_tags instead to see which tags may be applied to one specific case.
get_tag
Get one tag definition by ID, including its group and case-type restrictions.
create_tag
Define a new tag that can be applied to cases. Set limitgroups true and pass groups to restrict it to certain case groups — use listcasegroups and listcase_types for those IDs.
update_tag
Update a tag definition's name, active state, or group restrictions. This replaces the tag's properties, so supply every value you want kept.
delete_tag
Delete a tag definition permanently. This also removes the tag from every case it was applied to and cannot be undone. To take a tag off one case only, use removecasetags.
list_available_case_tags
List the tags that can still be applied to one case — those allowed for its case group and type and not already assigned. Call this before addcasetags.
add_case_tags
Apply one or more existing tags to a case. Call listavailablecase_tags first — a tag not permitted for the case's group or type, or already applied, is rejected.
remove_case_tags
Take one or more tags off a case. The tag definitions themselves are left intact — use delete_tag to remove a definition entirely.
list_case_tasks
List the tasks on one case by internal case ID. Use listtasksbycasenumber when you only have the case number, or search_tasks to look across cases and filter by type, status, assignee, or due date.
list_tasks_by_case_number
List the tasks on one case by its human-readable case number. Use listcasetasks when you already have the internal case ID.
get_task
Get one task by its task ID, including assignee, dates, and attached documents.
search_tasks
Search tasks across cases, filtering by modified window, due-date range, type, status, assignee, or template. All filters are optional. Use listtasktypes and listtaskstatuses to resolve IDs. Due-date filters need SmartAdvocate API 2026-07+.
create_task
Create a task on a case. Call listtasktypes, listtaskstatuses, and listtaskpriorities first — these IDs are per-firm configuration. Pass IDs rather than labels where you have them. Returns the new task ID.
update_task
Replace a task in full. Every field you want kept must be supplied — omitted fields are cleared. Use patch_task to change one field and leave the rest alone.
patch_task
Change selected fields on a task, leaving the others untouched. Pass fields as a mapping of API field name to new value, e.g. description or summary. Use update_task to replace the whole task.
delete_task
Delete a task permanently by its task ID. This cannot be undone.
list_task_types
List the firm's task types. Call this before createtask, updatetask, or search_tasks — task type IDs are per-firm configuration.
list_task_statuses
List the firm's task statuses, e.g. Not Started or Completed. Call this before createtask, updatetask, or search_tasks.
list_task_priorities
List the firm's task priority levels, e.g. Normal or High. Call this before createtask or updatetask.
list_case_udfs
List a case's user-defined fields and their current values — SmartAdvocate's custom fields. This is the discovery tool for UDF writes: it returns the udfid, screenname, and relatedPK that updateudf and the grid tools need.
list_udfs_by_case_number
List a case's user-defined fields by its human-readable case number. Use listcaseudfs when you already have the internal case ID.
get_udf
Get one user-defined field's value on a case by its UDF definition ID. Use listcaseudfs to find UDF IDs.
search_udfs
Search user-defined field values across cases by modified-date window, optionally restricted to specific case numbers. The date window is required.
update_udf
Set one user-defined field's value on a case. Call listcaseudfs first for the udfid, and pass its relatedPK as subrelatedid for plaintiff- or defendant-level fields. Use bulkupdateudfs to set several at once.
bulk_update_udfs
Set several user-defined field values on one case in a single transaction — if any entry is invalid nothing is written. Call listcaseudfs first for the udfids. Grid-type UDFs are rejected here; use createudfgrid_row for those.
list_udf_grid_rows
List the rows of a UDF grid on a case. Get the screen name from the screenname of a grid-type field returned by listcaseudfs. Row IDs from here feed getudfgridrow, updateudfgridrow, and deleteudfgridrow.
get_udf_grid_row
Get one row of a UDF grid by row ID, returning each cell's column definition ID and value. Use listudfgrid_rows to find row IDs.
create_udf_grid_row
Add a row to a UDF grid on a case. Read the column definition IDs from an existing row with listudfgrid_rows first — they are per-firm configuration and cannot be guessed.
update_udf_grid_row
Replace a UDF grid row's cells. This is a full replacement — include every column you want kept, with each cell's udfvalueid so existing values are updated rather than duplicated.
delete_udf_grid_row
Delete a row from a UDF grid on a case. This cannot be undone.
validate_credential
Check that the SmartAdvocate connection works by signing in and reading the firm's case groups.
How to set up Merge Agent Handler
In an mcp.json file, add the configuration below, and restart Cursor.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5 "headers": {
6 "Authorization": "Bearer yMt*****"
7 }
8 }
9 }
10}
11Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.
Make sure Claude is using the Node v20+.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "yMt*****"
14 }
15 }
16 }
17}Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<ah-production-access-key>"
14 }
15 }
16 }
17 }In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".
You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.
Learn more in the official documentation ↗
1{
2 "inputs": [
3 {
4 "type": "promptString",
5 "id": "agent-handler-auth",
6 "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7 "password": true
8 }
9 ],
10 "servers": {
11 "agent-handler": {
12 "type": "stdio",
13 "command": "npx",
14 "args": [
15 "-y",
16 "mcp-remote@latest",
17 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18 "--header",
19 "Authorization: Bearer ${input:agent-handler-auth}"
20 ]
21 }
22 }
23}FAQs on using Merge's SmartAdvocate MCP server
FAQs on using Merge's SmartAdvocate MCP server
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
