# Pylon Managed MCP Server

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt)

---
title: Pylon Managed MCP Server
latest-operator-version: v26.2.4
latest-console-tag: v3.12.0
latest-connect-version: 4.113.1
latest-redpanda-tag: v26.2.4
docname: managed/pylon
page-component-name: agentic-data-plane
page-version: master
page-component-version: master
page-component-title: Agentic Data Plane
page-relative-src-path: managed/pylon.adoc
page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/pylon.adoc
description: Connect agents to Pylon issues, accounts, contacts, and knowledge-base articles with a shared API token. Writes stay off until you enable them.
page-topic-type: how-to
personas: agent_builder, platform_engineer
learning-objective-1: Configure the Pylon managed MCP server with an API token stored in the secret store
learning-objective-2: Configure which tool groups the server exposes with the write, customer-reply, and knowledge-base settings
learning-objective-3: Search, read, and update Pylon issues from the Inspector or an agent
page-git-created-date: "2026-09-18"
page-git-modified-date: "2026-10-08"
---

<!-- Source: https://docs.redpanda.com/agentic-data-plane/connect/managed/pylon.md -->

The **Pylon** managed [MCP server](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#mcp-server) lets [agents](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#ai-agent) search and read Pylon issues, accounts, contacts, and knowledge-base articles through a shared API token. Write [tools](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#tool), customer-visible replies, and knowledge-base tools stay off until you enable them, so you decide how much an agent can change.

After reading this page, you will be able to:

-   Configure the Pylon managed MCP server with an API token stored in the secret store

-   Configure which tool groups the server exposes with the write, customer-reply, and knowledge-base settings

-   Search, read, and update Pylon issues from the Inspector or an agent


## [](#what-this-mcp-server-does)What this MCP server does

Wraps the Pylon REST API so an agent can:

-   Search issues with structured filters and free text, and read an issue with its full conversation thread.

-   Look up accounts, contacts, and Pylon agent users.

-   Read the custom-field definitions and allowed option values configured in your workspace.

-   Create and update issues, accounts, and contacts, add internal notes, reply to customers, and create or update knowledge-base articles, after you turn on the write settings.


The server is read-only by default. Turning on `Allow writes` adds the tools that create and update records and add internal notes. Customer-visible replies need a second setting, `Allow customer replies`, because a reply goes to the requester and is a different class of action from an internal edit. Knowledge-base tools appear only when you set a knowledge base ID.

Every call runs under one API token rather than as any Pylon user. Pylon shows the token’s name on each action the agent performs, so actions carry no per-user attribution and users see no consent flow.

The server trims responses for agents. Issue, message, and article bodies arrive as Markdown, and the server drops routing metadata, follower lists, and other verbose fields.

It is not a Pylon administration tool. You manage ticket forms, macros, teams, tags, and user roles in Pylon.

## [](#prerequisites)Prerequisites

Before you create the server, make sure you have:

-   A Pylon workspace served from Pylon’s US API host. See [Limitations](#limitations).

-   The Admin role in Pylon, because [Pylon allows only Admins to create API tokens](https://docs.usepylon.com/pylon-docs/developer/api).

-   One Agentic Data Plane secret-store entry for the token, named in `UPPER_SNAKE_CASE`, for example `PYLON_API_TOKEN`.

-   Optional: The ID of the knowledge base if the agent needs to read or write its articles. Pylon’s [knowledge-base API reference](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/knowledge-base) describes how to list knowledge bases and their IDs.


## [](#get-a-pylon-api-token)Get a Pylon API token

Create the token in Pylon, then store it in Agentic Data Plane:

1.  In the Pylon dashboard, open the API tokens page at `[https://app.usepylon.com/settings/api-tokens](https://app.usepylon.com/settings/api-tokens)`. Only Pylon Admins can create tokens.

2.  Create a token and name it after the agent that uses it, for example `redpanda-support-agent`. Pylon labels every action the token performs with this name.

3.  Copy the token value.

4.  Store it in the Agentic Data Plane secret store under a name like `PYLON_API_TOKEN`.


The token acts under its own name rather than as a user. Limit what an agent can change with the `Allow writes` and `Allow customer replies` settings when you configure the server, not with the token.

If you want the knowledge-base tools, also note the ID of the knowledge base. You can list your knowledge bases and their IDs with Pylon’s knowledge-base API, and the create form’s help text describes where the ID appears in the Pylon app.

## [](#configure)Configure

Create a new Pylon MCP server in Agentic Data Plane:

1.  Open **MCP servers** in the sidebar.

2.  Click **Add MCP server**.

3.  Click the **Pylon** card in the marketplace picker.

4.  Replace the suggested `Name`, and optionally add a `Description`.

5.  In the Pylon configuration form:

    | Field | Notes |
    | --- | --- |
    | API token | Secret-store reference for the Pylon API token, in UPPER_SNAKE_CASE, for example PYLON_API_TOKEN. Leave any other authentication field at its default. The server always sends the token as a bearer token. |
    | Knowledge base ID | Optional. Enables the knowledge-base article tools. Leave it empty to omit them. |
    | Allow writes | Off by default. When on, the server also registers the tools that create and update issues, accounts, contacts, and knowledge-base articles, and the tool that adds internal notes. |
    | Allow customer replies | Off by default. When on together with Allow writes, the server also registers reply_to_issue, which sends a customer-visible reply under the token’s name. Leave it off to restrict an agent to internal notes. |

6.  Click **Create server**.


The create form turns `Enable code mode` on by default for this server type. `rpk ai mcp-server create` leaves it off unless you pass `--code-mode`. See [Code Mode](https://docs.redpanda.com/agentic-data-plane/gateway/code-mode/).

### [](#configure-from-the-cli)Configure from the CLI

Run `rpk ai mcp-server create` with the Pylon `--managed.config` payload:

```bash
rpk ai mcp-server create acme-pylon --enabled --managed.config '{
  "@type": "type.googleapis.com/redpanda.mcps.pylon.v1.PylonMCPConfig",
  "api_token": {
    "key_secret_ref": "PYLON_API_TOKEN"
  },
  "knowledge_base_id": "<knowledge-base-id>",
  "allow_writes": true,
  "allow_customer_replies": false
}'
```

Replace `<knowledge-base-id>` with the ID of your Pylon knowledge base. Omit `knowledge_base_id`, `allow_writes`, and `allow_customer_replies` for a read-only server without knowledge-base tools. Pass `--enabled`, because a server created without it stays disabled until you update it.

## [](#tools)Tools

Which tools the server registers depends on the `Allow writes`, `Allow customer replies`, and `Knowledge base ID` settings. An agent sees only the registered tools in its tool list.

### [](#always-available)Always available

| Tool | Description |
| --- | --- |
| search_issues | Search issues with a structured filter, free text, or both. Filter by account, assignee, team, type, tags, and state, exclude states, tags, or teams, and bound the results by creation, update, or resolution time. Returns a page of issues and a cursor for the next page. |
| list_issues | Return every issue created in a time window. Pass both bounds, and keep the window at or under 365 days. A page holds 100 issues unless you set limit, so follow next_cursor until has_next_page is false. Use search_issues for anything other than a bulk export by creation date. |
| get_issue | Fetch one issue by its ID or its issue number. Set include_messages to true to include the full conversation thread. |
| get_issue_messages | Return an issue’s conversation thread, oldest first, with optional paging. Accepts the issue ID or the issue number. Omitting limit returns the whole thread. |
| search_accounts | Search accounts (companies) by name, domain, or tags. |
| get_account | Fetch one account by ID. |
| search_contacts | Search contacts (customer users) by name, email, or account. |
| get_contact | Fetch one contact by ID. |
| list_users | List the Pylon agent users in the workspace. The results leave out deactivated users, so a page can hold fewer users than limit asks for and still point at a next page. |
| get_user | Fetch one Pylon user by ID. |
| get_custom_fields | Return the custom-field definitions for an object type (issue, account, contact, task, project, or opportunity), including the allowed options of select and multiselect fields. Call it before writing a custom field. |
| get_me | Return the Pylon workspace the token belongs to. Useful for confirming that the token works. |

### [](#with-allow-writes)With `Allow writes`

| Tool | Description |
| --- | --- |
| create_issue | Open a new issue with a subject and a Markdown body, plus optional account, requester, assignee, priority, tags, and custom fields. |
| update_issue | Change an issue’s subject, state, assignee, account, requester, type, tags, or custom fields. Only the fields you pass change, and passing tags replaces the whole tag list. The tool accepts an unknown custom-field option silently and changes nothing, so check get_custom_fields first. |
| add_issue_note | Post an internal note on an issue. Notes are visible to Pylon agents only, never to the requester. |
| create_account | Create an account with a name and optional domains, tags, and custom fields. |
| update_account | Change an account’s tags or custom fields. |
| create_contact | Create a contact with a name, an email address, and optional custom fields. |
| update_contact | Change a contact’s custom fields. |

### [](#with-allow-writes-and-allow-customer-replies)With `Allow writes` and `Allow customer replies`

| Tool | Description |
| --- | --- |
| reply_to_issue | Send a customer-visible reply on an issue. Requires the message_id of the message you are replying to, which you get from get_issue with include_messages or from get_issue_messages. The reply reaches the requester under the token’s name. The server reads the issue before it sends anything, so the call fails if the issue can’t be read, whatever its source. On an issue that came in by email, the server addresses the reply to the requester. A caller can’t choose or add recipients. If the server can’t determine that address, the call fails and nothing is sent. See Troubleshooting. |

### [](#with-a-knowledge-base-id)With a knowledge base ID

| Tool | Description |
| --- | --- |
| list_knowledge_base_articles | List the articles in the configured knowledge base. Returns metadata only. |
| get_knowledge_base_article | Fetch one article with its published body as Markdown. |
| create_knowledge_base_article | Also needs Allow writes. Create an article from a title and a Markdown body. Requires an author user ID from list_users or get_me. Pylon saves the article as a draft unless you set is_published to true. |
| update_knowledge_base_article | Also needs Allow writes. Change an article’s title, body, published state, or visibility. |

### [](#paging)Page through results

Each tool that takes a `limit` pages its results. A response carries `next_cursor` and `has_next_page`, and you pass `next_cursor` back as `cursor` to read the following page. A non-empty `next_cursor` always means more records are waiting, because the server clears the cursor when `has_next_page` is false.

Set `limit` to change the page size:

| Tool | Default page | Maximum |
| --- | --- | --- |
| list_issues | 100 | 500 |
| search_issues, search_accounts, search_contacts, list_users | 25 | 100 |
| list_knowledge_base_articles | 25 | 50 |
| get_issue_messages | Whole thread | 1000 |

The server rejects a `limit` outside its range before the call reaches Pylon, along with a missing record ID, a text field longer than its maximum, and a malformed email address on `create_contact`. A subject or article title holds up to 500 characters, an issue, reply, or note body up to 65536, an account or contact name up to 256, and an article body up to 524288. The error names the argument to fix, so an agent can correct its own call instead of reading a bare status code.

## [](#examples)Examples

The examples in this section assume `[https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/acme-pylon](https://aigw.\<cluster-id\>.clusters.rdpa.co/mcp/v1/acme-pylon)` is your MCP server URL and that you have already authenticated to the gateway. Replace `<cluster-id>` with your cluster ID and `$TOKEN` with a gateway access token.

### [](#find-open-issues-for-an-account)Find open issues for an account

Combine a state filter with free text to narrow a queue:

```bash
curl -s https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/acme-pylon \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_issues",
      "arguments": {
        "filter": {
          "account_id": "<account-id>",
          "states": ["new", "waiting_on_you"]
        },
        "search_text": "login",
        "limit": 10
      }
    }
  }'
```

Replace `<account-id>` with the account ID from a `search_accounts` result.

### [](#read-an-issue-with-its-thread)Read an issue with its thread

Use the issue number people quote in Pylon. The thread comes back oldest first.

```bash
curl -s https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/acme-pylon \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_issue",
      "arguments": {
        "issue_id": "10432",
        "include_messages": true
      }
    }
  }'
```

### [](#set-a-custom-field-safely)Set a custom field safely

Read the allowed options first, then write the option’s slug. This example needs `Allow writes`.

```bash
curl -s https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/acme-pylon \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_custom_fields",
      "arguments": { "object_type": "issue" }
    }
  }'
```

Pick a field slug and one of its option slugs from the response, then update the issue:

```bash
curl -s https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/acme-pylon \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "update_issue",
      "arguments": {
        "issue_id": "10432",
        "custom_fields": { "<field-slug>": "<option-slug>" }
      }
    }
  }'
```

Replace `<field-slug>` and `<option-slug>` with a field slug and one of its option slugs from the `get_custom_fields` response.

## [](#troubleshooting)Troubleshooting

Common symptoms and fixes:

| Symptom | What to check |
| --- | --- |
| invalid arguments | An argument is out of range, missing, or too long, for example a limit above the tool’s maximum, an empty record ID, or a reply body over 65536 characters. The message names the argument. For the page-size bounds and text limits, see Page through results. |
| pylon API error (status 401) | The token was revoked or the secret holds the wrong value. Create a new token in Pylon and update the secret under the same name. |
| pylon API error (status 4xx) on a write | Pylon rejected the request. The server drops Pylon’s error message on purpose, so repeat the change in the Pylon app to see the reason, or compare the payload with the field’s definition from get_custom_fields. |
| A tool is missing from the tool list | It sits behind Allow writes, Allow customer replies, or the knowledge base ID. Update the server settings, then call the tool list again. |
| list_issues: start_time and end_time are required or time window exceeds Pylon’s 365-day maximum | Pass both bounds, and split a longer range into windows of at most 365 days. |
| reply_to_issue: message_id is required by the Pylon API | Fetch the thread with get_issue and include_messages or with get_issue_messages, then pass the ID of the message you are replying to. |
| reply to issue: this is an email issue, and its requester has no email address to send the reply to | The issue arrived by email, so the reply needs the requester’s address, and the issue has no requester or the requester’s contact record has no primary email. Add a primary email to the contact in Pylon, or reply from the Pylon app. Posting an internal note with add_issue_note doesn’t need an address. |
| reply to issue: read the issue to address the reply or reply to issue: read the requester’s contact for the email address | The server couldn’t read the issue, or the requester’s contact, to address the reply, so it sent nothing. Confirm the issue ID, and that the API token’s workspace can read the issue and its contacts. Retry after fixing it: no partial reply was sent. |
| create_knowledge_base_article: author_user_id is required by the Pylon API | Pass a Pylon user ID from list_users or get_me. |
| A custom-field write succeeded but nothing changed | The option slug is not one of the field’s allowed options. Read them with get_custom_fields and write the slug, not the label. |
| A call fails because the response is too large | The gateway caps responses at 10 MiB. Lower limit, page with cursor, or use get_issue_messages with a limit instead of include_messages. |

## [](#limitations)Limitations

-   **Regional hosts**: The server connects to Pylon’s US API host only. It does not support workspaces on Pylon’s EU host.

-   **Per-user identity**: The server offers no OAuth option. Every call runs under the shared token, and Pylon attributes every action to the token’s name.

-   **Pylon administration**: You manage ticket forms, macros, teams, tags, user roles, and knowledge-base collections in Pylon.

-   **Priority**: The `create_issue` tool can set one of Pylon’s priorities, but Pylon issues never return a priority value and the server cannot filter on one. Workspaces that track priority in a custom field can read and write it through `custom_fields`.

-   **Custom-field object types**: The `get_custom_fields` tool accepts `issue`, `account`, `contact`, `task`, `project`, and `opportunity`. Pylon’s `meeting` object type is not available.


## [](#next-steps)Next steps

-   [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/)

-   [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/)

-   [Create an Agent](https://docs.redpanda.com/agentic-data-plane/connect/create-agent/)

-   [Plug in an App, Database, or Tool](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/)