# Freshservice 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: Freshservice Managed MCP Server page-beta-text: This is a beta feature. Beta features are available for testing and feedback. They are not supported by Redpanda and should not be used in production environments. latest-operator-version: v26.1.5 latest-console-tag: v3.7.4 latest-connect-version: 4.96.1 latest-redpanda-tag: v26.1.10 docname: managed/freshservice page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/freshservice.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/freshservice.adoc # Beta release status page-beta: "true" description: Manage Freshworks Freshservice ITSM tickets, assets, change requests, and agents from an agent, with API-key or per-user OAuth authentication. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the Freshservice managed MCP server in API-key or User-OAuth mode learning-objective-2: Find the Freshservice credentials each mode needs learning-objective-3: List, create, and update tickets, assets, and changes from the Inspector or an agent page-git-created-date: "2026-06-09" page-git-modified-date: "2026-06-10" release-status: beta - This is a beta feature. Beta features are available for testing and feedback. They are not supported by Redpanda and should not be used in production environments. --- 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)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](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#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)Prerequisites Before you create the server, make sure you have: - A Freshservice instance and its domain (for example, `mycompany.freshservice.com`). - For API-key mode: the API key from your Freshservice profile (see [Get Freshservice credentials](#get-freshservice-credentials)). - For User-OAuth mode: a Freshservice OAuth app and an [OAuth Provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) configured in Redpanda ADP. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). ## [](#get-freshservice-credentials)Get Freshservice credentials ### [](#option-1-api-key-recommended-for-service-accounts)Option 1: API key (recommended for service accounts) 1. In Freshservice, open **Profile Settings**. 2. Copy the value from the **API Key** section. 3. Store the key in the ADP 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(: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)Option 2: User OAuth For per-user authentication, register an OAuth app on Freshservice and a matching OAuth Provider in ADP: 1. Register a Freshservice OAuth app at the Freshworks developer portal to obtain a client ID and client secret. 2. Register a matching OAuth Provider in ADP. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/). The `freshservice` preset pre-fills the authorization and token endpoints; ADP substitutes your Freshservice subdomain into the `{domain}` placeholders. 3. Each end-user authenticates once through the OAuth flow; tokens are stored in the gateway’s token vault. The OAuth scopes are `read` and `write`. Drop `write` if the MCP only needs to read. ## [](#configure)Configure Create a new Freshservice MCP server in ADP: 1. Open **MCP Servers > Create Server**. 2. Pick `Freshservice` from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. 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. | | api_key (API-key mode) | Secret-store reference holding the API key (for example, FRESHSERVICE_API_KEY). UPPER_SNAKE_CASE. | | user_oauth (User-OAuth mode) | The OAuth Provider you configured, and the minimum scopes a user’s connection must have. | 5. Click **Create**. ### [](#configure-from-the-cli)Configure from the CLI For a managed server, set the auth method inside the `--managed-config` JSON. The `auth` field is required. #### API-key mode ```bash rpk ai mcp create --name acme-freshservice --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.freshservice.v1.FreshServiceMCPConfig", "domain": "mycompany.freshservice.com", "api_key": { "key_secret_ref": "FRESHSERVICE_API_KEY" } }' ``` #### User-OAuth mode ```bash rpk ai mcp create --name acme-freshservice-oauth --managed-config '{ "@type": "type.googleapis.com/redpanda.mcps.freshservice.v1.FreshServiceMCPConfig", "domain": "mycompany.freshservice.com", "user_oauth": { "provider_name": "freshservice-prod", "required_scopes": ["read", "write"] } }' ``` Replace `freshservice-prod` with the name of the OAuth Provider you configured. ## [](#tools)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. | | get_ticket | Fetch one ticket with its full description text and attachments. | | create_ticket | Open a new incident or service-request ticket. | | 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. | ### [](#example-list-open-tickets)Example: List open tickets ```bash curl -s https://aigw..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": "open", "priority": "urgent" } } }' ``` Replace `` with your cluster ID and `$TOKEN` with a gateway access token. ### [](#example-create-a-ticket)Example: Create a ticket ```bash curl -s https://aigw..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.", "priority": 2, "status": 2 } } }' ``` ## [](#troubleshooting)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. | | OAuthConnectionRequired (User-OAuth mode) | First call from a user with no stored token. 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. Users re-consent with the higher scope. | > 📝 **NOTE** > > 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)Next steps - [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) - [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/) - [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/)