SIGN UPLOG IN
X (Twitter)LinkedInGitHubDiscordYouTube

How to integrate Freshservice MCP with Mastra AI

Connect Mastra AI to Freshservice MCP. List all open tickets in freshservice, create a new incident ticket for laptop issue, and more using natural language, with authentication handled for you.

Get started for freeGet a demo
Freshservice logoFreshservice
Api Key

Freshservice is a cloud-based IT service management (ITSM) platform for incident, asset, and service desk operations. Streamline your IT support with automation and centralized control.

20 Tools

Introduction

This guide walks you through connecting Freshservice to Mastra AI using the Composio tool router. By the end, you'll have a working Freshservice agent that can create tickets and service requests, list and bulk update tickets, browse the service catalog, and clean up old solution articles through natural language commands.

This guide will help you understand how to give your Mastra AI agent real control over a Freshservice account through Composio's Freshservice MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

Also integrate Freshservice with

Claude CodeClaude CoworkOpenAI Agents SDKClaude Agent SDKCodexOpenClawHermesAtomic AgentGoogle ADKLangChainVercel AI SDKLlamaIndexCrewAIPydantic AIAutoGen

TL;DR

Here's what you'll learn:
  • Set up your environment so Mastra, OpenAI, and Composio work together
  • Create a Tool Router session in Composio that exposes Freshservice tools
  • Connect Mastra's MCP client to the Composio generated MCP URL
  • Fetch Freshservice tool definitions and attach them as a toolset
  • Build a Mastra agent that can reason, call tools, and return structured results
  • Run an interactive CLI where you can chat with your Freshservice agent

What is Mastra AI?

Mastra AI is a TypeScript framework for building AI agents with tool support. It provides a clean API for creating agents that can use external services through MCP.

Key features include:

  • MCP Client: Built-in support for Model Context Protocol servers
  • Toolsets: Organize tools into logical groups
  • Step Callbacks: Monitor and debug agent execution
  • OpenAI Integration: Works with OpenAI models via @ai-sdk/openai

What is the Freshservice MCP server, and what's possible with it?

The Freshservice MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Freshservice account. It provides structured and secure access to tickets, service catalog items, locations, and form fields, so your agent can create tickets, retrieve ticket details, update multiple tickets, submit service requests, and list locations on your behalf.

  • Ticket creation and tracking: Have your agent create new support tickets, list existing tickets, or retrieve the details of a specific ticket.
  • Bulk ticket updates: Direct your agent to update multiple Freshservice tickets when priorities, statuses, or other ticket details need to change.
  • Service catalog requests: Let the agent browse available service catalog items and submit a service request for the item you need.
  • Location and form field lookup: Instruct your agent to list Freshservice locations or retrieve the available fields for problem and release forms.
  • Release and knowledge base cleanup: Have your agent delete releases, solution articles, or solution categories that are no longer needed.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step09 STEPS
1

Prerequisites

Before starting, make sure you have:
  • Node.js 18 or higher
  • A Composio account with an active API key
  • An OpenAI API key
  • Basic familiarity with TypeScript
2

Getting API Keys for OpenAI and Composio

OpenAI API Key
  • Go to the OpenAI dashboard and create an API key.
  • You need credits or a connected billing setup to use the models.
  • Store the key somewhere safe.
Composio API Key
  • Log in to the Composio dashboard.
  • Go to Settings and copy your API key.
  • This key lets your Mastra agent talk to Composio and reach Freshservice through MCP.
3

Install dependencies

bash
npm install @composio/core @mastra/core @mastra/mcp @ai-sdk/openai dotenv

Install the required packages.

What's happening:

  • @composio/core is the Composio SDK for creating MCP sessions
  • @mastra/core provides the Agent class
  • @mastra/mcp is Mastra's MCP client
  • @ai-sdk/openai is the model wrapper for OpenAI
  • dotenv loads environment variables from .env
4

Set up environment variables

bash
COMPOSIO_API_KEY=your_composio_api_key_here
COMPOSIO_USER_ID=your_user_id_here
OPENAI_API_KEY=your_openai_api_key_here

Create a .env file in your project root.

What's happening:

  • COMPOSIO_API_KEY authenticates your requests to Composio
  • COMPOSIO_USER_ID tells Composio which user this session belongs to
  • OPENAI_API_KEY lets the Mastra agent call OpenAI models
5

Import libraries and validate environment

typescript
import "dotenv/config";
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";
import { Composio } from "@composio/core";
import * as readline from "readline";

import type { AiMessageType } from "@mastra/core/agent";

const openaiAPIKey = process.env.OPENAI_API_KEY;
const composioAPIKey = process.env.COMPOSIO_API_KEY;
const composioUserID = process.env.COMPOSIO_USER_ID;

if (!openaiAPIKey) throw new Error("OPENAI_API_KEY is not set");
if (!composioAPIKey) throw new Error("COMPOSIO_API_KEY is not set");
if (!composioUserID) throw new Error("COMPOSIO_USER_ID is not set");

