1st draft not ready for review final 2 part run through required

Author: TuannasCodeCatastrophe

app/_how-tos/use-insomnia-mcp-clients-to-test-aggregated-mcp-tools.md

@@ -0,0 +1,124 @@
+---
+title: Use Insomnia MCP clients to test aggregated MCP tools
+content_type: how_to
+description: Learn how to use Insomnia 12.1 MCP clients to test MCP tools exposed by AI MCP Proxy in listener mode after they have been aggregated from multiple upstream APIs.
+
+products:
+  - insomnia
+  - ai-gateway
+
+related_resources:
+  - text: Aggregate MCP tools from multiple AI MCP Proxy plugins
+    url: /mcp/aggregate-mcp-tools/
+  - text: MCP clients in Insomnia
+    url: /insomnia/mcp/
+
+min_version:
+  insomnia: "12.0"
+
+tags:
+  - ai
+  - mcp
+
+tools:
+  - deck
+
+prereqs:
+  inline:
+    - title: Aggregated MCP server
+      content: |
+        Before testing with Insomnia, complete the [Aggregate MCP tools from multiple AI MCP Proxy plugins](/mcp/aggregate-mcp-tools/) guide.  
+        That guide produces:
+
+        - Multiple conversion-only AI MCP Proxy plugin instances that each expose MCP tools  
+        - One listener-mode AI MCP Proxy plugin aggregating those tools by tag  
+        - A public listener endpoint:
+          ```
+          http://localhost:8000/mcp-listener
+          ```
+      icon_url: /assets/icons/mcp.svg
+
+    - title: Network access
+      content: |
+        Ensure your local machine can reach the listener endpoint produced during aggregation.
+
+        Test connectivity:
+        ```
+        curl http://localhost:8000/mcp-listener
+        ```  
+tldr:
+  q: How do I test aggregated MCP tools using Insomnia?
+  a: |
+    Connect an Insomnia MCP client to the listener-mode AI MCP Proxy endpoint created during the aggregation setup. Then invoke each tool and validate behaviour using Insomnia’s Params, Headers, Events, and Console panels.
+---
+
+Use Insomnia to connect to an MCP server exposed through the AI MCP Proxy plugin in listener mode. 
+
+This listener server aggregates MCP tools from multiple upstream APIs, enabling you to validate end-to-end behaviour using Insomnia’s Params, Headers, Events, and Console panels.
+
+After completing the aggregation workflow described in **[Aggregate MCP tools from multiple AI MCP Proxy plugins](/mcp/aggregate-mcp-tools/)** and exposing an autogenerated or aggregated MCP server, follow this guide to test and validate its MCP tools using Insomnia’s MCP Clients:
+
+## Create an MCP client
+
+1. Open **Insomnia**.
+2. In the left sidebar, click **MCP Clients**.
+3. Click **New MCP Client**.
+4. In the **Name** field, enter a name:
+       Aggregated MCP Tools
+5. In the **MCP Server URL** field, enter your listener URL:
+       http://localhost:8000/mcp-listener
+6. Click **Connect**.
+
+Insomnia connects to the MCP server and discovers all aggregated tools.
+
+## Validate discovered tools
+
+1. In toolbar, locate the **Tools** drop-down section.
+2. Review the list of available tools.  
+
+If any tools are missing:
+
+- Confirm all conversion-only plugins use the same `tags[]` value.
+- Confirm that the listener-mode plugin’s `server.tag` matches that value.
+- Confirm that the listener Route is active and reachable.
+
+## Invoke and test tools
+
+Use Insomnia’s testing panels to validate MCP tool behaviour. Complete the following process to run a tool:
+
+1. In **Tools**, click any tool.
+2. Click the **Params** tab.
+3. Enter parameter values.
+4. Click **Call Tool**.
+5. Click the **Console** tab.
+
+## Debug tool behaviour using Insomnia panels
+
+Insomnia provides several panels to validate MCP activity:
+
+- **Params**: Verify the parameters passed to the tool.  
+- **Headers (Request)**: Inspect headers added by plugins such as Request Transformer Advanced.  
+- **Headers (Response)**: Validate response headers and status.  
+- **Events**: View lifecycle and authentication events.  
+- **Console**: Inspect raw MCP JSON-RPC requests and responses.
+
+Use these panels to confirm:
+
+- Correct parameter mapping  
+- Correct API key injection (if configured)  
+- Upstream connectivity  
+- Schema-correct JSON responses  
+
+
+## Validate aggregated MCP behaviour end-to-end
+
+1. Select any tool.
+2. Click **Call Tool**.
+3. Open the **Console** tab.
+4. Confirm:
+   - The MCP request structure is valid  
+   - The listener-mode MCP Proxy plugin processes the request  
+   - The upstream service responds successfully  
+   - The returned JSON matches the tool’s schema  
+
+A successful response confirms that your aggregated MCP configuration is working correctly.