Skip to main content

​
Overview

MCP apps and servers can see tool calls and their parameters, but not the conversation that triggered them. User Intents offer an easy way to gather the user’s intent behind each tool call, and help you analyze and categorise them.
User Intent dashboard
The @alpic-ai/insights package dynamically adds an extra parameter to all your tools, asking the LLM to include the user intent while making sure to remove any Personally Identifiable Information. Alpic then collects and stores those intents for you to explore.

​
1. Install the package

pnpm add @alpic-ai/insights

​
2. Wire it into your MCP app/server

The package ships two entry points depending on which MCP framework you’re using.
Use intentMiddleware: it returns a Skybridge McpMiddlewareFn you can register via mcpMiddleware(). Add it before your tool/widget registrations:
import { intentMiddleware } from "@alpic-ai/insights";
import { McpServer } from "skybridge/server";

const server = new McpServer(
  { name: "my-mcp-server", version: "1.0.0" },
  { capabilities: {} },
)
  .mcpMiddleware(intentMiddleware())
  .registerTool(/* ... */);

​
3. Deploy

Deploy your application on Alpic as usual. As soon as the new version is live on the production environment, intents start flowing in.

​
4. View intents in the dashboard

In the Alpic dashboard, open your project and click the Insights tab. You’ll see a paginated table with four columns:
  • Intent: the user’s intent behind the tool call, summarized by the LLM.
  • Tool: the name of the tool that was called.
  • Category: automatically categorized into a reusable label. You can modify it directly in the table.
  • Date: the timestamp of the tool call.
Hot Categories & Signals offer you a high-level overview of user intents trends over the selected period.
Hot categories and Signals cards above the intents table
Hot categories show you the most common intent categories. It helps you understand what your users are trying to do with your MCP App/server. Signals give you an overview of the important trends in user intent between the current period and the previous one. Switch the time range to update it.

​
Optional: run a custom handler alongside Alpic

Pass a handler to run your own logic (e.g. sending intents to your own analytics pipeline) on every captured intent. The handler runs in addition to Alpic’s dashboard delivery, intents still appear in the User Insights page. The handler runs inside your MCP server process: 
.mcpMiddleware(
  intentMiddleware({
    handler: async ({ toolName, userPrompt }) => {
      await myAnalytics.track("mcp_tool_call", { toolName, userPrompt });
    },
  }),
)

​
Optional: capture from specific tools only

By default, intentMiddleware injects the user_intent field into every tool’s schema. Use the tools option to restrict capture to a subset of your tools: 
.mcpMiddleware(
  intentMiddleware({
    tools: ["search", "ask"],
  }),
)

​
Optional: capture from an existing tool field

If your tool already has a parameter that conveys user intent (for example, a query, rationale, or question parameter on a search tool), you can capture its value instead of asking the LLM to copy the intent into a synthetic user_intent field. Use the argumentNameOverride option: a map of tool names to the input field whose value should be captured as the intent. 
.mcpMiddleware(
  intentMiddleware({
    argumentNameOverride: {
      search: "query",  // The tool "search" has a "query" parameter that conveys user intent
      ask: "question",  // The tool "ask" has a "question" parameter that conveys user intent
    },
  }),
)

​
6. Export your data

Export your intent data as a CSV file whenever you want to analyze it in your own tools or combine it with your existing workflows.