const composio = new Composio({
  apiKey: composioAPIKey as string,
});
What's happening:
  • dotenv/config auto loads your .env so process.env.* is available
  • openai gives you a Mastra compatible model wrapper
  • Agent is the Mastra agent that will call tools and produce answers
  • MCPClient connects Mastra to your Composio MCP server
  • Composio is used to create a Tool Router session
6

Create a Tool Router session for Freshservice

typescript
async function main() {
  const session = await composio.create(
    composioUserID as string,
    {
      toolkits: ["freshservice"],
    },
  );

  const composioMCPUrl = session.mcp.url;
  console.log("Freshservice MCP URL:", composioMCPUrl);
What's happening:
  • create spins up a short-lived MCP HTTP endpoint for this user
  • The toolkits array contains "freshservice" for Freshservice access
  • session.mcp.url is the MCP URL that Mastra's MCPClient will connect to
7

Configure Mastra MCP client and fetch tools

typescript
const mcpClient = new MCPClient({
    id: composioUserID as string,
    servers: {
      nasdaq: {
        url: new URL(composioMCPUrl),
        requestInit: {
          headers: session.mcp.headers,
        },
      },
    },
    timeout: 30_000,
  });

console.log("Fetching MCP tools from Composio...");
const composioTools = await mcpClient.getTools();
console.log("Number of tools:", Object.keys(composioTools).length);
What's happening:
  • MCPClient takes an id for this client and a list of MCP servers
  • The headers property includes the x-api-key for authentication
  • getTools fetches the tool definitions exposed by the Freshservice toolkit
8

Create the Mastra agent

typescript
const agent = new Agent({
    name: "freshservice-mastra-agent",
    instructions: "You are an AI agent with Freshservice tools via Composio.",
    model: "openai/gpt-5",
  });
What's happening:
  • Agent is the core Mastra agent
  • name is just an identifier for logging and debugging
  • instructions guide the agent to use tools instead of only answering in natural language
  • model uses openai("gpt-5") to configure the underlying LLM
9

Set up interactive chat interface

typescript
let messages: AiMessageType[] = [];

console.log("Chat started! Type 'exit' or 'quit' to end.\n");

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  prompt: "> ",
});

rl.prompt();

rl.on("line", async (userInput: string) => {
  const trimmedInput = userInput.trim();

  if (["exit", "quit", "bye"].includes(trimmedInput.toLowerCase())) {
    console.log("\nGoodbye!");
    rl.close();
    process.exit(0);
  }

  if (!trimmedInput) {
    rl.prompt();
    return;
  }

  messages.push({
    id: crypto.randomUUID(),
    role: "user",
    content: trimmedInput,
  });

  console.log("\nAgent is thinking...\n");

  try {
    const response = await agent.generate(messages, {
      toolsets: {
        freshservice: composioTools,
      },
      maxSteps: 8,
    });

    const { text } = response;

    if (text && text.trim().length > 0) {
      console.log(`Agent: ${text}\n`);
        messages.push({
          id: crypto.randomUUID(),
          role: "assistant",
          content: text,
        });
      }
    } catch (error) {
      console.error("\nError:", error);
    }

    rl.prompt();
  });

  rl.on("close", async () => {
    console.log("\nSession ended.");
    await mcpClient.disconnect();
    process.exit(0);
  });
}

main().catch((err) => {
  console.error("Fatal error:", err);
  process.exit(1);
});
What's happening:
  • messages keeps the full conversation history in Mastra's expected format
  • agent.generate runs the agent with conversation history and Freshservice toolsets
  • maxSteps limits how many tool calls the agent can take in a single run
  • onStepFinish is a hook that prints intermediate steps for debugging

Complete Code

Here's the complete code to get you started with Freshservice and Mastra AI:

typescript
import "dotenv/config";
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";
import { Composio } from "@composio/core";
import * as readline from "readline";

import type { AiMessageType } from "@mastra/core/agent";

const openaiAPIKey = process.env.OPENAI_API_KEY;
const composioAPIKey = process.env.COMPOSIO_API_KEY;
const composioUserID = process.env.COMPOSIO_USER_ID;

if (!openaiAPIKey) throw new Error("OPENAI_API_KEY is not set");
if (!composioAPIKey) throw new Error("COMPOSIO_API_KEY is not set");
if (!composioUserID) throw new Error("COMPOSIO_USER_ID is not set");

const composio = new Composio({ apiKey: composioAPIKey as string });

