Skip to main content

​
Overview

The WebHelp MCP Server can be customized through environment variables, Next.js configuration, and MCP handler options. This guide covers all available configuration points.

​
Environment Variables

While the server works without any environment variables for basic deployments, you can configure proxy settings for corporate environments.

​
Proxy Configuration

​
HTTPS_PROXY
string
Primary HTTPS proxy URL for outbound requests to WebHelp deployments.Example:
HTTPS_PROXY=http://proxy.company.com:8080
​
https_proxy
string
Alternative lowercase variant of HTTPS_PROXY (fallback).
​
HTTP_PROXY
string
HTTP proxy URL for outbound requests (used if HTTPS_PROXY is not set).
​
http_proxy
string
Alternative lowercase variant of HTTP_PROXY (fallback).

​
How Proxy Variables Are Used

The proxy configuration is used when the server makes requests to external WebHelp deployments, particularly for semantic search via the Oxygen Feedback service:
lib/webhelp-search-client.ts
const proxyUrl =
  process.env.HTTPS_PROXY ||
  process.env.https_proxy ||
  process.env.HTTP_PROXY ||
  process.env.http_proxy;

const options: any = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData)
  }
};
if (proxyUrl) {
  options.agent = new HttpsProxyAgent(proxyUrl);
}

​
Next.js Configuration

The server uses a minimal Next.js configuration that can be extended in next.config.ts.

​
Default Configuration

next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {};

export default nextConfig;

​
Custom Configuration Options

You can extend this configuration to add custom settings: 
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Increase timeout for large documentation sites
  experimental: {
    serverActions: {
      bodySizeLimit: '10mb',
    },
  },
};

export default nextConfig;

​
MCP Handler Options

The MCP handler is configured in app/[...site]/route.ts with several customizable options.

​
Current Configuration

app/[...site]/route.ts
return createMcpHandler(
  async (server) => {
    // Tool definitions...
  },
  {
    capabilities: {
      tools: {
        search: {
          description: searchDescription,
        },
        fetch: {
          description: "Fetch the content of a document by its ID",
        },
      },
    },
  },
  {
    streamableHttpEndpoint: `/${endpoint}`,
    verboseLogs: true,
    maxDuration: 60,
    // disableSse: false,
  },
)(req);

​
Available Handler Options

​
streamableHttpEndpoint
string
required
The endpoint path for the MCP server. Dynamically set based on the requested site.Default: /${endpoint} (e.g., /docs.example.com)
​
verboseLogs
boolean
default:"true"
Enable detailed logging for debugging. Logs include:
  • Incoming request paths
  • Tool invocations with parameters
  • Search and fetch operations
Recommendation: Set to false in production to reduce log volume.
​
maxDuration
number
default:"60"
Maximum duration in seconds for MCP requests. Important for:
  • Large documentation sites with extensive search indexes
  • Network-constrained environments
  • Rate limiting and resource management
Example: Increase for very large documentation:
maxDuration: 120, // 2 minutes
​
disableSse
boolean
default:"false"
Disable Server-Sent Events (SSE) for streaming responses.Note: Currently commented out. Enable if you encounter streaming issues:
disableSse: true,

​
Search Tool Configuration

The search tool can be customized to adjust result limits and behavior:
app/[...site]/route.ts
server.tool(
  "search",
  searchDescription,
  {
    query: z
      .string()
      .describe("Search query string (supports boolean operators like AND, OR)"),
  },
  async ({ query }) => {
    const result = await searchClient.search(query);
    const maxResultsToUse = 10; // Customize this value
    
    const topResults = result.results.slice(0, maxResultsToUse);
    // ...
  }
);
​
maxResultsToUse
number
default:"10"
Maximum number of search results returned to the AI model.Considerations:
  • More results provide better context but increase token usage
  • Fewer results reduce costs but may miss relevant content
  • Adjust based on your documentation size and AI model limits

​
WebHelp Search Client Options

The WebHelpSearchClient is initialized with base URLs for documentation sites:
app/[...site]/route.ts
function resolveBaseUrls(site: Array<string>): string[] {
  if (site[0] === 'federated' && site[1]) {
    return decodeUrls(site[1]);
  }
  const endpoint = site.join('/');
  return [`https://${endpoint}/`];
}

const baseUrls = resolveBaseUrls(site);
const searchClient = new WebHelpSearchClient(baseUrls);
The server supports federated search across multiple WebHelp deployments:
Access federated search using the /federated/{encoded-urls} endpoint format. URLs are encoded using the url-pack utility.

​
Semantic Search Configuration

Semantic search via Oxygen Feedback is automatically enabled when available:
lib/webhelp-search-client.ts
async semanticSearch(
  query: string,
  baseUrl: string,
  pageSize: number = 10  // Customize page size
): Promise<SearchResult>
​
pageSize
number
default:"10"
Number of results to request from the semantic search API.

​
Advanced Configuration

​
Custom HTML to Markdown Conversion

The Turndown service can be customized in lib/webhelp-search-client.ts:204-208: 
const turndownService = new TurndownService({
  headingStyle: 'atx',        // Use # for headings
  codeBlockStyle: 'fenced',   // Use ``` for code blocks
  bulletListMarker: '-'       // Use - for lists
});

​
Article Extraction

The server extracts content from <article> elements. Customize in lib/webhelp-search-client.ts:230-241: 
extractArticleElement(htmlContent: string): string {
  const dom = new JSDOM(htmlContent);
  const document = dom.window.document;
  
  const articleElement = document.querySelector('article');
  if (articleElement) {
    return articleElement.outerHTML;
  }
  
  return htmlContent; // Fallback to full HTML
}

​
Example: Production Configuration

Here’s a complete example for a production deployment: 
HTTPS_PROXY=http://corporate-proxy.company.com:8080

​
Next Steps

Vercel Deployment

Deploy your configured server to Vercel

Security

Secure your production deployment

Build docs developers (and LLMs) love

Get started for freeTalk to us