Admin Pages

Jitbit Helpdesk MCP Server

Jitbit Helpdesk includes a built-in MCP (Model Context Protocol) server that lets AI assistants search support tickets, read knowledge base articles, create new tickets, post ticket replies or internal notes, change a ticket's category or priority, and close tickets. It works with both SaaS and self-hosted installations, using your existing helpdesk permissions.

For example, ask your assistant to find unanswered tickets, summarize a customer's conversation, or draft a reply using a knowledge base article. The setup instructions below cover the hosted MCP endpoint and the local npm package, followed by the available tools and example prompts.

There are two ways to connect:

  • Hosted HTTP endpoint — built into Jitbit Helpdesk. Nothing to install. Recommended for most users.
  • Local npm package — jitbit-helpdesk-mcp runs on your machine over stdio. Use this only with clients that don't yet support the Streamable HTTP transport. The package is being phased out and doesn't include the newer tools (update ticket, close ticket, list categories, attachments).

This page covers connecting your own AI assistant to Jitbit Helpdesk. To let Jitbit's built-in AI Assistant call tools on an external MCP server, see MCP servers for the AI Assistant.


Getting your API token

  1. Log in to your Jitbit Helpdesk
  2. Go to your User Profile (click your avatar in the top right)
  3. Click the "API Token" button
  4. Copy the token

Option 1: Hosted HTTP endpoint

Your Jitbit Helpdesk exposes an MCP endpoint at /api/mcp over HTTPS. Any MCP client that speaks the Streamable HTTP transport can connect directly.

On-premise

Available in Jitbit Helpdesk v11.21 and later. The SaaS version always has it.

  • URL: https://yourcompany.jitbit.com/api/mcp
  • Auth: Authorization: Bearer <your-api-token> header, or OAuth sign-in
  • Transport: Streamable HTTP (stateless)

OAuth sign-in

Some MCP clients can't send a custom Authorization header, for example organization-wide connectors in AI assistants (Claude Team/Enterprise, Microsoft Copilot Studio, ChatGPT). These clients connect with OAuth instead: each user signs in to Jitbit Helpdesk with their own account and approves the connection. Nothing needs to be configured in Jitbit.

On-premise

