DOC-1787 Set expectations with MCP server (#144)

* DOC-1787

* Make number of results configurable

* Apply suggestions from code review

Co-authored-by: Joyce Fee <[email protected]>

---------

Co-authored-by: Joyce Fee <[email protected]>

Author: JakeSCahill

home/modules/ROOT/pages/mcp-setup.adoc

@@ -20,6 +20,7 @@ Add the following to your `.cursor/mcp.json` file:
 {
   "mcpServers": {
     "redpanda": {
+      "type": "http",
       "url": "https://docs.redpanda.com/mcp"
     }
   }
@@ -98,6 +99,7 @@ Add this configuration:
 {
   "mcpServers": {
     "redpanda": {
+      "type": "http",
       "url": "https://docs.redpanda.com/mcp"
     }
   }
@@ -110,6 +112,26 @@ For more details, see the https://support.anthropic.com/en/articles/9487310-desk
 --
 ====
 
+== Intended use
+
+This public MCP endpoint is designed for:
+
+* Evaluation and testing
+* IDE-based assistance and ad-hoc queries
+* Individual developer productivity
+
+*Not suitable for:*
+
+* High-volume automation or batch processing
+* Production services or runbooks
+* CI/CD pipelines or scheduled jobs
+
+=== Technical specifications
+
+* *Transport*: HTTP with Server-Sent Events (SSE) streaming support
+* *Rate limit*: 60 requests per 15-minute window per client
+* *Authentication*: None required for public endpoint
+
 == Other AI tools
 
 Any tool that supports MCP servers can connect using the following URL:
@@ -134,14 +156,23 @@ Once connected, you can ask context-aware questions about Redpanda from within y
 
 == Usage limits
 
-To ensure fair use and performance, the server enforces a rate limit of **60 questions per 15-minute window**.
+To ensure fair use and performance for all users, the public MCP endpoint enforces a rate limit of **60 requests per 15-minute window** per client.
+
+This limit is suitable for:
 
-If you exceed the limit, you receive an HTTP 429 response. Wait a few minutes before retrying.
+* Individual developer IDE usage
+* Ad-hoc documentation queries
+* Evaluation and testing
 
-.Expected response
+If you exceed the limit, you receive an HTTP 429 response with rate limit headers. Wait until the reset time before retrying.
+
+.Rate limit exceeded response
 [source,text]
 ----
 HTTP 429 Too Many Requests
+RateLimit-Limit: 60
+RateLimit-Remaining: 0
+RateLimit-Reset: <timestamp>
 ----
 
 == Troubleshooting
@@ -160,6 +191,19 @@ HTTP 429 Too Many Requests
 * Try running **MCP: Reset Cached Tools** from the Command Palette.
 * Check the Output panel (*View* > *Output* > *MCP*) for error messages.
 
+=== Configuration issues
+
+* Ensure `"type": "http"` is specified in your configuration for HTTP-based MCP servers.
+* Some MCP clients may have issues with SSE streaming. If you experience connection problems, verify that your client supports HTTP-based MCP servers with Server-Sent Events (SSE).
+* Check that your client's Accept headers include both `application/json` and `text/event-stream`.
+
+=== Rate limiting
+
+If you're building automation or high-volume integrations and hitting rate limits frequently:
+
+* The public endpoint's rate limits (60 requests per 15 minutes) are intentionally restrictive for fair use.
+* Consider implementing caching on your side to reduce duplicate queries.
+
 === Other issues
 
 Check the https://github.com/modelcontextprotocol/servers[MCP GitHub repository^] for additional troubleshooting guidance or https://github.com/redpanda-data/docs-site/issues[report an issue^] with our documentation.

netlify/edge-functions/mcp.js

@@ -66,7 +66,7 @@ const computeLimiterKey = (c) => {
   return `ua:${ua}|${accept}`
 }
 
-const SERVER_VERSION = '0.2.0';
+const SERVER_VERSION = '0.3.0';
 
 // Initialize MCP Server and register tools
 const server = new McpServer({
@@ -79,8 +79,11 @@ server.registerTool(
   'ask_redpanda_question',
   {
     title: 'Search Redpanda Sources',
-    description: 'Search the official Redpanda documentation and return the most relevant sections from it for a user query. Each returned section includes the url and its actual content in markdown. Use this tool to for all queries that require Redpanda knowledge.',
-    inputSchema: { question: z.string() },
+    description: 'Search the official Redpanda documentation and return the most relevant sections from it for a user query. Each returned section includes the url and its actual content in markdown. Use this tool for all queries that require Redpanda knowledge. Results are ordered by relevance, with the most relevant result returned first. Returns up to 5 results by default to manage token usage. Use top_k parameter (1-15) to request more or fewer results.',
+    inputSchema: {
+      question: z.string(),
+      top_k: z.number().int().min(1).max(15).optional().describe('Number of results to return (1-15). Defaults to 5 for optimal token usage.')
+    },
   },
   async (args) => {
     const q = (args?.question ?? '').trim();
@@ -89,6 +92,9 @@ server.registerTool(
         content: [{ type: 'text', text: JSON.stringify({ error: 'missing_query', message: 'Provide a non-empty "question".' }) }]
       };
     }
+    // Extract top_k parameter with default of 5, clamped to valid range
+    const topK = Math.max(1, Math.min(15, args?.top_k ?? 5));
+
     try {
       const response = await fetch(
         `${API_BASE}/query/v1/projects/${KAPA_PROJECT_ID}/retrieval/`,
@@ -101,6 +107,7 @@ server.registerTool(
           body: JSON.stringify({
             integration_id: KAPA_INTEGRATION_ID,
             query: q,
+            top_k: topK,
           }),
         }
       );