> For the complete documentation index, see [llms.txt](https://docs.keeping.com/help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeping.com/help/mcp-server/mcp-tool-reference.md).

# MCP tool reference

Every tool the Keeping MCP server offers, what it does, the permission it needs, when it became available, and which ones ask you to confirm before they change anything.

This page lists the tools your AI assistant can use once it is connected to the Keeping MCP server. Your assistant normally picks the right tool for you, so you don't need to name them. Use this page to see what is possible and what a given permission level allows.

{% hint style="info" %}
This list reflects the current server. Your AI tool always shows the live list of tools it has been given, which depends on the permission you chose when you connected. See [Permissions & Scopes](/help/mcp-server/connecting-to-keepings-mcp-server.md#permissions-and-scopes).
{% endhint %}

## How permissions map to tools

| Permission you choose                              | Tools your assistant gets                                                                                                |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Read only**                                      | Read tools and analytics tools. If you are an admin on a plan with Advanced MCP, also the admin tools marked **Read**.   |
| **Read and Write**                                 | Everything above, plus the write tools.                                                                                  |
| **Read, Write, and Manage Settings** (admins only) | Everything above, plus the admin tools marked **Manage Settings**. Offered to company admins on plans with Advanced MCP. |

If you connect with a Personal Access Token instead of OAuth, your assistant gets the read, analytics, and write tools only. A Personal Access Token can't use any admin tools, including the ones marked **Read**. To use them, connect with OAuth.

## Tools that ask you to confirm

Tools marked **Yes** in the **Asks to confirm** column won't make their change until your AI assistant confirms it. If the assistant calls one of them without confirming, nothing changes: the server answers that the change needs your confirmation first. Your assistant should describe the exact change and check with you before it confirms. This applies to deletes and to many changes to existing settings, such as updating a tag, a workflow, or a mailbox.

## When tools became available

The **Available since** line under each heading gives the date the tools in that table first ran on the production server. Your AI tool may need a reconnect, or in ChatGPT a **Refresh** on the Keeping plugin, before it sees tools added after you connected.

## Read tools

Retrieve tickets, mailboxes, people, and counts. Available with every permission level.

*Available since 2026-10-12. `get_my_preferences` since 2026-10-27.*

| Tool                        | What it does                                                                                    | Asks to confirm |
| --------------------------- | ----------------------------------------------------------------------------------------------- | --------------- |
| `get_me`                    | Your identity, role, and the mailboxes you can access.                                          |                 |
| `search_conversations`      | Search conversations (tickets) by free text and filters.                                        |                 |
| `get_conversation`          | Full details for one conversation (ticket), by ID, including its custom fields.                 |                 |
| `list_conversations`        | List conversations (tickets) with filters and pagination.                                       |                 |
| `get_conversation_messages` | The messages in a conversation, with sender info and previews.                                  |                 |
| `get_notes`                 | The internal notes on a conversation, with authors.                                             |                 |
| `get_draft_messages`        | The drafts on a conversation, including shared drafts and your private drafts.                  |                 |
| `get_activity`              | The activity log for a conversation.                                                            |                 |
| `list_mailboxes`            | The mailboxes you can access. For admins, each mailbox's connection status and next setup step. |                 |
| `list_agents`               | The agents (team members) in your company, optionally for one mailbox.                          |                 |
| `list_tags`                 | All tags in your company, with their colors and mailboxes.                                      |                 |
| `list_templates`            | List the company's saved reply templates, or read one template in full by ID.                   |                 |
| `get_current_counters`      | Ticket counts by status for each mailbox you can access.                                        |                 |
| `get_sla_violations`        | Get conversations that have breached an SLA.                                                    |                 |
| `get_my_preferences`        | Your own preferences, such as availability, thread order, and notification switches.            |                 |

## Analytics tools

Reporting and performance metrics. Available with every permission level, on plans with Premium Reporting.

*Available since 2026-10-12.*

| Tool                          | What it does                                                   | Asks to confirm |
| ----------------------------- | -------------------------------------------------------------- | --------------- |
| `get_team_report`             | Team performance overview for a date range.                    |                 |
| `get_ticket_report`           | Ticket volume over time.                                       |                 |
| `get_message_report`          | Message volume over time.                                      |                 |
| `get_my_highlights`           | A quick snapshot of your own performance over the last 7 days. |                 |
| `get_agent_report`            | Individual agent performance over time.                        |                 |
| `get_tag_report`              | Tag performance metrics.                                       |                 |
| `get_tag_intersection_report` | Stats for conversations that have 2 to 4 specific tags.        |                 |
| `get_csat_report`             | Customer satisfaction scores and ratings.                      |                 |

## Write tools

Act on tickets and on your own account. These need **Read and Write** or higher. Write tools create drafts. They never send a message, so a person always sends from the Keeping Inbox or Gmail.

*Available since 2026-10-12. `set_conversation_custom_field`, `create_signature`, `update_signature`, `delete_signature` and `update_my_preferences` since 2026-10-27.*

| Tool                            | What it does                                                                        | Asks to confirm |
| ------------------------------- | ----------------------------------------------------------------------------------- | --------------- |
| `create_draft_message`          | Create a draft reply on a conversation.                                             |                 |
| `edit_draft_message`            | Replace the body of a draft on a conversation.                                      |                 |
| `delete_draft_message`          | Delete a draft from a conversation.                                                 |                 |
| `create_conversation`           | Create a new ticket as a draft. It is not sent.                                     |                 |
| `change_status`                 | Set a conversation to open, pending, or closed.                                     |                 |
| `change_assignments`            | Assign or unassign agents on a conversation.                                        |                 |
| `change_tags`                   | Add or remove tags on a conversation.                                               |                 |
| `change_priority`               | Set the priority of a conversation.                                                 |                 |
| `add_note`                      | Add an internal note to a conversation.                                             |                 |
| `move_conversation`             | Move a conversation to a different mailbox.                                         |                 |
| `generate_share_link`           | Create or regenerate a public share link for a conversation.                        |                 |
| `set_conversation_custom_field` | Set or clear a custom field on a ticket, such as an order number.                   | Yes             |
| `create_signature`              | Create your personal email signature.                                               |                 |
| `update_signature`              | Replace your signature text or change whether it is added to replies automatically. |                 |
| `delete_signature`              | Delete your personal signature. Cannot be undone.                                   | Yes             |
| `update_my_preferences`         | Change your own preferences, such as going unavailable so round-robin skips you.    |                 |

## Admin tools

Set up and manage your company. These are for company admins only, on plans with Advanced MCP. Tools marked **Read** are available at every OAuth permission level. Tools marked **Manage Settings** need the **Read, Write, and Manage Settings** permission.

### Agents

*Available since 2026-10-22.*

| Tool                        | What it does                                                                                                                 | Needs           | Asks to confirm |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------- | --------------- |
| `list_invitations`          | List pending invitations and requests to join.                                                                               | Read            |                 |
| `invite_agent`              | Invite a person to your company by email. On per-seat plans, a person beyond your paid seats adds a seat to the bill.        | Manage Settings |                 |
| `resend_invitation`         | Send a pending invitation again.                                                                                             | Manage Settings |                 |
| `update_agent`              | Change an agent's role or replace the list of mailboxes they can work.                                                       | Manage Settings | Yes             |
| `remove_agent`              | Remove a person from the company, or cancel their pending invitation. Their tickets are unassigned and their drafts deleted. | Manage Settings | Yes             |
| `review_invitation_request` | Approve or deny a request to join the company. Approving beyond your paid seats adds a seat on per-seat plans.               | Manage Settings | Yes             |

### Mailboxes

*Available since 2026-10-22.*

| Tool                          | What it does                                                                                                                                | Needs           | Asks to confirm |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | --------------- |
| `create_mailbox`              | Create a shared mailbox and get the next setup steps: the Gmail forwarding instructions, or the link to sign in with Google on keeping.com. | Manage Settings |                 |
| `update_mailbox`              | Rename a mailbox or change which agents can work it. The address and connection type can't be changed.                                      | Manage Settings | Yes             |
| `set_mailbox_auto_reply`      | Turn a mailbox's auto reply on or off and set its subject and body.                                                                         | Manage Settings | Yes             |
| `resend_mailbox_verification` | Send the verification email again for a mailbox connected by forwarding.                                                                    | Manage Settings |                 |
| `start_historical_import`     | Import up to 28 days of past email into a Google-connected mailbox. Runs once per mailbox.                                                  | Manage Settings |                 |

**Connecting a mailbox from your assistant.** Forwarding is the default: the assistant gives you the forwarding address and walks you through Gmail's forwarding settings, then checks that Keeping's verification email came through. Signing in with Google instead happens on keeping.com, from the link the assistant gives you. The setup status says whether the connection is verified, not whether customer mail has arrived yet, so send a test email to the address to see a ticket open. Creating a mailbox from your own login address can replace the demo mailbox; the assistant asks before it does.

### Tags and custom fields

*Available since 2026-10-27.*

| Tool                  | What it does                                                                                                | Needs           | Asks to confirm |
| --------------------- | ----------------------------------------------------------------------------------------------------------- | --------------- | --------------- |
| `create_tag`          | Create a tag. Names are unique per company.                                                                 | Manage Settings |                 |
| `update_tag`          | Rename a tag, change its color, or change which mailboxes offer it. The SLA Violation tag can't be renamed. | Manage Settings | Yes             |
| `delete_tag`          | Delete a tag and remove it from every ticket. Workflows whose only condition was this tag become inactive.  | Manage Settings | Yes             |
| `list_custom_fields`  | List a mailbox's custom ticket fields.                                                                      | Read            |                 |
| `create_custom_field` | Add a custom field, such as Order number or Plan, to every ticket in a mailbox.                             | Manage Settings |                 |
| `update_custom_field` | Rename a custom field, change its options, or deactivate or reactivate it.                                  | Manage Settings | Yes             |

### Templates

*Available since 2026-10-27.*

| Tool                    | What it does                                                 | Needs           | Asks to confirm |
| ----------------------- | ------------------------------------------------------------ | --------------- | --------------- |
| `create_template`       | Create a saved reply (template).                             | Manage Settings |                 |
| `update_template`       | Change a template's name, body, labels, or mailboxes.        | Manage Settings | Yes             |
| `delete_template`       | Delete a template for everyone. Sent replies are unaffected. | Manage Settings | Yes             |
| `delete_template_label` | Delete a template label and remove it from every template.   | Manage Settings | Yes             |

### Company settings and CSAT

*Available since 2026-10-27.*

| Tool                      | What it does                                                                                                               | Needs           | Asks to confirm |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------- | --------------- |
| `get_company_settings`    | Read your company name, ticket-ID-in-subject setting, MCP access, and business hours.                                      | Read            |                 |
| `update_company_settings` | Change the company name, the ticket-ID-in-subject setting, or business hours. Business hours drive SLA timers and reports. | Manage Settings | Yes             |
| `get_csat_settings`       | Read your customer satisfaction (CSAT) survey settings.                                                                    | Read            |                 |
| `update_csat_settings`    | Turn the CSAT survey on or off, choose when it is added, and pick mailboxes. Turning it on needs the CSAT add-on.          | Manage Settings | Yes             |
| `update_csat_template`    | Change how the CSAT rating widget looks in replies.                                                                        | Manage Settings | Yes             |

### Workflows

*Available since 2026-10-28.*

| Tool                        | What it does                                                                                                               | Needs           | Asks to confirm |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------- | --------------- |
| `list_workflows`            | List your workflows in run order.                                                                                          | Read            |                 |
| `get_workflow`              | Read one workflow in full, including any issues that keep it from being activated.                                         | Read            |                 |
| `describe_workflow_options` | List the triggers, conditions, and actions available when building a workflow, with your tags, agents and mailboxes by ID. | Read            |                 |
| `create_workflow`           | Create a workflow (an if/then automation rule).                                                                            | Manage Settings |                 |
| `update_workflow`           | Replace a workflow's whole document, including turning it on or off.                                                       | Manage Settings | Yes             |
| `delete_workflow`           | Permanently delete a workflow.                                                                                             | Manage Settings | Yes             |
| `reorder_workflows`         | Set the order workflows run in.                                                                                            | Manage Settings | Yes             |

### SLAs

*Available since 2026-10-28.*

| Tool                   | What it does                                                                                                          | Needs           | Asks to confirm |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------- | --------------- |
| `list_slas`            | List your SLA policies.                                                                                               | Read            |                 |
| `get_sla`              | Read one SLA policy in full, including any issues that keep it from being activated.                                  | Read            |                 |
| `describe_sla_options` | List the targets, conditions, and actions available when building an SLA, with your tags, agents and mailboxes by ID. | Read            |                 |
| `create_sla`           | Create an SLA policy with a response or resolution time target.                                                       | Manage Settings |                 |
| `update_sla`           | Replace an SLA policy's whole document, including turning it on or off.                                               | Manage Settings | Yes             |
| `delete_sla`           | Permanently delete an SLA policy and cancel its pending checks. Tickets already tagged SLA Violation keep the tag.    | Manage Settings | Yes             |

### Reports, plan, and integrations

*Available since 2026-10-27.*

| Tool                | What it does                                                                                                            | Needs | Asks to confirm |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----- | --------------- |
| `get_simple_report` | A company support summary for a date range, with the same numbers as the Reports page.                                  | Read  |                 |
| `get_subscription`  | Read your plan, its status, trial or period end date, seat and mailbox usage against your limits, and enabled features. | Read  |                 |
| `list_integrations` | List your integrations (Shopify, HubSpot, Salesforce, Slack, WooCommerce, Zapier) and the mailboxes each serves.        | Read  |                 |

{% hint style="info" %}
Plan and billing changes aren't available through MCP. They happen on [keeping.com](https://keeping.com).
{% endhint %}

## How workflow and SLA documents work

Your assistant creates a workflow or an SLA by sending one document that describes the whole rule, the same way you would fill in the editor in Keeping. It calls `describe_workflow_options` or `describe_sla_options` first to get the vocabulary, the rules, and your company's tag, agent and mailbox IDs. The conditions and actions are the ones described in [Workflow conditions](/help/workflows/workflow-conditions.md), [Workflow actions](/help/workflows/workflow-actions.md), [SLA conditions](/help/service-level-agreements/sla-conditions.md) and [SLA actions](/help/service-level-agreements/sla-actions.md).

Three things to know:

* **Updates replace the whole document.** `update_workflow` and `update_sla` take every field, not only the change, so the assistant reads the current document with `get_workflow` or `get_sla` first.
* **Changing, deleting and reordering ask you to confirm.** Creating a new workflow or SLA does not.
* **Deleting an SLA keeps the SLA Violation tag** on tickets that were already late, and cancels the checks that were still pending.

In both documents, every condition block must match for the rule to apply, and inside a block any one condition is enough.

### Example: a workflow

This is what the assistant sends to `create_workflow` for "when a new email about an invoice arrives from 9 am, make it high priority, assign it to Dana and tag it Billing". The IDs come from `describe_workflow_options`.

```json
{
  "name": "Invoices to Dana, high priority",
  "mailbox_ids": [12],
  "status": "active",
  "document": {
    "trigger": {"type": "initial_email"},
    "condition_blocks": [
      {"conditions": [
        {"field": "conversation subject", "operator": "contains", "value": "invoice"},
        {"field": "message body", "operator": "contains", "value": "invoice"}
      ]},
      {"conditions": [
        {"field": "ticket arrives on or after", "value": {"time": "09:00", "time_zone": "America/New_York"}}
      ]}
    ],
    "actions": [
      {"type": "priority", "priority": "high"},
      {"type": "assign", "role_id": 9},
      {"type": "tag", "tag_id": 34}
    ]
  }
}
```

The trigger is one of the **Runs when** choices in the editor. A workflow that runs on an email needs at least one condition; one that runs on a ticket change (a tag applied, a teammate assigned, a priority set) takes none. Actions run in the order given.

### Example: an SLA

This is what the assistant sends to `create_sla` for "VIP customers get a first reply within four business hours; assign late tickets to Dana and notify Sam".

```json
{
  "name": "VIP first reply within 4 business hours",
  "mailbox_id": 12,
  "status": "active",
  "document": {
    "target": {"field": "first response time", "minutes": 240, "time_type": "business"},
    "condition_blocks": [
      {"conditions": [{"field": "tag", "value": 34}]},
      {"conditions": [
        {"field": "customer email", "operator": "ends with", "value": "@bigcorp.com"},
        {"field": "priority", "value": "high"}
      ]}
    ],
    "actions": [
      {"type": "assign", "role_id": 9},
      {"type": "notify", "role_id": 7}
    ]
  }
}
```

An SLA watches one mailbox and has one timer: first response time or resolution time, in minutes, counted in calendar or business time. Business time uses the business hours in your company settings, so it is rejected until those are set. The SLA Violation tag is added automatically to a ticket that breaks the SLA; it is not an action you add.

*Tool list checked against the server on 2026-10-30.*