MCP Server

Overview

The HawkSearch MCP Server is a Model Context Protocol (MCP) server that exposes HawkSearch functionality as AI-accessible tools. It serves as the bridge between AI assistants and HawkSearch engines, allowing assistants to retrieve data, perform management actions, and execute workflows on behalf of authenticated users.

Plans

Plan	Description	Features
Dashboard	A plan geared toward admin and management functionality, enabling applications to programmatically maintain search configurations, merchandising rules, campaigns, and site-search behavior.	FieldManager — list, getById, getInfo, getInfoById, create, update, delete FacetManager — list, getById, create, update, delete SynonymManager — list, getById, create, update, delete RedirectManager — list, getById, create, update, delete BoostBuryManager — list, create, update, delete, deleteById VisibilityManager — list, getById, create, update, delete VisitorTargetManager — list, getById, create, update, delete SpellCheckManager — list, getById, create, update, delete LandingPageManager — getUrls/list, getById, getByUrl, create, update, delete CampaignManager — list, getById, create, update, delete PaginationManager — list, getById, create, update, delete SortingSetManager — list, getById, create, update, delete RecommendationVisibilityManager — list, getById BannerManager — list, getById, getCampaignsById, getZones
Analytics	A plan focused on search analytics and reporting, helping teams understand their customers on a deeper level.	Top 250 Facets (topFacet) Top 250 Search Terms — clicks (topClick) Top 250 Search Terms (topSearch) Keyword List Daily (keywordlist) Activity Funnel (activityfunnel) AutoComplete Click-Summary Report (autoCompleteClickSummary) More reports are set to be added in the near future.
Premium	The ultimate HawkSearch AI experience. Enable both the Dashboard and the Analytics functionality to activate an AI that understands your system inside and out.	All of the above.

Error Codes

HTTP Status	Error Code	Meaning
400	-32600	Invalid Request : the request was blocked by input guardrails or was malformed.
401	-32001	Unauthorized : the caller could not be authenticated.
403	-32003	Forbidden : the caller is authenticated but not allowed, or the engine configuration is not provisioned.
429	-32000	Too Many Requests : the per-caller rate limit was exceeded.
500	-32603	Internal Server Error : an unexpected error occurred while processing the request.

Error Scenarios, Causes, and Resolutions

Request guardrail errors (HTTP 400, code -32600)

These are raised before the request reaches a tool, when the input fails safety/size checks.

Message	Cause	Resolution
Request payload exceeds the maximum permitted size.	The request body is larger than 64 KB.	Reduce the payload size or split the operation into smaller requests.
Request contains disallowed content and has been rejected.	The body matched a blocked pattern (prompt-injection, SQL injection, command injection, SSRF, credential/data harvesting, script/HTML, etc.).	Remove the flagged content. Tools that legitimately carry markup (LandingPage, Facet, Redirect, BoostBury, Visibility, VisitorTarget) are exempt from the HTML /XML data check.

Authentication errors (HTTP 401, code -32001)

The caller could not be authenticated from the bearer token.

Message	Cause	Resolution
Unauthorized: Malformed security token.	The Authorization header is present but is not a readable JWT.	Send a valid Bearer access token.
Unauthorized: Missing token.	No Authorization header was supplied (outside local development).	Include an Authorization: Bearer header.
Unauthorized: token has no email.	The token has no username/email claim to identify the user.	Ensure the user pool issues a username or email claim.
Unauthorized:	The token failed signature, issuer, or expiry validation (e.g. expired).	Refresh the token and retry.

Authorization & provisioning errors (HTTP 403, code -32003)

The caller is authenticated but is not permitted, or the target engine is not fully set up.

Message	Cause	Response
Forbidden: client is not permitted.	The token's client_id is not in the allow-list.	Reach out to the HawkSearch support team for assistance.
Forbidden: X-HawkSearch-ClientGuid header is required.	The caller did not name which engine to act on.	Send the X-HawkSearch-ClientGuid header identifying the target engine.
Forbidden: no engine access for this user.	The user's email is not mapped to the requested engine.	Grant the user access to the engine
Forbidden: engine host is not permitted.	The engine's BaseUrl is missing or its host is not in the allowed suffixes.	Set a valid BaseURL (e.g. https://.hawksearch.net/ <engine.hawksearch.com>) in the engine's sysparam.
Forbidden: the engine has an invalid or missing package tier.	The engine's PackageTier is empty or not a recognised value.	Set PackageTier to a valid tier (see Package Tiers section).

Other Errors

Message	Status / Code	Cause	Resolution
Rate limit exceeded. Please retry later.	429 / -32000	The caller exceeded the allowed number of requests per time window.	Reduce the request rate and retry after the window.
Internal server error during request processing.	500 / -32603	An unexpected error occurred in the request pipeline.	Retry the request. If it persists, reach out to our support team for help.