Agentic Data Plane
Preview

Pylon Managed MCP Server

The Pylon managed MCP server lets agents search and read Pylon issues, accounts, contacts, and knowledge-base articles through a shared API token. Write tools, 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

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

Before you create the server, make sure you have:

  • A Pylon workspace served from Pylon’s US API host. See Limitations.

  • The Admin role in Pylon, because Pylon allows only Admins to create API tokens.

  • 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 describes how to list knowledge bases and their IDs.

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. 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

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.

Configure from the CLI

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

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

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

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

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

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

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.

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

The examples in this section assume 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

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

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

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

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

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

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:

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

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

  • 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