> ## Documentation Index > Fetch the complete documentation index at: https://docs.hyperline.co/llms.txt > Use this file to discover all available pages before exploring further. # MCP server > Connect your own MCP server so the customer monitoring agent can use data from your internal tools when it analyzes a customer. The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that exposes data from a system to AI agents as **tools**. Each tool has a name, a description, and the inputs it accepts. Connecting an MCP server lets the [customer monitoring agent](https://docs.hyperline.co/docs/customer-intelligence/customer-monitoring-agent.md) look up data that only lives in your own systems, such as product usage, NPS scores, account notes, or internal health indicators. The agent combines that data with contract, subscription, invoice, payment, and usage data from Hyperline. > [!NOTE] > > MCP servers are part of [Customer intelligence](https://docs.hyperline.co/docs/customer-intelligence/overview.md), a paid add-on. Contact the Hyperline team through the in-app chat to enable it. > [!NOTE] > > This page covers connecting **your** MCP server to Hyperline. To use Hyperline from an AI assistant such as Claude or Cursor, see the [Hyperline MCP server](https://docs.hyperline.co/developers/ai/mcp.md). ## Prerequisites * An MCP server that uses the Streamable HTTP transport. * A server URL that starts with `https://` and is reachable from the internet. Hyperline rejects local and private network addresses, and URLs that contain a username or password. * A bearer token or an API key, if the server requires authentication. * Tools marked as read-only by the server. See [Read-only tools](#read-only-tools). ## Connect an MCP server **1. Go to Settings > Integrations and open the Data tab** **2. Click Connect on MCP server** **3. Fill in the connection details** * **Name**: the name the agent and your team see, for example `Product usage`. * **Server URL**: the HTTPS address of the server. * **Authentication**: **None**, **Bearer token**, or **API key**. For a bearer token or an API key, paste the value in the field that appears. **4. Click Connect** The server appears in your active integrations. ![Connect an MCP server dialog with a name, a server URL, and a bearer token](https://mintcdn.com/hyperline/5cJz5wCG2lC7BnM7/images/integrations/mcp-server/connect-modal.png?fit=max\&auto=format\&n=5cJz5wCG2lC7BnM7\&q=85\&s=2510407e55f47bf2d1242e3aaa04a07b) You can connect several MCP servers, for example one per internal system. > [!NOTE] > > Hyperline sends a bearer token in the `Authorization` header (`Bearer `) and an API key in the `x-api-key` header. ## Check the connection and its tools Open the MCP server from **Settings > Integrations** to manage it: | Section | What it shows | | - | - | | **Connection** | The name, server URL, and authentication method. To keep the stored credential when you edit the server, leave the credential field empty. | | **Status** | The **Health** of the connection (`Healthy`, `Unhealthy`, or `Not checked`) and the **Last check** date. When the connection fails, the error appears under **Connection failed**. | | **Tools** | The tools the server exposes, with their description. Tools the server marks as read-only show a **Read-only** tag. | Click **Test connection** to check the server again and refresh its list of tools. ![Status and Tools sections of an MCP server, with three tools tagged Read-only](https://mintcdn.com/hyperline/5cJz5wCG2lC7BnM7/images/integrations/mcp-server/status-and-tools.png?fit=max\&auto=format\&n=5cJz5wCG2lC7BnM7\&q=85\&s=e71aaf56f699a0a9ee6a1c704ffcd20d) ## Enable the server for an agent A connected MCP server is not used until you enable it on an agent. 1. Go to **Customers > Monitoring** and open the agent. 2. Go to the **Connectors** tab. 3. Turn on the toggle next to the MCP server. 4. Click **Save changes**. ![Connectors tab of a monitoring agent with the Product usage MCP server turned on](https://mintcdn.com/hyperline/5cJz5wCG2lC7BnM7/images/integrations/mcp-server/agent-connectors.png?fit=max\&auto=format\&n=5cJz5wCG2lC7BnM7\&q=85\&s=957987c2cd74fb1e9b836642e2881f1d) Each agent has its own selection, so you can enable a server on one agent and not on another. ## How the agent uses MCP tools At the start of each run, the agent loads the tools of every MCP server enabled on it. Changes you make to the server's tools apply from the next run. During an analysis, the agent decides which tools to call and what to send them, based on the tool names, descriptions, and inputs, and on the agent's **Context**. The tools the agent called appear in **Data sources and tools used** on the analysis result. ### Read-only tools The agent runs on its own only the tools the server marks as read-only. A tool counts as read-only when the server sets its `readOnlyHint` annotation and does not set `destructiveHint`. The agent never runs a tool that is not marked this way on its own, even when the tool only reads data. If a tool you expect is missing from the agent's analyses, check that it shows the **Read-only** tag in the **Tools** section, and ask the team that maintains the server to add the annotation. ## Configure the agent's context The agent picks MCP tools from their names and descriptions only. To get reliable results, explain your data in the agent's **Context** tab: 1. Go to **Customers > Monitoring** and open the agent. 2. Go to the **Context** tab. 3. Fill in **General context** and **Scoring instructions**, as described below. 4. Click **Save changes**. | Field | What to write | | - | - | | **General context** | Which MCP server and tool hold the data, the identifier and filter to send for a customer, and what each field means: its unit, its period, and its possible values. | | **Scoring instructions** | Which dimension each field counts in, and which values or notes are risk signals or expansion signals. | The agent knows each customer's Hyperline ID, name, and domain. Name the one your server expects, and write field names exactly as the server returns them. > [card] Example 💡 > > Your product usage export lists one row per customer per month, keyed by Hyperline customer ID. Write the following in the agent's **Context** tab: > > ```text General context wrap theme={null} > Product usage data lives in the "Product usage" MCP server: one row per customer per month. > To read a customer's history, call its query tool with the Hyperline customer ID in the customer_id filter. > > Columns: > - seats_purchased > - active_users > - logins > - feature_adoption_pct > - nps_score (filled some months only) > - champion_status: engaged, unresponsive or left_company > - csm_owner > - account_note > ``` > > ```text Scoring instructions wrap theme={null} > Usage and engagement: active_users, logins and feature_adoption_pct, compared with seats_purchased and over time. > Communication: nps_score and champion_status. > Churn signals: account notes about a competitor, a termination quote or a champion who left. > Expansion signals: account notes asking for more seats or an add-on. > ``` > > The agent then reads each customer's usage history, weighs it in the **Usage and engagement** and **Communication** dimensions, and lists the notes in the positive signals or risk factors. > [!TIP] > > Keep both fields short and specific to your data. The agent reads them for every customer it analyzes. ## Check the result 1. Open the agent and click **Actions > Trigger analysis**. 2. Select one or two customers whose data you know, and start the run. 3. Open an analysis. The MCP tools the agent called appear in **Data sources and tools used**, and the reasoning cites the data they returned. If the agent did not call your tools, check the **Troubleshooting** table below, then make the **General context** more explicit about which tool to call. ## Troubleshooting | Issue | What to check | | - | - | | **Health** shows `Unhealthy` | The server URL, that it starts with `https://` and is reachable from the internet, and the credential. The error under **Connection failed** gives the reason. | | The **Tools** section is empty | Click **Test connection**. If the list stays empty, the server exposes no tools to the credential you used. | | The agent never calls a tool | That the server is enabled in the agent's **Connectors** tab, that the tool shows the **Read-only** tag, and that the agent's **Context** explains when to call it. | ## Related * [Customer monitoring agent](https://docs.hyperline.co/docs/customer-intelligence/customer-monitoring-agent.md) * [Integrations overview](https://docs.hyperline.co/integrations/overview.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.