Using TurboHelp MCP

Updated 26 ago 2026 5 min read

This guide explains how to connect an AI client to TurboHelp using MCP. Use it when you want an assistant to inspect helpdesk data, find available API routes, or perform approved actions through the TurboHelp API.

At a Glance

MCP access is available on Growth and Scale plans.
Create a dedicated MCP-only API token from the account settings MCP section.
Connect your AI client to /api/mcp/helpdesk with an Authorization: Bearer header.
Settings, token management, logs, webhooks, impersonation, and other sensitive routes are blocked from MCP.

TurboHelp MCP lets compatible AI clients connect to your helpdesk through the Model Context Protocol. Instead of copying ticket data into a chat window, you can let an AI client inspect available API routes and make authorized TurboHelp API requests on behalf of the current agent.

MCP access is available on the Growth and Scale plans. It is not available on Starter.

MCP can read and change helpdesk data depending on the route being called. Only create tokens for trusted agents and trusted AI clients.

What MCP Can Do

The TurboHelp MCP server exposes a controlled gateway to the TurboHelp JSON API. The AI client can:

Discover available helpdesk API routes.
Read conversations, customers, tags, articles, reports, and other API resources that the agent can access.
Call allowed write routes when the connected AI client asks for an action and the underlying user has permission.

Some sensitive routes are intentionally not available through MCP, including settings, token management, authentication routes, logs, inbound mail webhooks, impersonation, and cache flush routes.

Requirements

Your TurboHelp workspace must be on the Growth or Scale plan.
Your user account must be active and verified.
Your user account must have permission to access the API resources you want to use.
Your AI client must support remote HTTP MCP servers and bearer-token authentication.

Create an MCP Token

MCP uses personal API access tokens. Browser sessions and cookies are not accepted for MCP connections.

Open your TurboHelp account settings.
Go to the MCP section.
Click Create MCP token. You can also create one from API access tokens by enabling Limit token to MCP access.
Enter a clear name, such as Claude MCP or Cursor MCP.
Create the token and copy it immediately. The token is shown only once.

A token created with Limit token to MCP access can connect to the MCP endpoint, but it is not a regular full API token.

MCP Endpoint

Use the MCP endpoint for your TurboHelp installation:

https://your-turbohelp-domain.com/api/mcp/helpdesk

If your installation uses a separate API domain, use that domain instead:

https://your-api-domain.com/api/mcp/helpdesk

Every MCP request must include the API token in the authorization header:

Authorization: Bearer YOUR_MCP_TOKEN

Connect an AI Client

The exact setup screen depends on the AI client, but the connection needs the same three values:

Server type: HTTP or remote MCP server.
URL: your TurboHelp MCP endpoint.
Authorization header: Bearer YOUR_MCP_TOKEN.

Many clients use a JSON configuration similar to this:

{
  "mcpServers": {
    "turbohelp": {
      "type": "http",
      "url": "https://your-turbohelp-domain.com/api/mcp/helpdesk",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

If your client has a visual setup flow, create a new remote MCP server, paste the endpoint URL, and add the authorization header there.

Available Tools

After connecting, the AI client will see two TurboHelp tools.

`turbohelp_list_api_routes`

Use this tool to discover which API routes are available through MCP. It supports searching by route path or action, filtering by HTTP method, and optionally including write routes.

Example prompts:

List TurboHelp MCP routes related to conversations.
Show me available GET routes for customers.
Find routes that can update tags.

`turbohelp_api_request`

Use this tool to call an allowed TurboHelp API route. The request can include a method, path, query parameters, and JSON body.

Example prompts:

Show my recent open conversations.
Get details for conversation 123.
Add the tag "billing" to conversation 123.

When your AI client asks to run a write action, review it carefully before approving. The action uses your TurboHelp permissions and can affect real helpdesk data.

Troubleshooting

401 Unauthorized

The request is missing a valid bearer token. Make sure the client is sending Authorization: Bearer YOUR_MCP_TOKEN. MCP does not accept browser cookies or a normal logged-in web session.

403 Forbidden

The token or workspace is not allowed to use MCP. Check that:

The workspace is on Growth or Scale.
The token was created with MCP access or full API access.
The user still has access to the current workspace.
The user has permission to perform the requested API action.

Route Not Found or Blocked

The requested API route may not be exposed through MCP. Settings, token management, authentication, logs, inbound mail webhooks, impersonation, and cache flush routes are blocked intentionally.

Security Best Practices

Create a dedicated MCP-only token for each AI client.
Use clear token names so you can identify where each token is used.
Delete tokens that are no longer needed.
Do not paste MCP tokens into chats, tickets, public documents, or shared screenshots.
Rotate the token if it may have been exposed.