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. Pick Pylon from the marketplace picker.

  4. Fill in the identity fields (name, 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.

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. Results come in pages, 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.

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.

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.

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

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.

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