Agentic Data Plane

Freshservice Managed MCP Server

The Freshservice managed MCP server lets agents work with your Freshworks Freshservice ITSM instance: list and search tickets, read full ticket detail, create and update tickets, browse CMDB assets, open change requests, and look up support agents.

After reading this page, you will be able to:

  • Configure the Freshservice managed MCP server in API-key or User-OAuth mode

  • Find the Freshservice credentials each mode needs

  • List, create, and update tickets, assets, and changes from the Inspector or an agent

What this MCP server does

The Freshservice managed MCP server wraps the Freshservice REST API v2. It supports these authentication modes:

  • API key (Basic authentication): A long-lived Freshservice API key sent as the HTTP Basic authentication username, with the literal string X as the password. Best for service-account-style use.

  • User OAuth: Per-user Freshservice OAuth tokens resolved from the gateway’s token vault. Best when you want each agent action attributed to the calling end user.

Responses are curated for token efficiency. High-volume fields (routing headers, internal SLA sub-deadlines, spam and email-config flags, agent scoreboards) are dropped before reaching the LLM, and ticket and change descriptions are returned as plain text rather than HTML. Freshservice error response bodies are never forwarded to the caller. Only the HTTP status code is surfaced, so API keys and internal request IDs cannot leak into tool error text.

Prerequisites

Before you create the server, make sure you have:

Get Freshservice credentials

Choose the credential that matches your authentication mode. Use an API key for service-account access, or an OAuth app for User OAuth.

  1. In Freshservice, open Profile Settings.

  2. Copy the value from the API Key section.

  3. Store the key in the Agentic Data Plane secret store under a name like FRESHSERVICE_API_KEY.

The MCP sends the key as the HTTP Basic authentication username with X as the password (base64(<api-key>:X)), which is the Freshservice convention. The API key inherits the permissions of the Freshservice user it belongs to, so use an account with the roles your workflows need (agent, asset, and change permissions).

Option 2: User OAuth

For per-user authentication, create OAuth credentials in Freshworks and a matching custom OAuth provider in Agentic Data Plane:

  1. In your Freshworks organization, create OAuth credentials for Freshservice to obtain a client ID and client secret. Select the scopes listed in the next step. Request only scopes that the credentials include.

  2. In Agentic Data Plane, create a custom OAuth provider. See Configure an OAuth Provider. Use these settings, replacing <org-domain> with your Freshworks organization domain:

    Authorization endpoint: https://<org-domain>/oauth/v2/authorize
Token endpoint:         https://<org-domain>/oauth/v2/token
Scopes:                 freshservice.tickets.view freshservice.tickets.create freshservice.tickets.edit freshservice.assets.view freshservice.changes.create freshservice.agents.manage

    Freshworks expects the client ID and secret in a Basic Authorization header on the token request, so set the token endpoint authentication method to Client Secret (Basic). For read-only use, keep only the .view scopes and freshservice.agents.manage, and drop the tools that write.

  3. Each end user authenticates once through the OAuth flow. Tokens are stored in the gateway’s token vault.

Configure

Create a new Freshservice MCP server in Agentic Data Plane:

  1. Open MCP servers in the sidebar.

  2. Click Add MCP server.

  3. Click the FreshService card in the marketplace picker.

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

  5. In the Freshservice configuration form:

    Field Notes

    Domain

    Your Freshservice host, without the https:// scheme or a trailing slash (for example, mycompany.freshservice.com).

    Auth

    API Key for service-account mode, or User OAuth for per-user mode.

    Key Secret Ref (API-key mode)

    Secret-store reference holding the API key (for example, FRESHSERVICE_API_KEY). UPPER_SNAKE_CASE.

    User OAuth fields (User-OAuth mode)

    The OAuth provider you configured, and the minimum scopes a user’s connection must have. Every required scope must also be in the provider’s scopes.

  6. If the form shows Queryable, Enabled is on. Turn it off unless your agents need the two SQL tools. See Expose Freshservice data as SQL tables.

  7. Click Create server.

Configure from the CLI

For a managed server, set the authentication method inside the --managed.config JSON. The auth field is required.

  • API-key mode

  • User-OAuth mode

rpk ai mcp-server create acme-freshservice --enabled --managed.config '{
  "@type": "type.googleapis.com/redpanda.mcps.freshservice.v1.FreshServiceMCPConfig",
  "domain": "mycompany.freshservice.com",
  "api_key": {
    "key_secret_ref": "FRESHSERVICE_API_KEY"
  }
}'
rpk ai mcp-server create acme-freshservice-oauth --enabled --managed.config '{
  "@type": "type.googleapis.com/redpanda.mcps.freshservice.v1.FreshServiceMCPConfig",
  "domain": "mycompany.freshservice.com",
  "user_oauth": {
    "provider_name": "freshservice-prod",
    "required_scopes": ["freshservice.tickets.view", "freshservice.tickets.create", "freshservice.tickets.edit"]
  }
}'

Replace freshservice-prod with the name of the OAuth provider you configured. List only scopes the provider requests. If you require a scope that the provider doesn’t request, tool calls fail with scope_upgrade_required until each user reconnects and grants it. If the Freshworks OAuth credentials don’t include that scope, every tool call keeps failing.

