MCP server

The Model Context Protocol (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 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.

MCP servers are part of Customer intelligence, a paid add-on. Contact the Hyperline team through the in-app chat to enable it.

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.

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.

Connect an MCP server

Go to Settings > Integrations and open the Data tab

Click Connect on MCP server

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.

Click Connect

The server appears in your active integrations.

Connect an MCP server dialog with a name, a server URL, and a bearer token

You can connect several MCP servers, for example one per internal system.

Hyperline sends a bearer token in the Authorization header (Bearer <token>) 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

Enable the server for an agent

A connected MCP server is not used until you enable it on an agent.

Go to Customers > Monitoring and open the agent.
Go to the Connectors tab.
Turn on the toggle next to the MCP server.
Click Save changes.

Connectors tab of a monitoring agent with the Product usage MCP server turned on

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:

Go to Customers > Monitoring and open the agent.
Go to the Context tab.
Fill in General context and Scoring instructions, as described below.
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.

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:

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

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.

Keep both fields short and specific to your data. The agent reads them for every customer it analyzes.

Check the result

Open the agent and click Actions > Trigger analysis.
Select one or two customers whose data you know, and start the run.
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.

Integrations

Payment gateway

CRM

Support platform

Email

Call recording

Accounting software

Tax engine

Data platform

Automation

Prerequisites

Connect an MCP server

Check the connection and its tools

Enable the server for an agent

How the agent uses MCP tools

Read-only tools

Configure the agent’s context

Example 💡

Check the result

Troubleshooting

​Prerequisites

​Connect an MCP server

​Check the connection and its tools

​Enable the server for an agent

​How the agent uses MCP tools

​Read-only tools

​Configure the agent’s context

Example 💡

​Check the result

​Troubleshooting

​Related

Prerequisites

Connect an MCP server

Check the connection and its tools

Enable the server for an agent

How the agent uses MCP tools

Read-only tools

Configure the agent’s context

Check the result

Troubleshooting

Related