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

# Pylon MCP

Expose Pylon data to AI tools and assistants via Model Context Protocol.

## Pylon MCP Server

The Pylon MCP Server exposes Pylon data to AI tools that support the Model Context Protocol (e.g. Claude, ChatGPT, Cursor). AI tools authenticate with your Pylon account via OAuth and can read and update issues, accounts, contacts, knowledge base articles, tasks and projects, triggers, and more within the data you can see in Pylon.

* **Server URL (US):** `https://mcp.usepylon.com`
* **Server URL (EU):** `https://mcp.eu.usepylon.com`
* **Auth:** OAuth 2.0 (AuthKit). Actions are performed on behalf of the authenticated user; access is scoped to the same data as in the Pylon dashboard.
* **Transport:** Streamable HTTP (stateless; no server-side sessions).

### Setup in Pylon

Open **Settings > AI Controls > MCP Server** in Pylon. Copy your workspace's regional MCP URL from **Installation** and use it in your AI tool. For client-specific instructions, see [connecting to the Pylon MCP Server](https://support.usepylon.com/articles/2407390554-connecting-to-the-pylon-mcp-server?lang=en).

### What you can do with MCP today

Member and Admin users need the `MCP Access` [role](https://docs.usepylon.com/pylon-docs/platform/roles-and-user-management#member-permissions-2) enabled to connect. Each tool also requires the permissions for its operation. Access follows the same scoping as the Pylon dashboard — the MCP cannot return data that the authenticated user cannot already see, or perform writes that the authenticated user cannot already write in the UI.

Some tools also require a plan feature, noted in their section. Rate limits apply per tool, elaborated below.

#### **Issues**

AI tools can send replies to customers and post internal notes for your team. A reply goes straight to the customer on the issue's channel (Slack, email, chat, etc.) and can't be unsent, so AI tools are instructed to show you the exact message and get your approval before sending it. Most AI tools also ask you to confirm each reply.

| **Tool**                     | **Read / Write** | **Description**                                                                                                                        |
| ---------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **`search_issues`**          | Read             | Search issues by keyword (titles, messages, tags, and names) and by state, account, assignee, tags, custom fields, etc.                |
| **`get_issue`**              | Read             | Fetch a single issue by ID or number; set `include_messages=true` to include its conversation                                          |
| **`get_issue_messages`**     | Read             | Fetch an issue's full message history in order, including the original To and Cc recipients of email messages                          |
| **`get_issue_statuses`**     | Read             | List the default and custom issue statuses configured for your organization                                                            |
| **`create_issue`**           | Write            | Create a new issue                                                                                                                     |
| **`update_issue`**           | Write            | Update issue fields (status, assignee, team, priority, tags, custom fields, …); tags can be replaced or added and removed individually |
| **`snooze_issue`**           | Write            | Snooze an issue until a future time. It moves to On hold and returns to Waiting on you when the snooze ends                            |
| **`send_issue_reply`**       | Write            | Send a reply to the customer on an issue. For email issues, recipients follow reply-all                                                |
| **`send_issue_note`**        | Write            | Post an internal note on an issue, visible only to your team                                                                           |
| **`get_issue_threads`**      | Read             | List an issue's internal threads                                                                                                       |
| **`create_issue_thread`**    | Write            | Create an internal thread on an issue, optionally synced to an internal Slack channel                                                  |
| **`get_issue_followers`**    | Read             | List an issue's followers                                                                                                              |
| **`update_issue_followers`** | Write            | Add or remove teammates as followers of an issue                                                                                       |
| **`link_product_issue`**     | Write            | Link a Linear, Jira, GitHub, Asana, or Shortcut ticket to an issue                                                                     |

#### **Accounts**

| **Tool**                   | **Read / Write** | **Description**                                                         |
| -------------------------- | ---------------- | ----------------------------------------------------------------------- |
| **`search_accounts`**      | Read             | Search accounts by name, domain, external ID, tags, custom fields, etc. |
| **`get_account`**          | Read             | Fetch a single account, including custom field values                   |
| **`create_account`**       | Write            | Create a new account                                                    |
| **`update_account`**       | Write            | Update account fields                                                   |
| **`upload_account_files`** | Write            | Upload files (e.g. PDFs) to an account's Files tab                      |
| **`create_attachment`**    | Write            | Upload a file and get back an attachment ID and URL                     |

#### **Account Notebooks & Notes**

Requires Account Intelligence and permission to read or update the account.

| **Tool**                | **Read / Write** | **Description**                                                                    |
| ----------------------- | ---------------- | ---------------------------------------------------------------------------------- |
| **`get_notebook`**      | Read             | List an account's notebooks, fetch widget configuration, or include widget content |
| **`save_account_note`** | Write            | Create a timestamped account note or edit its title or HTML body                   |

Use `get_notebook` with the account and a `notebook_id` to read its widget configuration. Set `include_content=true` with that `notebook_id` to return widget contents in the response's `content` field, including the most recent 20 timestamped notes per widget. Notebook reads can refresh missing or pending AI insights when you also have account write permission. Wait about 30 seconds and repeat the call with `include_content=true` to retrieve refreshed content.

Use `save_account_note` without `note_id` to create a note; `account_id`, `widget_id`, and nonempty `content_html` are required. Use `get_notebook` to find a `timestamped_notes` widget ID, and include its content to find existing note IDs.

To edit a note, supply a nonempty `note_id` and `title` and/or `content_html`. Omit either field to preserve it; send an empty `title` to clear the title. An empty `content_html` is rejected, and HTML is sanitized. `account_id` and `widget_id` apply only when creating. An explicitly empty `note_id` is rejected; omit it to create.

#### **Contacts, Users & Teams**

| **Tool**              | **Read / Write** | **Description**                                                                                         |
| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
| **`search_contacts`** | Read             | Search contacts by name, email, phone, account, and more                                                |
| **`get_contact`**     | Read             | Fetch a contact by ID                                                                                   |
| **`create_contact`**  | Write            | Create a contact on an account. Contacts created this way don't get customer portal access or an invite |
| **`update_contact`**  | Write            | Update a contact's name, account, or custom fields                                                      |
| **`search_users`**    | Read             | Search Pylon team members by name, or look one up by email                                              |
| **`get_user`**        | Read             | Fetch a Pylon team member by ID                                                                         |
| **`get_me`**          | Read             | Return the authenticated user and their organization                                                    |
| **`search_teams`**    | Read             | Look up teams by name, or list all teams                                                                |

#### **Knowledge Base**

Reading requires permission to view the knowledge base. Drafting, publishing, and changing article settings require the same edit and publish permissions as the Pylon knowledge base editor.

| **Tool**                         | **Read / Write** | **Description**                                                                                  |
| -------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------ |
| **`list_knowledge_bases`**       | Read             | List the knowledge bases you can read                                                            |
| **`list_collections`**           | Read             | List collections in a knowledge base                                                             |
| **`get_collection`**             | Read             | Fetch a collection's details and visibility settings                                             |
| **`list_collection_contents`**   | Read             | List the articles and sub-collections directly inside a collection                               |
| **`search_articles`**            | Read             | Full-text search across article titles and content                                               |
| **`get_article`**                | Read             | Fetch an article's content and visibility settings, by ID or by the identifier in its public URL |
| **`get_related_links`**          | Read             | List the tracked websites and external sites configured for your org                             |
| **`save_draft_article`**         | Write            | Create a draft article, or save new draft content for an existing article without publishing     |
| **`publish_article`**            | Write            | Publish an article's content                                                                     |
| **`update_article_settings`**    | Write            | Change an article's visibility and AI agent access                                               |
| **`move_article_to_collection`** | Write            | Move an article into a different collection                                                      |

#### **Feature Requests**

Requires the Feature Requests plan feature.

| **Tool**                              | **Read / Write** | **Description**                                                                                                  |
| ------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| **`search_feature_requests`**         | Read             | Search feature requests by status and other filters                                                              |
| **`get_feature_request`**             | Read             | Fetch a feature request, including its evidence                                                                  |
| **`get_feature_request_statuses`**    | Read             | List the feature request statuses configured for your org                                                        |
| **`create_feature_request`**          | Write            | Create a feature request, optionally with a customer issue or account as its first evidence                      |
| **`update_feature_request`**          | Write            | Update a feature request's title, description, status, or custom fields                                          |
| **`add_evidence_to_feature_request`** | Write            | Record that a customer asked for an existing feature request, linking the issue or account                       |
| **`merge_feature_requests`**          | Write            | Merge duplicate feature requests into one; evidence and linked tickets move over and the duplicates are archived |

#### **Tasks & Projects**

Requires Account Intelligence.

| **Tool**                    | **Read / Write** | **Description**                                                                            |
| --------------------------- | ---------------- | ------------------------------------------------------------------------------------------ |
| **`search_tasks`**          | Read             | Search tasks across your organization, or for one account or project                       |
| **`get_task`**              | Read             | Fetch a task, including its subtasks                                                       |
| **`get_task_statuses`**     | Read             | List the default and custom task statuses                                                  |
| **`save_task`**             | Write            | Create a task or update only the fields you provide                                        |
| **`delete_task`**           | Write            | Delete a task and its subtasks                                                             |
| **`search_projects`**       | Read             | Search or list projects by name, account, owner, and status                                |
| **`get_project`**           | Read             | Fetch a project's details and progress                                                     |
| **`save_project`**          | Write            | Create a project for an account, optionally from a template, or update an existing project |
| **`get_project_templates`** | Read             | List project templates                                                                     |
| **`get_milestones`**        | Read             | List milestones for a project or account, or fetch one by ID                               |
| **`save_milestone`**        | Write            | Create a milestone in a project or update an existing milestone                            |

For `save_task`, `save_project`, and `save_milestone`, omit the object's ID to create it. Supply a nonempty `task_id`, `project_id`, or `milestone_id` to update only the fields you provide; omitted fields keep their current values. An explicitly empty ID is rejected. Read the existing object before updating it.

* **Tasks:** Creating requires `title`. `parent_task_id` applies only when creating. `completed_at` applies only when updating an already completed task and cannot be cleared. On updates, send an empty string for `due_date`, `assignee_id`, or an account, project, or milestone assignment to clear it.
* **Projects:** Creating always requires `account_id`. Also provide `name`, or supply `project_template_id` to copy a template's milestones, tasks, and subtasks. `account_id`, `owner_type`, and `project_template_id` apply only when creating; `is_archived` applies only when updating. On updates, send an empty string for `start_date`, `end_date`, or `owner_id` to clear it.
* **Milestones:** Creating requires `name` and `project_id`. `project_id` and `account_id` apply only when creating. On updates, send an empty `due_date` to clear it.

Tasks and projects accept `custom_fields` when creating or updating. Use `get_custom_fields` with `object_type` set to `task` or `project` to discover field slugs and values first.

#### **Call Recordings**

Requires Account Intelligence. Access follows the same per-recording permissions as in Pylon.

| **Tool**                     | **Read / Write** | **Description**                                                                                                 |
| ---------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------- |
| **`search_call_recordings`** | Read             | Search call recordings by title or account name, or by what was said during the call                            |
| **`get_call_recording`**     | Read             | Fetch a recording's details, participants, summary, and full transcript, or list an account's recent recordings |

#### **Surveys**

| **Tool**                   | **Read / Write** | **Description**                           |
| -------------------------- | ---------------- | ----------------------------------------- |
| **`list_surveys`**         | Read             | List NPS, CSAT, and custom surveys        |
| **`get_survey_responses`** | Read             | Fetch survey responses by survey or issue |

#### **Triggers**

New triggers are created disabled so you can review them in Pylon before turning them on.

Use `validate_trigger` before saving. `save_trigger` supports custom trigger groups and flat branches with compatible actions, delays, and conditions. Configure default or special groups, recurring schedules, phone/IVR triggers, nested branches, and background-agent investigations in Pylon instead. Updating a trigger replaces its editable configuration while preserving its group and enabled state.

| **Tool**                       | **Read / Write** | **Description**                                                                              |
| ------------------------------ | ---------------- | -------------------------------------------------------------------------------------------- |
| **`list_trigger_groups`**      | Read             | List trigger groups                                                                          |
| **`list_triggers`**            | Read             | List triggers with their kickoffs, actions, and firing statistics                            |
| **`get_trigger`**              | Read             | Fetch a trigger's full configuration                                                         |
| **`describe_trigger_kickoff`** | Read             | List the available kickoff types, or describe one kickoff's supported conditions and actions |
| **`describe_trigger_action`**  | Read             | List the available action types, or describe one action's variables and compatible kickoffs  |
| **`get_trigger_examples`**     | Read             | Example payloads for common trigger patterns                                                 |
| **`validate_trigger`**         | Read             | Validate a `save_trigger` payload without saving it                                          |
| **`save_trigger`**             | Write            | Create a disabled trigger, or replace an existing trigger's configuration                    |

#### **Macros**

Discover saved macros and create or edit their message text. Reading macro details requires permission to view macro settings; saving requires permission to edit macro settings and the macro itself.

| **Tool**          | **Read / Write** | **Description**                                                                            |
| ----------------- | ---------------- | ------------------------------------------------------------------------------------------ |
| **`list_macros`** | Read             | List visible macro summaries and groups, with optional name search and group filtering     |
| **`get_macro`**   | Read             | Read stored HTML, text type, visibility, configured action types, and attachment summaries |
| **`save_macro`**  | Write            | Create a text-only macro or edit an existing macro's name, message text, or text type      |

`list_macros` accepts `query`, `macro_group_id`, `limit` (default 25, maximum 100), and `cursor`. Continue with the returned cursor and the same filters when `has_next_page` is true.

To create a macro, provide `name`, `macro_group_id` from `list_macros`, and either Markdown `text` or HTML `text_html`. New macros are organization-visible and default to the `reply` text type; `note` and `email` are also supported.

To edit a macro, first call `get_macro`, then supply its `macro_id` and only the fields you want to change. Use `text_html` when editing returned HTML to preserve rich formatting and template metadata. `text` and `text_html` are mutually exclusive and both are sanitized. Explicitly empty content, or content with neither text nor a safe image after sanitization, is rejected. Omit both to preserve existing message text.

Existing actions, conditions, visibility, editor permissions, group, and attachments are preserved. Change those settings or remove files in Pylon. Attachment summaries are read-only and limited to 100 entries; check `attachment_count` and `has_more_attachments` for additional files. These tools do not execute macros, resolve template variables against an issue, or send messages.

#### **Filters, Fields & Tags**

These tools help an AI tool build valid filters and field values for the tools above.

| **Tool**                    | **Read / Write** | **Description**                                                                    |
| --------------------------- | ---------------- | ---------------------------------------------------------------------------------- |
| **`build_filter`**          | Read             | Build a validated filter for any object type                                       |
| **`get_filter_attributes`** | Read             | Fields, operators, and reference types available when filtering an object type     |
| **`get_custom_fields`**     | Read             | List custom field definitions for an object type                                   |
| **`list_tags`**             | Read             | List issue, account, or knowledge base article tags, or look one up by exact value |

For custom-field filters or updates, use `get_custom_fields` to discover the field definitions and valid values first. Use `get_filter_attributes` and `build_filter` for filters beyond a search tool's direct arguments. Pass the returned `filter_json` to search tools that accept it, such as `search_issues`.

Search tools use the argument names shown in their schemas. Some accept common aliases, but use the documented names for new integrations. For paginated tools, continue with the returned `cursor` while keeping your filters unchanged, and stop when `has_next_page` is false.

Check `search_issues` response warnings before interpreting an empty result. An unmatched account, assignee, or requester name means the name lookup found no record; it does not confirm that the intended account or person has no matching issues. Follow the warning's recovery guidance and retry the search.

#### **Audit Logs**

Requires Admin permission. Full audit log history is available on the Enterprise plan; otherwise, searches cover only the last 30 days. A search starting earlier than that limit returns an error.

| **Tool**                     | **Read / Write** | **Description**                                                                      |
| ---------------------------- | ---------------- | ------------------------------------------------------------------------------------ |
| **`list_audit_log_actions`** | Read             | Discover exact supported action names, regardless of recorded events                 |
| **`search_audit_logs`**      | Read             | Search recorded actions and changes in your organization by object, action, and time |

Use `object_id` to find changes to an issue or account. Resolve a ticket number to its ID with `get_issue` first. Use `actions` for exact action names or `action_contains` to discover names by substring. `happened_after` and `happened_before` accept RFC3339 timestamps, such as `2026-10-01T00:00:00Z`. Filters combine with AND; within `actions`, an entry can match any supplied action. Actor IDs are returned, but actor filtering is not supported.

Results include `audit_logs`, the current page's `count`, and `has_next_page`. The default `limit` is 25 and the maximum is 100. Continue with the returned `cursor` and unchanged filters. Set `include_metadata` to `true` for action-specific details; metadata is omitted by default. When history is restricted, `history_limited_to_days` is `30`.

**Find action names**

Call `list_audit_log_actions` for the authoritative catalog of action names supported by audit-log search. It includes names regardless of whether matching events exist in your workspace and excludes hidden actions. It requires the same Admin permission as `search_audit_logs`.

Use optional `query` for a case-insensitive substring match on names. Results are alphabetical; `limit` defaults to 50 and has a maximum of 100. Continue with the returned `cursor` and unchanged `query` while `has_next_page` is true to read the full catalog. The `count` is the number of names on the current page.

The `actions` filter takes exact strings from this catalog or a returned entry's `action` field. Copy those values rather than guessing from a UI label: some stored action names differ from the labels shown in Pylon.

Common exact action names include:

| Change                               | Exact action name             |
| ------------------------------------ | ----------------------------- |
| One issue custom field changed       | `Issue Custom Field Updated`  |
| Multiple issue custom fields changed | `Issue Custom Fields Updated` |
| Issue assigned                       | `Success Issue Assigned`      |
| Issue closed                         | `Success Ticket Closed`       |
| Issue tags changed                   | `Issue Tags Changed`          |
| Account owner changed                | `Account Owner Changed`       |
| Account created                      | `Account Created`             |
| Macro edited                         | `Macro Updated`               |

For example, call `list_audit_log_actions` to discover custom-field action names:

```json
{
  "query": "Custom Field",
  "limit": 50
}
```

Then copy returned names into `search_audit_logs.actions`:

```json
{
  "actions": ["Issue Custom Field Updated", "Issue Custom Fields Updated"],
  "include_metadata": true,
  "limit": 25
}
```

These are examples, not a complete catalog. Use `list_audit_log_actions` for the full catalog. A listed action may have no recorded events in your workspace; search results remain subject to your history access. In `search_audit_logs`, `action_contains` searches action names only, not attributes, field values, or metadata.

Audit logs show recorded events, not a complete explanation of every automation or field change.

#### **Contact Pylon Support**

| **Tool**                    | **Read / Write** | **Description**                                        |
| --------------------------- | ---------------- | ------------------------------------------------------ |
| **`submit_support_ticket`** | Write            | Send a request about Pylon to Pylon's own support team |

Sign in as a human Pylon user with an email address. Before submission, your AI tool must obtain your agreement to send the request specifically to Pylon support. Use `create_issue` for tickets in your own workspace. Share only relevant approved context, and reuse the same `idempotency_key` and unchanged request details when retrying a submission to avoid duplicates.

#### AI Agents

AI agent backtesting through MCP requires AI Agents and Backtesting for your organization, plus MCP Access and the relevant agent permissions. `get_agent_issue` needs permission to view AI agents. Issue-backed cases and agent activity follow your issue visibility.

| Tool                                 | Read / Write | Description                                                                                                      |
| ------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------- |
| **`list_agents`**                    | Read         | Find the AI agent ID to test.                                                                                    |
| **`list_agent_variations`**          | Read         | Find customer-visible variation IDs for an agent.                                                                |
| **`list_backtest_datasets`**         | Read         | Find datasets and their case counts.                                                                             |
| **`create_backtest_dataset`**        | Write        | Create an empty dataset.                                                                                         |
| **`add_issues_to_backtest_dataset`** | Write        | Snapshot readable issues as cases (up to 100 per dataset).                                                       |
| **`run_backtest`**                   | Write        | Start asynchronous runs for one or more agent configurations.                                                    |
| **`list_backtests`**                 | Read         | Find customer backtests, their runs, and progress.                                                               |
| **`get_backtest_results`**           | Read         | Get paginated progress and results for a backtest or run.                                                        |
| **`get_backtest_case`**              | Read         | Compare every agent result for one case.                                                                         |
| **`get_playground`**                 | Read         | Inspect the full message, tool, and event timeline for a result.                                                 |
| **`get_agent_issue`**                | Read         | See an AI agent's full activity on a real issue: tool calls, runbook steps, escalations, messages, and outcomes. |
| **`update_backtest_case_feedback`**  | Write        | Rate one case result thumbs up or thumbs down, or clear its rating.                                              |

### **Combined tools**

Some tools were combined to keep the list short for AI tools. The old names still work for existing integrations and scripts, but no longer appear in an AI tool's tool list. Use the new tool for anything new.

| **Old tool**                                                                       | **Use instead**                                                    |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `create_task`                                                                      | `save_task` without `task_id`                                      |
| `update_task`                                                                      | `save_task` with `task_id`                                         |
| `create_project`                                                                   | `save_project` without `project_id`                                |
| `update_project`                                                                   | `save_project` with `project_id`                                   |
| `create_milestone`                                                                 | `save_milestone` without `milestone_id`                            |
| `update_milestone`                                                                 | `save_milestone` with `milestone_id`                               |
| `create_account_note`                                                              | `save_account_note` without `note_id`                              |
| `update_account_note`                                                              | `save_account_note` with `note_id`                                 |
| `get_notebook_content`                                                             | `get_notebook` with `notebook_id` and `include_content=true`       |
| `create_trigger`, `update_trigger`                                                 | `save_trigger`                                                     |
| `list_trigger_kickoffs`, `list_trigger_actions`                                    | `describe_trigger_kickoff`, `describe_trigger_action` with no type |
| `get_issue_filter_attributes` and the other `get_<object>_filter_attributes` tools | `get_filter_attributes` with `object_type`                         |
| `get_tasks`, `get_projects`                                                        | `search_tasks`, `search_projects`                                  |
| `create_project_from_template`                                                     | `save_project` with `project_template_id` (omit `project_id`)      |
| `get_milestone`                                                                    | `get_milestones` with `milestone_id`                               |
| `get_article_by_identifier`                                                        | `get_article` with `identifier`                                    |
| `create_draft_article`, `create_draft_article_version`                             | `save_draft_article`                                               |
| `list_teams`                                                                       | `search_teams`                                                     |
| `get_tag`                                                                          | `list_tags` with `value`                                           |

### **Rate limits**

Rate limits are applied per tool and per organization to keep the MCP server healthy under bursty AI traffic. Tool throttling returns a JSON-RPC error with code **`-32000`**. Its message identifies the tool and tells you how many seconds to wait before retrying. Wait for that delay before retrying the call.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.usepylon.com/pylon-docs/integrations/pylon-mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.