async function main() {
  const session = await composio.create(composioUserID as string, {
    toolkits: ["freshservice"],
  });

  const composioMCPUrl = session.mcp.url;

  const mcpClient = new MCPClient({
    id: composioUserID as string,
    servers: {
      freshservice: {
        url: new URL(composioMCPUrl),
        requestInit: {
          headers: session.mcp.headers,
        },
      },
    },
    timeout: 30_000,
  });

  const composioTools = await mcpClient.getTools();

  const agent = new Agent({
    name: "freshservice-mastra-agent",
    instructions: "You are an AI agent with Freshservice tools via Composio.",
    model: "openai/gpt-5",
  });

  let messages: AiMessageType[] = [];

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    prompt: "> ",
  });

  rl.prompt();

  rl.on("line", async (input: string) => {
    const trimmed = input.trim();
    if (["exit", "quit"].includes(trimmed.toLowerCase())) {
      rl.close();
      return;
    }

    messages.push({ id: crypto.randomUUID(), role: "user", content: trimmed });

    const { text } = await agent.generate(messages, {
      toolsets: { freshservice: composioTools },
      maxSteps: 8,
    });

    if (text) {
      console.log(`Agent: ${text}\n`);
      messages.push({ id: crypto.randomUUID(), role: "assistant", content: text });
    }

    rl.prompt();
  });

  rl.on("close", async () => {
    await mcpClient.disconnect();
    process.exit(0);
  });
}

main();

Conclusion

You've built a Mastra AI agent that can interact with Freshservice through Composio's Tool Router. You can extend this further by:
  • Adding other toolkits like Gmail, Slack, or GitHub
  • Building a web-based chat interface around this agent
  • Using multiple MCP endpoints to enable cross-app workflows
TOOLS

Supported Tools

Every Freshservice action and event your agent gets out of the box.

Bulk Update Tickets

Updates the same supplied fields on multiple Freshservice tickets identified by ID, using sequential requests.

Create Service Request

Create a service request for a catalog item in Freshservice using the v2 API.

Create Ticket

Create a new Freshservice ticket to log an incident.

Delete Release

Deletes a release from Freshservice.

Delete Solution Article

Deletes a Freshservice knowledge base solution article by ID, moving it to Trash where it can be restored.

Delete Solution Category

Deletes a Freshservice solution category, moving it and its associated folders and articles to Trash.

Get Freshservice Agent

Retrieve one Freshservice support agent profile by its numeric user ID.

Get Problem Form Fields by Workspace

Lists Freshservice problem form field definitions for a specified workspace.

List Release Form Fields

Lists Freshservice release form field definitions for building or validating release forms.

Get Freshservice Requester

Retrieve one Freshservice requester profile by its numeric user ID.

Get Service Catalog Item

Retrieve a service catalog item's details and request form by display ID.

Get Freshservice Ticket

Retrieve a specific Freshservice ticket by ID, including its status, priority, requester ID, and other supported attributes.

List Freshservice Agents

Return Freshservice support agents page by page.

List Freshservice Locations

Lists a page of Freshservice locations, with a choice of page number and page size.

List Project Tasks

Return a page of tasks belonging to one Freshservice project.

List Service Catalog Items

Requests a page of Freshservice service catalog items to help identify items and their display IDs for service requests.

List Ticket Approvals

Return approvals and their current participants for a service request.

List Ticket Conversations

Return a page of replies and notes on one Freshservice ticket.

List Freshservice Tickets

List Freshservice tickets with optional predefined filtering and pagination; on accounts with workspaces, results are limited to the primary workspace.

Search Tickets

Search Freshservice tickets using the provider's filter expression syntax.

FRAMEWORKS

How to build Freshservice MCP Agent with another framework

Claude Code logo

Claude Code

Use Freshservice MCP with Claude Code

Claude Cowork logo

Claude Cowork

Use Freshservice MCP with Claude Cowork

OpenAI Agents SDK logo

OpenAI Agents SDK

Use Freshservice MCP with OpenAI Agents SDK

Claude Agent SDK logo

Claude Agent SDK

Use Freshservice MCP with Claude Agent SDK

Codex logo

Codex

Use Freshservice MCP with Codex

OpenClaw logo

OpenClaw

Use Freshservice MCP with OpenClaw

Hermes logo

Hermes

Use Freshservice MCP with Hermes

Atomic Agent logo

Atomic Agent

Use Freshservice MCP with Atomic Agent

Google ADK logo

Google ADK

Use Freshservice MCP with Google ADK

LangChain logo

LangChain

Use Freshservice MCP with LangChain

Vercel AI SDK logo

Vercel AI SDK

Use Freshservice MCP with Vercel AI SDK

LlamaIndex logo

LlamaIndex

Use Freshservice MCP with LlamaIndex

CrewAI logo

CrewAI

Use Freshservice MCP with CrewAI

Pydantic AI logo

Pydantic AI

Use Freshservice MCP with Pydantic AI

AutoGen logo

AutoGen

Use Freshservice MCP with AutoGen

FAQ

Frequently asked questions

With a standalone Freshservice MCP server, the agents and LLMs can only access a fixed set of Freshservice tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Freshservice and many other apps based on the task at hand, all through a single MCP endpoint.

Yes, you can. Mastra AI fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Freshservice tools.

Yes, absolutely. You can configure which Freshservice scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Freshservice data and credentials are handled as safely as possible.

Start with Freshservice.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Freshservice tool your agent needs.Free to start.

Start building