> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alpic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# User Intents

> Understand what your users really want from your plugin.

### 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](https://mintcdn.com/alpic/Xn2W6iZnB0gwz_IL/images/user-intent-dashboard.png?fit=max\&auto=format\&n=Xn2W6iZnB0gwz_IL\&q=85\&s=1dbdcba71378b6c1fda9c590d011ee07)

The [`@alpic-ai/insights`](https://www.npmjs.com/package/@alpic-ai/insights) (TypeScript) and
[`alpic-ai-insights`](https://pypi.org/project/alpic-ai-insights/) (Python SDK) packages dynamically add 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

> [tab] TypeScript
>
> `bash pnpm add @alpic-ai/insights `

> [tab] Python SDK
>
> `bash pip install alpic-ai-insights # or: uv add alpic-ai-insights `

### 2. Wire it into your MCP app/server

Choose the entry point for your language and MCP framework.

> [tab] TypeScript — Skybridge v2
>
> Use `intentMiddleware`: it returns a Skybridge `McpMiddlewareFn` you can register via `mcpMiddleware()`. Add it
> inside the Skybridge v2 `handler`, before your tool/widget registrations:
>
> ```typescript theme={null}
> import { intentMiddleware } from "@alpic-ai/insights";
> import { Skybridge } from "skybridge/server";
>
> const app = new Skybridge({
>   name: "my-mcp-server",
>   version: "1.0.0",
>   handler: (server) => server
>     .mcpMiddleware(intentMiddleware())
>     .registerTool(/* ... */),
> });
> ```

> [tab] TypeScript — Skybridge 0.36 / v1
>
> With Skybridge 0.36 or v1, add the middleware to the existing `McpServer` before registering tools:
>
> ```typescript theme={null}
> 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(/* ... */);
> ```

> [tab] TypeScript — MCP SDK v1
>
> Use `captureIntents`, it accepts an `McpServer` and patches the `tools/list` and `tools/call` in place.
>
> ```typescript theme={null}
> import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
> import { captureIntents } from "@alpic-ai/insights";
>
> const server = new McpServer(
>   { name: "my-mcp-server", version: "1.0.0" },
>   { capabilities: {} },
> );
>
> server.registerTool(/* ... */);
>
> captureIntents(server);
> ```

> [tab] Python SDK — FastMCP
>
> Register your tools first, then call `capture_intents` before starting the server:
>
> ```python theme={null}
> from alpic_ai_insights import capture_intents
> from mcp.server.fastmcp import FastMCP
>
> mcp = FastMCP("my-mcp-server")
>
> @mcp.tool()
> def search(query: str) -> str:
>     return query
>
> capture_intents(mcp)
> ```

> [tab] Python SDK — low-level
>
> `capture_intents` also accepts `mcp.server.lowlevel.Server`. Register both the `list_tools` and `call_tool`
> handlers before enabling capture:
>
> ```python theme={null}
> from typing import Any
>
> from alpic_ai_insights import capture_intents
> from mcp import types
> from mcp.server.lowlevel import Server
>
> server = Server("my-mcp-server")
>
> @server.list_tools()
> async def list_tools() -> list[types.Tool]:
>     return [
>         types.Tool(
>             name="search",
>             inputSchema={
>                 "type": "object",
>                 "properties": {"query": {"type": "string"}},
>                 "required": ["query"],
>             },
>         )
>     ]
>
> @server.call_tool()
> async def call_tool(name: str, arguments: dict[str, Any]):
>     return [types.TextContent(type="text", text=str(arguments["query"]))]
>
> capture_intents(server)
> ```

The `FastMCP` example above uses the class bundled with the official MCP Python SDK
(`mcp.server.fastmcp.FastMCP`), not the separate `fastmcp` package.

### 3. Deploy

Deploy your application on Alpic as usual. As soon as the new version is live on the [production environment](https://docs.alpic.ai/build-deploy/environments.md), 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 the following columns:

* **Intent:** the user's intent behind the tool call, summarized by the LLM.
* **Tool:** the name of the tool that was called.
* **Client:** the MCP client the call came from (ChatGPT, Claude, Cursor, ...).
* **Category:** automatically categorized into a reusable label. You can modify it directly in the table.
* **Date:** the timestamp of the tool call.
* **Replay:** a link to the matching session replay, shown when [session replay](https://docs.alpic.ai/analytics/privacy.md) is enabled.

Identical intents on the same tool are grouped into a single row with a `×N` badge showing how many times they
occurred. Changing the category on a grouped row applies it to every occurrence in the group.

Use the search box to look through intents, tools and categories, and the **Filters** button to narrow the table by
tool, client, or category. Select rows to categorize or delete several intents at once.

### 5. Spot trends and signals

**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](https://mintcdn.com/alpic/ynBj7kasaXZp_B8j/images/insights-trends-and-signals.png?fit=max\&auto=format\&n=ynBj7kasaXZp_B8j\&q=85\&s=16a92366b9aef59d1d916e35a88df737)

**Hot categories** show you the most common intent categories. It helps you understand what your users are trying to do with your plugin.

**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:

> [tab] TypeScript — Skybridge
>
> ```typescript theme={null}
> .mcpMiddleware(
>   intentMiddleware({
>     handler: async ({ toolName, userPrompt }) => {
>       await myAnalytics.track("mcp_tool_call", { toolName, userPrompt });
>     },
>   }),
> )
> ```

> [tab] TypeScript — MCP SDK v1
>
> ```typescript theme={null}
> captureIntents(server, {
>   handler: async ({ toolName, userPrompt }) => {
>     await myAnalytics.track("mcp_tool_call", { toolName, userPrompt });
>   },
> });
> ```

> [tab] Python SDK
>
> ```python theme={null}
> async def handle_intent(prompt):
>     await analytics.track(
>         "mcp_tool_call",
>         {"tool_name": prompt.tool_name, "user_prompt": prompt.user_prompt},
>     )
>
> capture_intents(mcp, handler=handle_intent)
> ```

### 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:

> [tab] TypeScript — Skybridge
>
> ```typescript theme={null}
> .mcpMiddleware(
>   intentMiddleware({
>     tools: ["search", "ask"],
>   }),
> )
> ```

> [tab] TypeScript — MCP SDK v1
>
> ```typescript theme={null}
> captureIntents(server, {
>   tools: ["search", "ask"],
> });
> ```

> [tab] Python SDK
>
> ```python theme={null}
> capture_intents(mcp, 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 in TypeScript or `argument_name_override` in Python: a map of tool names to
the input field whose value should be captured as the intent.

> [tab] TypeScript — Skybridge
>
> ```typescript theme={null}
> .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
>     },
>   }),
> )
> ```

> [tab] TypeScript — MCP SDK v1
>
> ```typescript theme={null}
> captureIntents(server, {
>   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
>   },
> });
> ```

> [tab] Python SDK
>
> ```python theme={null}
> capture_intents(
>     mcp,
>     argument_name_override={
>         "search": "query",
>         "ask": "question",
>     },
> )
> ```

### 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.