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

# Hyperline MCP

> Connect AI assistants like Claude and Cursor to your Hyperline account through the Model Context Protocol for billing data lookups and actions.

Connect your AI tools to Hyperline using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction). MCP is an open standard that lets AI assistants interact with your billing data, manage customers, and automate revenue operations.

## What is Hyperline MCP?

Hyperline MCP is a hosted MCP server that gives AI tools secure access to your Hyperline account. It's designed to work seamlessly with popular AI assistants like Claude, ChatGPT, Cursor, and more.

### Why use Hyperline MCP?

* **Natural language billing management**: Manage customers, subscriptions, and invoices through conversational AI instead of navigating through multiple screens
* **Full account access**: AI tools can search, read, create, and update records across your Hyperline account, including customers, subscriptions, invoices, products, and usage data
* **Easy setup**: Connect through OAuth with one-click installation for supported AI tools, or use an API key for direct authentication
* **Optimized for AI**: Built specifically for AI agents with efficient data formatting and human-readable responses
* **Secure by design**: Authenticates with your Hyperline credentials, with read operations auto-approved while write operations request confirmation

### What can you do with Hyperline MCP?

* **Customer management**: Look up customer details, find contacts by email or name, and create new customer records
* **Subscription operations**: View active subscriptions, check renewal dates, and manage subscription lifecycle
* **Invoice handling**: Search invoices by status, view payment history, and track overdue payments
* **Usage tracking**: Query usage data, check consumption metrics, and explore billing periods
* **Revenue analytics**: Access MRR, ARR, and other key metrics through natural language queries
* **Product catalog**: Browse products and pricing, understand your catalog structure

## Getting started

### Prerequisites

Before connecting Hyperline MCP, ensure you have:

1. An active Hyperline account
2. An MCP-compatible AI client (Claude, ChatGPT, Cursor, VS Code, etc.)

### Authentication

The Hyperline MCP server uses OAuth 2.0 for authentication. Most AI clients handle the OAuth flow automatically. The client redirects you to log in with your Hyperline credentials.

If your client doesn't support OAuth (for example, in a server or machine-to-machine context), you can authenticate using an API key instead. You can generate API keys from your workspace [Settings](https://app.hyperline.co/app/settings/api).

Some AI clients support OAuth but do not support dynamic client registration. In that case, the client may ask for an OAuth **Client ID** in addition to the MCP server URL.

If your client has a **Client ID** or **OAuth client ID** field:

1. Enter the MCP server URL: `https://mcp.hyperline.co/mcp`
2. Use dynamic client registration if the client offers it
3. If dynamic registration is not available, contact the Hyperline team via the in-app chat to get the static OAuth Client ID for your environment

<Note>
  Avoid using a shared API key when you need per-user Hyperline permissions. OAuth keeps access tied to the Hyperline user who authorizes the AI client, so existing roles and permissions still apply.
</Note>

### Connecting to Hyperline MCP

Add the following server URL to your AI client:

```
https://mcp.hyperline.co/mcp
```

<Info>
  For sandbox environments, use `https://sandbox.mcp.hyperline.co/mcp` instead.
</Info>

