Agentic Data Plane
Preview

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

Wraps the Freshservice REST API v2. The following authentication modes are supported:

  • 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 Method

    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. 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. rpk ai mcp-server create leaves it off unless you pass --code-mode. 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 caveat after the table.

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 see the caveat after the tool table: check each returned ticket’s values. 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".

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