Alpic Docs

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.

The @alpic-ai/insights (TypeScript) and 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

TypeScript
Python SDK

bash pnpm add @alpic-ai/insights

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.

TypeScript — Skybridge
TypeScript — MCP SDK
Python SDK — FastMCP
Python SDK — low-level

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(/* ... */);

Use captureIntents, it accepts an McpServer and patches the tools/list and tools/call in place.

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);

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)

capture_intents also accepts mcp.server.lowlevel.Server. Register both the list_tools and call_tool handlers before enabling capture:

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

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

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:

TypeScript — Skybridge
TypeScript — MCP SDK
Python SDK

.mcpMiddleware(
  intentMiddleware({
    handler: async ({ toolName, userPrompt }) => {
      await myAnalytics.track("mcp_tool_call", { toolName, userPrompt });
    },
  }),
)

captureIntents(server, {
  handler: async ({ toolName, userPrompt }) => {
    await myAnalytics.track("mcp_tool_call", { toolName, userPrompt });
  },
});

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:

TypeScript — Skybridge
TypeScript — MCP SDK
Python SDK

.mcpMiddleware(
  intentMiddleware({
    tools: ["search", "ask"],
  }),
)

captureIntents(server, {
  tools: ["search", "ask"],
});

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.

TypeScript — Skybridge
TypeScript — MCP SDK
Python SDK

.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
    },
  }),
)

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
  },
});

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.

​Overview

​1. Install the package

​2. Wire it into your MCP app/server

​3. Deploy

​4. View intents in the dashboard

​5. Spot trends and signals

​Optional: run a custom handler alongside Alpic

​Optional: capture from specific tools only

​Optional: capture from an existing tool field

​6. Export your data