feat(server): MCP endpoints API consolidation (#2829)

## Overview

This PR serves as the foundational layer that will eventually merge all
upcoming PRs for the new test harness and new MCP integration tests for
multiple databases.

**Before** | **After**
--- | ---
<img width="1133" height="1032" alt="image"
src="https://github.com/user-attachments/assets/4a4fe226-aea8-43d7-9c80-fbedf0ce2e5b"
/> | <img width="1323" height="1539" alt="image"
src="https://github.com/user-attachments/assets/75526df2-3351-4dd9-a3d7-f3e04d177d0e"
/>

## Strategy
While the legacy integration tests continue to run over the legacy
`/api` endpoints, we are introducing the new native MCP JSON-RPC harness
in parallel. This allows us to verify both pathways side-by-side without
breaking existing CI coverage.

To support this, we utilize the `--enable-api` flag to control whether
the server initializes the legacy API handlers or runs in MCP-only mode.
This ensures that the new tests can accurately verify the behavior of
the server when running in its final intended configuration.

## Changes
- Updates to `internal/server/server.go` to support dynamic execution
and flag-controlled initialization.
- Frontend files updated (`loadTools.js` and `runTool.js`) to streamline
how tools are loaded and invoked in the UI, aligning it with the
upcoming native MCP transition.

## Checklist
- [x] Ensure the tests and linter pass
- [x] Manually verified functionality of Toolbox UI

---------

Co-authored-by: Yuan Teoh <yuanteoh@google.com>

Author: anubhav756

UPGRADING.md

@@ -26,7 +26,6 @@ If you still require the legacy `/api` endpoint, you must explicitly activate it
   endpoint exclusively, as the `/api` endpoint is now deprecated. If your workflow  
   relied on a non-standard feature that is missing from the new implementation, please submit a
   feature request on our [GitHub Issues page](https://github.com/googleapis/genai-toolbox/issues).
-* **UI Dependency:** Until the UI is officially migrated, it still requires the API to function. You must run the toolbox with both flags: `./toolbox --ui --enable-api`.
 
 ### 2. Strict Tool Naming Validation (SEP986)
 Tool names are now strictly validated against [ModelContextProtocol SEP986 guidelines](https://github.com/alexhancock/modelcontextprotocol/blob/main/docs/specification/draft/server/tools.mdx#tool-names) prior to MCP initialization.
@@ -110,4 +109,4 @@ The following CLI flags are deprecated and will be removed in a future release.
 
 * **Prebuilt Tools:** Toolsets have been resized for better performance.
 ## 📚 Documentation Moved
-Our official documentation has a new home! Please update your bookmarks to [mcp-toolbox.dev](http://mcp-toolbox.dev).
+Our official documentation has a new home! Please update your bookmarks to [mcp-toolbox.dev](http://mcp-toolbox.dev).

internal/server/server.go

@@ -32,6 +32,7 @@ import (
 	"github.com/go-chi/chi/v5/middleware"
 	"github.com/go-chi/cors"
 	"github.com/go-chi/httplog/v3"
+	"github.com/go-chi/render"
 	"github.com/googleapis/genai-toolbox/internal/auth"
 	"github.com/googleapis/genai-toolbox/internal/auth/generic"
 	"github.com/googleapis/genai-toolbox/internal/embeddingmodels"
@@ -469,6 +470,11 @@ func NewServer(ctx context.Context, cfg ServerConfig) (*Server, error) {
 			return nil, err
 		}
 		r.Mount("/api", apiR)
+	} else {
+		r.Handle("/api/*", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			err := errors.New("/api native endpoints are disabled by default. Please use the standard /mcp JSON-RPC endpoint")
+			_ = render.Render(w, r, newErrResponse(err, http.StatusGone))
+		}))
 	}
 	if cfg.UI {
 		webR, err := webRouter()

internal/server/static/js/loadTools.js

@@ -15,10 +15,10 @@
 import { renderToolInterface } from "./toolDisplay.js";
 import { escapeHtml } from "./sanitize.js";
 
-let toolDetailsAbortController = null;
+let currentToolsList = [];
 
 /**
- * Fetches a toolset from the /api/toolset endpoint and initiates creating the tool list.
+ * Fetches a toolset from the /mcp endpoint and initiates creating the tool list.
  * @param {!HTMLElement} secondNavContent The HTML element where the tool list will be rendered.
  * @param {!HTMLElement} toolDisplayArea The HTML element where the details of a selected tool will be displayed.
  * @param {string} toolsetName The name of the toolset to load (empty string loads all tools).
@@ -27,10 +27,24 @@ let toolDetailsAbortController = null;
 export async function loadTools(secondNavContent, toolDisplayArea, toolsetName) {
     secondNavContent.innerHTML = '<p>Fetching tools...</p>';
     try {
-        const response = await fetch(`/api/toolset/${toolsetName}`);
+        const url = toolsetName ? `/mcp/${toolsetName}` : `/mcp`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'MCP-Protocol-Version': '2025-11-25'
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: "1",
+                method: "tools/list",
+            })
+        });
+        
         if (!response.ok) {
             throw new Error(`HTTP error! status: ${response.status}`);
         }
+        
         const apiResponse = await response.json();
         renderToolList(apiResponse, secondNavContent, toolDisplayArea);
     } catch (error) {
@@ -41,33 +55,38 @@ export async function loadTools(secondNavContent, toolDisplayArea, toolsetName)
 
 /**
  * Renders the list of tools as buttons within the provided HTML element.
- * @param {?{tools: ?Object<string,*>} } apiResponse The API response object containing the tools.
+ * @param {Object} apiResponse The API response object containing the tools.
  * @param {!HTMLElement} secondNavContent The HTML element to render the tool list into.
  * @param {!HTMLElement} toolDisplayArea The HTML element for displaying tool details (passed to event handlers).
  */
 function renderToolList(apiResponse, secondNavContent, toolDisplayArea) {
     secondNavContent.innerHTML = '';
 
-    if (!apiResponse || typeof apiResponse.tools !== 'object' || apiResponse.tools === null) {
-        console.error('Error: Expected an object with a "tools" property, but received:', apiResponse);
+    if (apiResponse && apiResponse.error) {
+        console.error('MCP API Error:', apiResponse.error);
+        secondNavContent.textContent = `Error: ${apiResponse.error.message || 'Unknown MCP error'}`;
+        return;
+    }
+
+    if (!apiResponse || !apiResponse.result || !Array.isArray(apiResponse.result.tools)) {
+        console.error('Error: Expected a valid MCP response with "result.tools" array, but received:', apiResponse);
         secondNavContent.textContent = 'Error: Invalid response format from toolset API.';
         return;
     }
 
-    const toolsObject = apiResponse.tools;
-    const toolNames = Object.keys(toolsObject);
+    currentToolsList = apiResponse.result.tools;
 
-    if (toolNames.length === 0) {
+    if (currentToolsList.length === 0) {
         secondNavContent.textContent = 'No tools found.';
         return;
     }
 
     const ul = document.createElement('ul');
-    toolNames.forEach(toolName => {
+    currentToolsList.forEach(toolObj => {
         const li = document.createElement('li');
         const button = document.createElement('button');
-        button.textContent = toolName;
-        button.dataset.toolname = toolName;
+        button.textContent = toolObj.name;
+        button.dataset.toolname = toolObj.name;
         button.classList.add('tool-button');
         button.addEventListener('click', (event) => handleToolClick(event, secondNavContent, toolDisplayArea));
         li.appendChild(button);
@@ -90,86 +109,81 @@ function handleToolClick(event, secondNavContent, toolDisplayArea) {
             currentActive.classList.remove('active');
         }
         event.target.classList.add('active');
-        fetchToolDetails(toolName, toolDisplayArea);
+        renderToolDetails(toolName, toolDisplayArea);
     }
 }
 
 /**
- * Fetches details for a specific tool /api/tool endpoint.
- * It aborts any previous in-flight request for tool details to stop race condition.
- * @param {string} toolName The name of the tool to fetch details for.
+ * Renders details for a specific tool from the cached MCP tools list.
+ * @param {string} toolName The name of the tool to render details for.
  * @param {!HTMLElement} toolDisplayArea The HTML element to display the tool interface in.
- * @returns {!Promise<void>} A promise that resolves when the tool details are fetched and rendered, or rejects on error.
  */
-async function fetchToolDetails(toolName, toolDisplayArea) {
-    if (toolDetailsAbortController) {
-        toolDetailsAbortController.abort();
-        console.debug("Aborted previous tool fetch.");
-    }
+function renderToolDetails(toolName, toolDisplayArea) {
+    const toolObject = currentToolsList.find(t => t.name === toolName);
 
-    toolDetailsAbortController = new AbortController();
-    const signal = toolDetailsAbortController.signal;
+    if (!toolObject) {
+        toolDisplayArea.innerHTML = `<p class="error">Tool "${escapeHtml(toolName)}" data not found.</p>`;
+        return;
+    }
 
-    toolDisplayArea.innerHTML = '<p>Loading tool details...</p>';
+    console.debug("Rendering tool object: ", toolObject);
 
-    try {
-        const response = await fetch(`/api/tool/${encodeURIComponent(toolName)}`, { signal });
-        if (!response.ok) {
-                throw new Error(`HTTP error! status: ${response.status}`);
+    let toolAuthRequired = [];
+    let toolAuthParams = {};
+    if (toolObject._meta) {
+        if (toolObject._meta["toolbox/authInvoke"]) {
+            toolAuthRequired = toolObject._meta["toolbox/authInvoke"];
         }
-        const apiResponse = await response.json();
-
-        if (!apiResponse.tools || !apiResponse.tools[toolName]) {
-            throw new Error(`Tool "${toolName}" data not found in API response.`);
+        if (toolObject._meta["toolbox/authParam"]) {
+            toolAuthParams = toolObject._meta["toolbox/authParam"];
         }
-        const toolObject = apiResponse.tools[toolName];
-        console.debug("Received tool object: ", toolObject)
-
-        const toolInterfaceData = {
-            id: toolName,
-            name: toolName,
-            description: toolObject.description || "No description provided.",
-            authRequired: toolObject.authRequired || [],
-            parameters: (toolObject.parameters || []).map(param => {
-                let inputType = 'text'; 
-                const apiType = param.type ? param.type.toLowerCase() : 'string';
-                let valueType = 'string'; 
-                let label = param.description || param.name;
-
-                if (apiType === 'integer' || apiType === 'float') {
-                    inputType = 'number';
-                    valueType = 'number';
-                } else if (apiType === 'boolean') {
-                    inputType = 'checkbox';
-                    valueType = 'boolean';
-                } else if (apiType === 'array') {
-                    inputType = 'textarea'; 
-                    const itemType = param.items && param.items.type ? param.items.type.toLowerCase() : 'string';
-                    valueType = `array<${itemType}>`;
-                    label += ' (Array)';
-                }
-
-                return {
-                    name: param.name,
-                    type: inputType,    
-                    valueType: valueType, 
-                    label: label,
-                    authServices: param.authServices, // TODO: to be updated when the native endpoint is no longer supported.
-                    required: param.required || false,
-                    // defaultValue: param.default, can't do this yet bc tool manifest doesn't have default
-                };
-            })
-        };
-
-        console.debug("Transformed toolInterfaceData:", toolInterfaceData);
+    }
 
-        renderToolInterface(toolInterfaceData, toolDisplayArea);
-    } catch (error) {
-        if (error.name === 'AbortError') {
-            console.debug("Previous fetch was aborted, expected behavior.");
-        } else {
-            console.error(`Failed to load details for tool "${toolName}":`, error);
-            toolDisplayArea.innerHTML = `<p class="error">Failed to load details for ${escapeHtml(toolName)}. ${escapeHtml(error.message)}</p>`;
-        }
+    // Default processing if inputSchema properties are not present
+    let toolParameters = [];
+    if (toolObject.inputSchema && toolObject.inputSchema.properties) {
+        const props = toolObject.inputSchema.properties;
+        const requiredFields = toolObject.inputSchema.required || [];
+
+        toolParameters = Object.keys(props).map(paramName => {
+            const param = props[paramName];
+            let inputType = 'text'; 
+            const apiType = param.type ? param.type.toLowerCase() : 'string';
+            let valueType = 'string'; 
+            let label = param.description || paramName;
+
+            if (apiType === 'integer' || apiType === 'number') {
+                inputType = 'number';
+                valueType = 'number';
+            } else if (apiType === 'boolean') {
+                inputType = 'checkbox';
+                valueType = 'boolean';
+            } else if (apiType === 'array') {
+                inputType = 'textarea'; 
+                const itemType = param.items && param.items.type ? param.items.type.toLowerCase() : 'string';
+                valueType = `array<${itemType}>`;
+                label += ' (Array)';
+            }
+
+            return {
+                name: paramName,
+                type: inputType,    
+                valueType: valueType, 
+                label: label,
+                required: requiredFields.includes(paramName),
+                authServices: toolAuthParams[paramName] || []
+            };
+        });
     }
+
+    const toolInterfaceData = {
+        id: toolName,
+        name: toolName,
+        description: toolObject.description || "No description provided.",
+        authRequired: toolAuthRequired,
+        parameters: toolParameters
+    };
+
+    console.debug("Transformed toolInterfaceData:", toolInterfaceData);
+    renderToolInterface(toolInterfaceData, toolDisplayArea);
 }

internal/server/static/js/runTool.js

@@ -80,15 +80,33 @@ export async function handleRunTool(toolId, form, responseArea, parameters, pret
 
     console.debug('Running tool:', toolId, 'with typed params:', typedParams);
     try {
-        const response = await fetch(`/api/tool/${toolId}/invoke`, {
+        const body = {
+            jsonrpc: "2.0",
+            id: "2",
+            method: "tools/call",
+            params: {
+                name: toolId,
+                arguments: typedParams
+            }
+        };
+
+        const mcpHeaders = { 
+            ...headers, 
+            'Content-Type': 'application/json',
+            'MCP-Protocol-Version': '2025-11-25'
+        };
+
+        const response = await fetch(`/mcp`, {
             method: 'POST',
-            headers: headers,
-            body: JSON.stringify(typedParams)
+            headers: mcpHeaders,
+            body: JSON.stringify(body)
         });
+
         if (!response.ok) {
             const errorBody = await response.text();
             throw new Error(`HTTP error ${response.status}: ${errorBody}`);
         }
+        
         const results = await response.json();
         updateLastResults(results);
         displayResults(results, responseArea, prettifyCheckbox.checked);
@@ -144,19 +162,34 @@ export function displayResults(results, responseArea, prettify) {
     if (results === null || results === undefined) {
         return;
     }
+
+    if (results.error) {
+        responseArea.value = `MCP Error ${results.error.code}: ${results.error.message}\n${JSON.stringify(results.error.data, null, 2) || ''}`;
+        return;
+    }
+
     try {
-        const resultJson = JSON.parse(results.result);
-        if (prettify) {
-            responseArea.value = JSON.stringify(resultJson, null, 2);
+        let textContent = "";
+        if (results.result && Array.isArray(results.result.content)) {
+            textContent = results.result.content
+                .filter(c => c.type === 'text' && typeof c.text === 'string')
+                .map(c => c.text)
+                .join('\n');
+        } else if (results.result && typeof results.result.content === 'string') {
+            textContent = results.result.content;
         } else {
-            responseArea.value = JSON.stringify(resultJson);
+            textContent = JSON.stringify(results.result, null, 2);
+        }
+
+        try {
+            const resultJson = JSON.parse(textContent);
+            responseArea.value = prettify ? JSON.stringify(resultJson, null, 2) : JSON.stringify(resultJson);
+        } catch (e) {
+            // Not pure JSON string, output as-is
+            responseArea.value = textContent;
         }
     } catch (error) {
         console.error("Error parsing or stringifying results:", error);
-        if (typeof results.result === 'string') {
-            responseArea.value = results.result;
-        } else {
-            responseArea.value = "Error displaying results. Invalid format.";
-        }
+        responseArea.value = typeof results === 'object' ? JSON.stringify(results, null, 2) : String(results);
     }
 }