<Tabs>
  <Tab title="Claude">
    **For Claude Desktop or Claude.ai:**

    1. Open **Settings** → **Connectors**
    2. Click **Add custom connector**
    3. Enter a name (e.g., `hyperline`) and the URL: `https://mcp.hyperline.co/mcp`
    4. Follow the OAuth prompts to log in to your Hyperline account
  </Tab>

  <Tab title="Claude Code">
    Run the following command to add the Hyperline MCP server:

    ```bash theme={null}
    claude mcp add --transport http hyperline https://mcp.hyperline.co/mcp
    ```
  </Tab>

  <Tab title="ChatGPT">
    1. Go to **Settings** → **Apps** → **Advanced settings** → Enable **Developer mode**
    2. Click **Create App**
    3. Fill in the Name (e.g., `Hyperline`) and MCP Server URL
    4. Add the MCP Server URL: `https://mcp.hyperline.co/mcp`
    5. Complete the OAuth flow to authenticate with Hyperline
  </Tab>

  <Tab title="Cursor">
    1. Use <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows) to open the command palette
    2. Search for "Open MCP settings"
    3. Click **Add custom MCP** to open the `mcp.json` file
    4. Configure the server:

    ```json theme={null}
    {
      "mcpServers": {
        "hyperline": {
          "url": "https://mcp.hyperline.co/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    1. Create a `.vscode/mcp.json` file in your project
    2. Configure the server:

    ```json theme={null}
    {
      "servers": {
        "hyperline": {
          "type": "http",
          "url": "https://mcp.hyperline.co/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other clients">
    Add `https://mcp.hyperline.co/mcp` as a remote MCP server and complete the OAuth authentication when prompted.

    If your client doesn't support OAuth, use your API key for direct authentication instead.
  </Tab>
</Tabs>

Once connected, your AI client is authenticated and can access your Hyperline account data.

<Accordion title="Server / machine-to-machine (M2M) setup">
  If your MCP client runs in a server environment without a browser (e.g., a backend agent or automated pipeline), you can skip OAuth and authenticate directly with an API key.

  Generate an API key from your workspace [Settings](https://app.hyperline.co/app/settings/api), then pass it in the `Authorization` header when connecting to the MCP server:

  ```
  Authorization: Bearer <YOUR_API_KEY>
  ```

  For example, in an MCP client configuration that supports custom headers:

  ```json theme={null}
  {
    "mcpServers": {
      "hyperline": {
        "url": "https://mcp.hyperline.co/mcp",
        "headers": {
          "Authorization": "Bearer <YOUR_API_KEY>"
        }
      }
    }
  }
  ```

  <Warning>
    Keep your API key secret. Do not commit it to version control. Use environment variables or a secrets manager instead.
  </Warning>
</Accordion>

## Multi-company access

If your Hyperline user has access to multiple companies, the MCP server defaults to the first (oldest) company linked to your account.

To target a specific company, include the `Hyperline-CompanyId` header in your MCP server configuration:

```json theme={null}
{
  "mcpServers": {
    "hyperline": {
      "url": "https://mcp.hyperline.co/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>",
        "Hyperline-CompanyId": "<YOUR_COMPANY_ID>"
      }
    }
  }
}
```

You can retrieve the list of companies your account has access to using the [`/v1/companies`](/api-reference/endpoints/companies/list-companies) endpoint.

## Supported tools

The Hyperline MCP server exposes over 100 tools covering the full breadth of your billing operations. These include listing and retrieving customers, quotes, subscriptions, invoices, and product information. They also cover actions like creating and voiding invoices, generating quotes, assigning subscriptions, querying usage data, and accessing revenue metrics.

Once connected, your AI assistant automatically discovers all available tools. Describe what you need in natural language, and the assistant uses the right tools to get it done.

## Sample prompts

### Customer and account lookup

| Prompt | What it does |
| - | - |
| "Find all customers with overdue invoices" | Searches for customers with unpaid invoices past due date |
| "What's the email for Acme Corp?" | Looks up contact information for a specific customer |
| "Show me everything we know about customer X" | Retrieves comprehensive customer information |
| "Find customers in the Enterprise plan" | Filters customers by subscription plan |
| "List customers created in the last 30 days" | Shows recently acquired customers |

### Subscriptions and billing

| Prompt | What it does |
| - | - |
| "What subscriptions does Acme Corp have?" | Lists all subscriptions for a customer |
| "Show me subscriptions renewing next week" | Finds upcoming renewals |
| "Which customers are on the Pro plan?" | Lists customers filtered by plan |
| "Create a subscription for customer X on the Starter plan" | Creates a new subscription |

### Invoices and payments

| Prompt | What it does |
| - | - |
| "List unpaid invoices from the last 30 days" | Searches for outstanding invoices |
| "What's the total amount billed this month?" | Calculates monthly billing total |
| "Show me the payment history for Acme Corp" | Retrieves customer payment records |
| "Find invoices over \$10,000" | Filters invoices by amount |

### Revenue analytics

| Prompt | What it does |
| - | - |
| "What's my current MRR?" | Returns Monthly Recurring Revenue |
| "Show me revenue trends for the last quarter" | Displays revenue metrics over time |
| "How many active subscriptions do we have?" | Counts active subscriptions |
| "What's our customer churn this month?" | Calculates churn metrics |

## Security best practices

<Warning>
  Treat your credentials and billing data as sensitive information. Only connect to AI applications you trust, and use sandbox credentials when experimenting.
</Warning>

### Tool safety

Hyperline MCP uses MCP safety annotations:

* **Read operations**: Auto-approved for seamless searching and viewing
* **Write operations**: Request your confirmation before creating or updating data

### User permissions

Hyperline MCP respects your existing user permissions. The tools available through the MCP server depend on the roles and permissions configured for your user account in your workspace [Settings](https://app.hyperline.co/app/settings/members). When you use an API key, they depend on its scopes. AI assistants can only access and modify what you are authorized to do in Hyperline.

You can revoke access at any time by deleting API keys or revoking user access.

### Rate limits

Standard API rate limits apply to all MCP operations. See [Rate limiting](/developers/rate-limiting) for details. In most cases, normal conversational use stays well within rate limits.

## Troubleshooting

If your AI assistant can't connect to Hyperline:

1. **Verify your credentials**: Make sure the credentials are correct and haven't been regenerated or revoked
2. **Check the environment**: Ensure you're using the correct URL for your environment (production vs sandbox)
3. **Test the connection**: Try a simple request like "List customers" to verify the connection works
4. **Check permissions**: Ensure your Hyperline user has the necessary permissions for the operations you're attempting

<Info>
  If you need additional support, contact the Hyperline team via the in-app chat.
</Info>


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