The create form turns Enable code mode on by default for this server type. The rpk ai mcp-server create command has no code-mode flag. To add code mode from the CLI, create a Code MCP server named <server-name>-code with --code.mcp-servers <server-name>. See Code Mode.

Tools

The Freshservice MCP exposes tools across tickets, assets, changes, and agents:

Tool Description

list_tickets

List tickets, with optional status, priority, and page filters. Status and priority are integer codes: status 2 (open), 3 (pending), 4 (resolved), or 5 (closed); priority 1 (low), 2 (medium), 3 (high), or 4 (urgent). See the filter caveat.

get_ticket

Fetch one ticket with its full description text and attachments.

create_ticket

Open a new incident or service-request ticket. Requires subject plus a requester: either requester_id or email.

update_ticket

Update ticket fields such as status, priority, and assignee.

list_assets

List CMDB assets, with optional type and page filters.

get_asset

Fetch one asset with its dynamic type_fields.

create_change

Open a new change request with planning fields.

list_agents

List support agents, with optional active and email filters.
Freshservice’s API reference doesn’t list status or priority as filters for the ticket list endpoint that list_tickets calls, so those filters might not narrow the results. Check the returned tickets' status and priority values before you rely on them. By default, Freshservice also returns only tickets created in the past 30 days.

Example: List tickets

curl -s https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/acme-freshservice \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_tickets",
      "arguments": {
        "status": 2,
        "priority": 4
      }
    }
  }'

Replace <cluster-id> with your cluster ID and $TOKEN with a gateway access token. The status and priority filters take the integer codes listed in the tool table. This example asks for open (2), urgent (4) tickets, but check each returned ticket’s values because of the filter caveat. String values such as "open" are rejected by the tool schema.

Example: Create a ticket

curl -s https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/acme-freshservice \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_ticket",
      "arguments": {
        "subject": "Laptop will not boot",
        "description": "Reported by the Dresden office; powers on but no display.",
        "email": "reporter@example.com",
        "priority": 2,
        "status": 2
      }
    }
  }'

A requester is required. Pass either email (as here) or requester_id. ID fields such as requester_id are passed as JSON strings, for example "requester_id": "12345".

Expose Freshservice data as SQL tables

The Freshservice server can also present its read operations as read-only SQL tables, so an agent can filter records the way it would query a database. SQL exposure is the Enabled toggle under Queryable in the server’s configuration. If SQL tools are available in your organization, the create form shows Queryable with Enabled on, so a server you create there is queryable unless you turn it off. Otherwise the form doesn’t show Queryable, and the server starts with SQL exposure off. Creating a server with rpk ai leaves SQL exposure off unless the managed configuration sets it. An existing server keeps the setting it was saved with. To change it, open the server’s edit form, which shows Queryable if SQL tools are available in your organization or if the server was saved with SQL exposure on. SQL exposure adds two tools:

  • list_tables: Return the table catalog. For each table, the catalog lists its columns and their types, which columns can be filtered and with which operators, whether each filter is exact, the page-size limit, and a schema fingerprint that every query response repeats so a caller can tell when the catalog changed.

  • execute_query: Run one query against a table and return a page of rows plus a cursor for the next page.

The tables are:

Table Contents

tickets

Tickets, one row per ticket. Only requester_id can be filtered, and that filter isn’t exact, so re-apply it to the rows you read back. As with list_tickets, an unfiltered scan returns only the tickets created in the past 30 days.

assets

Assets, one row per asset. The table offers no filters, so a query reads the whole set and filters the rows it reads back.

agents

Freshservice agents. You can filter on active exactly, and on email but not exactly.

A page holds at most 100 rows on every table.

The status and priority options that list_tickets accepts are not part of the tickets table, because Freshservice’s list endpoint doesn’t document them, so execute_query refuses a predicate on those columns rather than returning rows that quietly ignore it. Read each row’s status and priority back instead.

With SQL exposure on, the two tools are available to every caller of the server, including agents. Turn off Enabled on a server whose agents should only reach the curated Freshservice tools.

To trim the catalog table by table, hide columns, require filters, retype a column, or serve a table under another name, use the SQL exposure tab on the server’s page. That tab works the same way for every managed type that offers SQL tables. See Narrow what the SQL tools expose. If the server’s page has no SQL exposure tab, narrowing isn’t enabled for your organization. The Enabled setting on the server’s configuration still turns the two SQL tools on and off.

Troubleshooting

Common symptoms and fixes:

Symptom What to check

freshservice API error (status 401)

Confirm FRESHSERVICE_API_KEY matches the value from Profile Settings, and that the key’s Freshservice user has the roles the operation needs.

freshservice API error (status 403)

The API key’s Freshservice user lacks permission for the resource (for example, assets or changes). Grant the role or use an account that has it.

connection_required (User-OAuth mode)

First call from a user with no stored token. The failed tool result carries the authorization URL. The user completes the Freshservice OAuth consent flow, the token lands in the vault, and later calls reuse it. See User-delegated OAuth.

scope_upgrade_required (User-OAuth mode)

The server’s required scopes were extended after users consented, so users reconnect to grant them. If it persists after reconnecting, a required scope is missing from the provider’s scopes or from the Freshworks OAuth credentials.
Freshservice error bodies are not forwarded to the caller, so tool errors carry only the HTTP status code. Reproduce the call against the Freshservice API directly to see the full error detail.

Next steps