OAuth sign-in requires Jitbit Helpdesk v11.24 or later, installed at the root of its domain (for example https://helpdesk.example.com/, not https://example.com/helpdesk/). Cloud-hosted AI assistants also need your server to be reachable from the internet.

Adding the server to your MCP client:

  1. In your AI assistant's connector or MCP server settings, add a new remote (HTTP) MCP server
  2. Enter the URL https://yourcompany.jitbit.com/api/mcp
  3. Choose OAuth as the authentication method if asked. Leave the client ID and secret empty — the client registers itself automatically. If the client insists on a client ID or secret, any value works

Connecting (each user):

  1. Click Connect (or equivalent) in your AI assistant
  2. Log in to your helpdesk if you aren't already (SSO and two-factor authentication work as usual)
  3. Check the consent screen shows the app you're connecting, then click Allow

The AI assistant then acts as you: it sees only the tickets and articles you have access to, and tickets or comments it creates are attributed to you. Only click Allow for a connection you started yourself.

To revoke access, disconnect the server in your AI assistant. To invalidate the credentials it received, change your helpdesk password (this also invalidates your API token), or an admin can disable the user.

Claude Code

claude mcp add --transport http jitbit-helpdesk https://yourcompany.jitbit.com/api/mcp \
  --header "Authorization: Bearer your-api-token"

Claude Desktop, Cursor, Windsurf

Add to your config file:

  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
  • Cursor: Settings > MCP Servers
  • Windsurf: Settings > MCP Servers
{
  "mcpServers": {
    "jitbit-helpdesk": {
      "type": "http",
      "url": "https://yourcompany.jitbit.com/api/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      }
    }
  }
}

Option 2: Local npm package (stdio)

The npm package is being phased out and only has the original tools (search and list tickets, get ticket, knowledge base, add comment, create ticket). Use the hosted HTTP endpoint whenever your client supports it.

Use this only if your MCP client doesn't support HTTP transport yet.

Claude Code

claude mcp add jitbit-helpdesk \
  -e JITBIT_URL=https://yourcompany.jitbit.com \
  -e JITBIT_TOKEN=your-api-token \
  -- npx -y jitbit-helpdesk-mcp

Claude Desktop, Cursor, Windsurf

{
  "mcpServers": {
    "jitbit-helpdesk": {
      "command": "npx",
      "args": ["-y", "jitbit-helpdesk-mcp"],
      "env": {
        "JITBIT_URL": "https://yourcompany.jitbit.com",
        "JITBIT_TOKEN": "your-api-token"
      }
    }
  }
}

Environment Variables

VariableRequiredDescription
JITBIT_URLYesBase URL of your Jitbit instance (SaaS: https://yourcompany.jitbit.com, self-hosted: your server URL)
JITBIT_TOKENYesAPI token from your Jitbit user profile

Available Tools

Once configured, the MCP server exposes the following tools that the AI assistant can call automatically. All are read-only except jitbit_create_ticket, jitbit_add_comment, jitbit_update_ticket and jitbit_close_ticket.

Search Tickets

Tool name: jitbit_search_tickets

Search tickets by keyword or phrase. Matches against ticket subjects and bodies.

Parameters:

  • query (string, required) — search query (minimum 3 characters)
  • limit (number, default 25) — max results (1-100)

Example use: "Search for tickets about password reset" — the AI calls jitbit_search_tickets with query "password reset" and returns matching tickets.

List Tickets

Tool name: jitbit_list_tickets

List and filter tickets by mode and status.

Parameters:

  • mode (string, optional) — "all", "unanswered", "unclosed", "unassigned", or "handledbyme"
  • status (string, optional) — filter by ticket status name
  • limit (number, default 25) — max results (1-100)
  • offset (number, default 0) — pagination offset

Example use: "Show me unanswered tickets" — the AI calls jitbit_list_tickets with mode "unanswered".

Get Ticket

Tool name: jitbit_get_ticket

Get a single ticket with its full conversation thread, including subject, body, status, priority, category (with its ID, e.g. IT / Hardware (#17)), submitter, submitter's company, assignee, due date, tags, custom fields that have a value, and all comments (oldest first). Custom fields are shown according to your permissions: admin-only and tech-only fields are hidden from users who can't see them in the helpdesk. Attachments are listed with a file ID that can be passed to jitbit_get_attachment.

Parameters:

  • ticketId (number, required) — the ticket ID

Example use: "Show me ticket #4521" — the AI calls jitbit_get_ticket with ticketId 4521 and returns the full ticket details and conversation history.

Update Ticket

Tool name: jitbit_update_ticket

Change a ticket's category and/or priority. Only the fields you pass are changed, and both are validated before anything is saved. Allowed for admins, technicians with access to the ticket's category, and the ticket submitter. The new category must be one you can submit tickets to. Returns the ticket's category and priority after the update.

Changing the category permanently deletes the ticket's custom field values that don't apply to the new category. Moving the ticket back does not restore them.

Parameters:

  • ticketId (number, required) — the ticket ID
  • category (string or number, optional) — the category ID, "Section / Category", or a category name if it's unique. An unknown or ambiguous name returns the list of matching or available categories
  • priority (string or number, optional) — "Low" (-1), "Normal" (0), "High" (1) or "Critical" (2), by name or number. Custom priorities aren't supported yet

Example use: "Move ticket #1234 to Billing and make it high priority" — the AI calls jitbit_update_ticket with ticketId 1234, category "Billing" and priority "High".

Close Ticket

Tool name: jitbit_close_ticket

Close a ticket. Allowed for admins, technicians with access to the ticket's category, and the ticket submitter (unless your helpdesk only lets technicians close tickets). Fails if mandatory custom fields are empty. To reply before closing, the AI calls jitbit_add_comment first.

Parameters:

  • ticketId (number, required) — the ticket ID

Example use: "Close ticket #1234" — the AI calls jitbit_close_ticket with ticketId 1234.

List Categories

Tool name: jitbit_list_categories

List the ticket categories you can submit tickets to, as "Section / Category (#ID)", the same list as the category dropdown in the helpdesk. Marks the default category and tech-only categories, and includes each category's description if it has one. Either the name or the ID can be used in jitbit_create_ticket and jitbit_update_ticket.

Parameters: none

Example use: "Which category should this ticket go in?" — the AI calls jitbit_list_categories and picks one based on the names and descriptions.

Get Attachment

Tool name: jitbit_get_attachment

Get a temporary download link for a file attached to a ticket or knowledge base article. The link works without authentication for 10 minutes.

Parameters:

  • fileId (number, required) — the file ID from jitbit_get_ticket or jitbit_get_kb_article

Example use: "Look at the screenshot the customer attached to ticket #4521" — the AI gets the ticket, then calls jitbit_get_attachment with the screenshot's file ID and downloads it.

Search Knowledge Base

Tool name: jitbit_search_kb

Search knowledge base articles by keyword or phrase. Matches against article subjects, bodies, and tags. Only articles you have permission to see are returned.

Parameters:

  • query (string, required) — search query (minimum 3 characters)
  • limit (number, default 25) — max results (1-100)

Example use: "Find KB articles about VPN setup" — the AI calls jitbit_search_kb with query "VPN setup" and returns matching articles with their IDs, categories, and tags.

Get Knowledge Base Article

Tool name: jitbit_get_kb_article

Get a single knowledge base article with its full content, including subject, category, tags, and dates.

Parameters:

  • articleId (number, required) — the article ID

Example use: "Read KB article #87" — the AI calls jitbit_get_kb_article with articleId 87 and returns the full article text, which it can summarize or paste into a ticket reply.

Add Comment

Tool name: jitbit_add_comment

Add a comment (reply) to a ticket. The comment is posted as the authenticated API user. Tech-only comments are allowed only for admins or technicians with access to the ticket's category.

Parameters:

  • ticketId (number, required) — the ticket ID to comment on
  • body (string, required) — the comment text (plain text is accepted and converted to HTML)
  • forTechsOnly (boolean, required) — true for an internal note visible only to technicians, false for a reply visible to the customer

Example use: "Reply to ticket #1234 telling the customer we've shipped the fix" — the AI calls jitbit_add_comment with ticketId 1234, the reply text, and forTechsOnly: false.

Create Ticket

Tool name: jitbit_create_ticket

Create a new ticket. The ticket is submitted as the authenticated API user, into a category you have permission to submit to.

Parameters:

  • subject (string, required) — the ticket subject
  • body (string, required) — the ticket text (plain text is accepted and converted to HTML)
  • category (string or number, optional) — the category ID, "Section / Category", or a category name if it's unique. If omitted, the helpdesk's default category is used. An unknown or ambiguous name returns the list of matching or available categories
  • priority (string, optional) — priority name, e.g. "Low", "Normal", "High", "Critical" or a custom priority. Defaults to Normal

Example use: "Create a ticket in the Hardware category: the printer on floor 3 is jammed" — the AI calls jitbit_create_ticket with a subject, the description and category "Hardware", and returns the new ticket ID.


What You Can Do With It

Once connected, you can ask your AI assistant things like:

  • "Search for tickets about SSO login issues"
  • "Show me all unanswered tickets"
  • "Get the details of ticket #1234"
  • "Find tickets related to billing"
  • "List unclosed tickets and summarize them"
  • "Search the knowledge base for our refund policy"
  • "Read KB article #87 and draft a reply for ticket #1234"
  • "Reply to ticket #1234 with the workaround from KB article #87"
  • "Add an internal note to ticket #1234 flagging it for the billing team"
  • "Create a high-priority ticket about the VPN outage"
  • "Go through unassigned tickets and fix any that are in the wrong category"
  • "Mark ticket #1234 as critical"
  • "Reply to ticket #1234 that the issue is fixed, then close it"

The AI assistant handles tool selection automatically — just ask in natural language.


Security

  • The only tools that write anything are jitbit_create_ticket (creates tickets), jitbit_add_comment (adds replies and internal notes), jitbit_update_ticket (changes category and priority) and jitbit_close_ticket (closes tickets). The MCP server cannot delete tickets or comments, and every other tool is read-only
  • All calls use your personal API token, so the AI sees only what you have access to, and any tickets or comments it creates are attributed to you
  • For the hosted endpoint, the token is sent as a Bearer header over HTTPS
  • With OAuth sign-in, you log in and explicitly approve the connection on a consent screen. The AI assistant receives a token equivalent to your API token
  • For the npm package, the token is stored locally in your MCP configuration and is never sent to third parties
Previous
AI Assistant