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

7.2. MCP Server Admin Settings

Updated: Jun 8 2026, 03:52 PM

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

1. Log in to your HelpSpot admin area.
2. Go to Settings.
3. 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.

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.