Home → API Manual → MCP Server → MCP Server Admin Settings

7.1. MCP Server Admin Settings

Updated: 10 Sep 2026, 02:15 PM EDT

The HelpSpot MCP (Model Context Protocol) server lets AI agents—such as Claude, Cursor, ChatGPT, and GitHub Copilot—connect to your HelpSpot instance and work with requests, the knowledge base, and related data on a staff member's behalf. Every action an agent takes is performed as the authenticated staff user and respects that user's existing permissions.

This page explains the MCP administration screen and what each setting does. For step-by-step instructions on connecting a specific client, see the other pages in this chapter.

Where to Find the Settings

Log in to your HelpSpot admin area.
Go to Settings.
Select MCP.

The screen is titled MCP Server (AI Agents) and is divided into general settings and a list of available tools.

Enable MCP Server

The master switch for the feature. When it is off, the MCP server is completely unavailable and every connection attempt is rejected, regardless of any other setting on this page.

Default: Off.
Turn this on to allow AI agents to connect to HelpSpot via MCP.
Once enabled, individual staff users generate their own access tokens (see How Staff Connect below). Each user only ever sees and acts on the data their HelpSpot permissions allow.

MCP Server URL

The read-only address that MCP clients connect to. It always ends in /mcp and is based on your installation's base URL.

Copy this value into your MCP client when setting up a connection.
The field cannot be edited here—it is derived automatically from your HelpSpot URL.

Allowed OAuth Redirect Domains

Controls which external clients are permitted to register with your MCP server through OAuth dynamic client registration. Enter one origin per line, for example https://claude.ai.

Default: Blank, which blocks all external MCP client registration. This is a secure, deny-by-default configuration.
Only clients whose redirect URI begins with one of the listed origins may register.
Each entry must be a scheme and host only (for example https://example.com). Paths, query strings, and fragments are not allowed and will be rejected when you save.
This setting affects MCP only. Other OAuth integrations in HelpSpot are unaffected.

Clients that authenticate with a personal access token (rather than OAuth registration) do not depend on this list—see below.

Available Tools

This section lists every tool the MCP server can expose to AI agents, grouped by area (Requests, Knowledge Books, and supporting lookups). Each tool has its own switch.

Default: All tools are enabled.
Uncheck any tool you do not want exposed to AI agents. Connected clients must reconnect before they see the change.
Disable all write tools — a shortcut that turns off every tool that can create or change data, leaving only read-only tools enabled. Use this if you want agents to look up information but never modify anything.
Enable all — re-enables every tool.

Write tools vs. read-only tools

Tools that create or modify data (for example, creating a request or updating a knowledge base page) are treated as write tools. Read-only tools only retrieve information. The Disable all write tools button acts on the write tools as a group.

Private vs. public request tools

Some tools come in a public and a private variant, and the two cannot be enabled at the same time:

create-request-tool / create-private-request-tool
update-request-tool / update-private-request-tool

The public variant sends customer-facing email as it normally would. The private variant performs the same action without emailing the customer or sending any external mail—useful when you want agents to log notes and updates internally only. When you enable one variant, its counterpart is automatically disabled, and the screen notes that a tool is “available when” its sibling is disabled.

Tool Reference

The following tools are available. Tools marked (write) create or change data; all others are read-only.

Requests

search-requests-tool — Search and filter requests with full-text search, status/category/staff/date/custom-field filters, and pagination.
get-request-tool — Fetch a single request, including status, category, assignment, customer info, custom fields, and recent history.
get-requests-tool — Fetch multiple requests by ID, returning abbreviated details for each accessible request.
get-request-history-tool — Page through the history and notes of a request.
list-filters-tool — List the saved filters available to you.
get-filter-results-tool — Run a saved filter and return the matching requests.
aggregate-requests-tool — Group and count requests for reporting (by category, status, staff, channel, custom field, or customer).
aggregate-request-history-tool — Aggregate individual updates, notes, and replies for activity reporting.
create-request-tool (write) — Create a new request; the customer is emailed as normal.
create-private-request-tool (write) — Create a request as a private staff note with no customer email.
update-request-tool (write) — Add notes, change status, reassign, and more.
update-private-request-tool (write) — Update a request privately with no customer email.

Knowledge Books

list-books-tool — List all knowledge base books with their chapters and page counts.
search-knowledge-books-tool — Search knowledge book pages by keyword.
get-book-page-tool — Fetch a single page, including its chapter and book.
create-book-tool (write) — Create a new knowledge base book.
create-chapter-tool (write) — Create a new chapter in a book.
create-book-page-tool (write) — Create a new page in a chapter.
update-book-page-tool (write) — Update an existing page.

Supporting Lookups

list-categories-tool — List active categories with their tags, custom fields, and assigned staff.
list-statuses-tool — List active statuses.
list-staff-tool — List active staff members.
list-custom-fields-tool — List custom fields with their IDs, types, and options.

How Staff Connect

After you enable the server and configure the settings above, each staff member connects their own client:

Clients that support OAuth (such as Claude) register and authenticate through the browser. For these to register, their origin must be listed in Allowed OAuth Redirect Domains.
Alternatively, staff can generate a personal access token from their Preferences page and supply it to the client as a bearer token.

All access is per-user: an agent can only see and change the data the connected staff member is allowed to see and change.

Tool Output Is Text, Not Structured Data

MCP tools return their results as a single text content item written for an AI agent to read. For example, get-request-tool returns line-oriented plain text (Request #12345, Title: …, Status: …, followed by recent history). It is not JSON, and the server does not return structuredContent or declare an output schema. History notes in this output have HTML removed and are truncated to 500 characters.

The labels and layout are presentation text and may change between releases, so do not build an integration that parses them.

If you need machine-readable request data, use the HelpSpot Private API instead, which returns JSON when you pass output=json:

GET /api/index.php?method=private.request.get&output=json&fRawValues=1&xRequest=<ID>
Authorization: Bearer <API_TOKEN>

The Private API must be enabled under Admin > Settings > Web Services API and is separate from the MCP tool list. API tokens are generated from a staff profile and inherit that account's permission group and category access. See Private Methods.

Security Notes

The server is off by default and external client registration is blocked until you explicitly allow specific origins.
Disable any tools you do not need. Use Disable all write tools if agents should never modify data.
MCP requests are rate limited independently of the rest of HelpSpot to protect the server.
Changes to the tool list take effect after connected clients reconnect.

This page was: Helpful | Not Helpful

Helpspot MCP Overview →