> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/mcp-server-integrations/mcp-server.md). # MCP Server ## Overview The Younium MCP server lets you work with your Younium data through an AI assistant — Claude, ChatGPT, or an AI-enabled developer tool. MCP (Model Context Protocol) is an open standard for connecting AI assistants to business systems. Once connected, you ask questions and give instructions in plain language, and the assistant uses Younium on your behalf: your own user account, your own permissions, your own data. The server is hosted by Younium, so there is nothing to install. You add it as a connector in your AI platform and sign in with your ordinary Younium account. When the assistant needs something from Younium it calls one of the server's tools, and the server carries that out as your user. There are no API keys to create or manage, and no Younium password ever reaches the AI platform. Questions are answered straight away — what the open receivables are and which invoices are overdue, how MRR developed per country over the last year, what cash flow looks like by cash month, which subscriptions an account has. Anything that changes data is different: the assistant either creates it at draft stage, where nothing is billed or sent, or — for the actions that commit money or move a live record — shows you exactly what will happen and waits for you to approve it. *** ## AI Platform You also need an AI platform that supports remote MCP servers with OAuth sign-in. What each requires differs, and on two of them an administrator sets the connector up once for the whole workspace before anyone else can connect. | Platform | What it requires | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Claude** | Web and desktop. Any plan can add the connector individually. On Team and Enterprise, only an organization Owner can add it centrally for members. | | **ChatGPT** | Write actions require a Business, Enterprise or Edu workspace, where an administrator creates and publishes the connector. On individual plans OpenAI limits it to reading. | | **Cursor** | Added directly by the user. Younium recognises Cursor as a pre-registered application. | | **Other MCP clients** | Any client implementing the streamable HTTP transport with OAuth 2.1 connects without Younium-specific configuration. | > **Note on central installation:** An administrator adding the connector makes it *available* to members. It grants nobody access to anything — each member still signs in with their own Younium account and gets their own permissions. On a Business workspace in ChatGPT, a published connector cannot be edited afterwards; changing how it is configured means publishing it again. *** ## Which server to connect to There is one server per Younium environment, and the address you use is the one that matches the environment your Younium account is in. A connection reaches only its own environment's data, so a sandbox connection can never touch production records. | Environment | Server address | | ------------------------- | --------------------------------- | | Production, Europe | `https://mcp.younium.com` | | Production, United States | `https://mcp.us.younium.com` | | Sandbox | `https://mcp.sandbox.younium.com` | Each server reaches the Younium platform in its own region, and the analytics and quote services it can use are the ones deployed there. That has one consequence worth knowing before you connect: **the United States region has no CPQ service**, so the quote tools are unavailable on `https://mcp.us.younium.com` whether or not your organization has the CPQ add-on. The assistant reports quotes as unavailable, and the Younium Core quote tools are unaffected. *** ## Connecting the integration You connect as yourself, in one Younium organization. Before you start you need a Younium user account, the connector enabled for your organization, and — unless your plan lets you add connectors yourself — an administrator who has already added it. Adding the connector means giving your AI platform the server address for your environment. Nothing accompanies it: no client identifier, no secret, no request headers. The platform reads what it needs from the address itself. Pressing **Connect** then takes you through two Younium screens. The first is a consent page naming the application that is asking to connect. The second is the ordinary Younium sign-in, including SSO and multi-factor authentication where your organization uses them; if you are already signed in to Younium in that browser it passes instantly. You are then returned to the AI platform, which holds a time-limited token for your Younium session. You know it worked when the assistant can tell you which organization, user and legal entity it is connected to. It is instructed to report that at the start of a session, and asking it directly — *"what Younium organization am I connected to?"* — is the quickest check. From then on the connection renews itself while you use it. After a long period without use you are asked to sign in again, and a Younium security update can require a fresh sign-in sooner. Reconnecting takes a few seconds and loses nothing. If tool calls suddenly start failing with authorization errors, an expired connection is the usual reason. Disconnecting means removing the connector in your AI platform. Nothing about the connection is held on the Younium side, and the token the platform had stops working when it expires. ### The consent page The consent page is the one moment in the connection where you can catch an application that is not what it claims to be, so it is worth reading rather than clicking through. | What it shows | What it means | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **App name** | The name the application gives for itself — Claude, ChatGPT, Cursor. | | **After sign-in you will be sent back to** | The web address that receives the connection, or "this computer" for a desktop tool. This is the part an attacker cannot fake. | | **Published by** | How much Younium knows about the application: *known to Younium*, meaning it is pre-registered; or the website address its details were fetched from; or *unknown — this app registered itself and has not been reviewed*. | | **What the app will be able to do** | Reading the Younium data you have access to, and preparing changes that are shown to you for approval first — always with your own permissions, in your current legal entity. | Click **Allow** only if you started this connection yourself, from the application named on the page, and you recognise the return address. If you reached the page by following a link somebody sent you, click **Cancel**. Nothing has been connected. > **Note on unreviewed applications:** Any MCP-capable application can register itself, so the *unknown* state is normal for clients other than the pre-registered ones and is not by itself a sign of anything wrong. What it does mean is that the only assurance you have is that you started the connection — which matters more there than anywhere else. *** ## Organization and legal entity A connection belongs to one Younium organization: the one that was active when you signed in during the connection. If you have access to several and end up in the wrong one, there is no way to switch inside the session. Disconnect the connector, connect again, and choose the right organization while signing in. The same applies when you want to work in a different organization. Legal entities work the other way. Almost all Younium data — accounts, subscriptions, invoices, usage, quotes — belongs to a legal entity, and the connector always works in your **current** one, the same legal entity your Younium web session uses. You can ask the assistant which entities you have access to and ask it to switch, as often as you like. > **Note on switching:** The current legal entity is a single user setting, so switching it in a chat also moves your open Younium web session. An assistant should say when it changes entity. Insights is the exception. Its analytics tools are organization-wide and are not filtered by your current legal entity, so analysing a single entity there means asking the assistant to filter on it. *** ## Permissions Every call runs as your Younium user, under the role permissions you hold for the legal entity you are working in — the ones an administrator manages under **Users & Roles**. The connector cannot do anything you could not do yourself in the Younium web app. That is enforced by what the assistant is offered, not only by what it is allowed to finish. A tool your role does not permit is never presented to the assistant, so it cannot attempt it. Where an action needs a permission you lack — deleting usage, for instance — the assistant is told which permission is missing, so it can tell you what to ask your administrator for instead of simply failing. Two other things narrow what is on offer. An organization enabled at the read-only level gets the query tools and the legal-entity switch and nothing more. And a small number of the highest-impact tools can be switched off centrally. When an action is refused, the refusal distinguishes the two causes: your own permissions, or your organization's level. Asking the assistant which Younium tools are unavailable to you, and why, is the direct way to see where you stand. One consequence is worth knowing: if an administrator changes your role, or you switch legal entity, the list of tools the assistant can see refreshes on the next conversation rather than mid-chat. The permission check itself applies immediately, so nothing you should not be able to do becomes possible in the meantime. *** ## What the connector can do **Read** tools answer questions and run immediately. **Write** tools change Younium directly, at draft stage. **Write ✋** tools are the committing actions, which always preview and wait for your approval — see **Approving high-stakes actions** below. ### Session and search | Tool | Type | What it does | | -------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_session_context` | Read | Reports who you are connected as: user, organization, current and available legal entities, whether CPQ is enabled, and which tools your permissions allow | | `set_current_legal_entity` | Write | Switches your current legal entity, for later calls and for your Younium web session | | `search_younium` | Read | Quick search across domains: accounts by name, and subscriptions, invoices and quotes by number, limited to the categories you may view | ### Accounts, products and subscriptions These tools read and write the records described in [Accounts](/platform/accounts-contacts.md), [Products & Pricing](/platform/products-pricing.md) and [Subscriptions](/platform/subscriptions.md). | Tool | Type | What it does | | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `list_accounts` | Read | Finds customer accounts, with filtering and paging | | `get_account` | Read | Reads one account in full | | `update_account` | Write | Updates fields on an account, such as adding a missing invoice address | | `create_account` | Write | Creates a customer account — master data only, nothing is billed | | `list_products` | Read | Reads the catalogue: products, charge plans, charges and prices | | `create_product` | Write | Creates a catalogue product with its charge plans and price tiers | | `list_subscriptions` | Read | Finds subscriptions, filtered by status, account or date | | `get_subscription` | Read | Reads one subscription in summary or in full, with its charges and prices and optionally its version history | | `create_subscription` | Write | Creates a subscription in draft — nothing is billed until it is activated | | `activate_subscription` | Write ✋ | Activates a draft subscription and starts live billing | | `modify_subscription` | Write ✋ | Changes an active subscription — prices, quantities, added or removed charges, renewal, reversion — effective from a date you choose | ### Quotes Quote tools require [CPQ](/sales-and-product-led-growth/cpq.md), and the assistant detects whether your organization has it. They are also unavailable throughout the United States region, which runs no CPQ service. | Tool | Type | What it does | | ------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_quotes` | Read | Finds quotes by status, sales stage, owner or free text | | `get_quote` | Read | Reads one quote in full, with its totals, e-signing status and the lifecycle actions currently possible | | `list_cpq_products` | Read | The price book quotes are built from | | `create_quote` | Write | Creates a draft quote, for new business or as a change to an existing subscription | | `update_quote` | Write | Updates quote header fields such as name, validity and recipient | | `edit_quote_lines` | Write | Adds, changes or removes products, charges and discounts on a draft quote | | `advance_quote` | Write ✋ | Moves the quote through its lifecycle — submit, approve, send to the customer, accept, decline, mark lost, reopen, revise. Sending emails the customer, which is why it asks first | | `convert_quote_to_subscription` | Write ✋ | Converts an accepted quote into a subscription, activating it where the billing address is complete and creating a draft where it is not. The preview says which | ### Quotes in Younium Core Organizations using the quote functionality built into Younium Core rather than CPQ can read those quotes through the connector. Creating and editing them happens in the Younium web app. | Tool | Type | What it does | | -------------------- | ---- | ---------------------------------------------------- | | `list_legacy_quotes` | Read | Finds Younium Core quotes, with filtering and paging | | `get_legacy_quote` | Read | Reads one Younium Core quote in full | ### Billing, payments and receivables Invoicing follows the draft-then-post lifecycle described in [Billing](/platform/billing.md), and settlements behave as described in [Payments](/platform/payments.md). | Tool | Type | What it does | | -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `list_invoices` | Read | Finds invoices by status, account or date, with their amounts and unpaid remainder | | `get_invoice` | Read | Reads one invoice with its lines and a short-lived link to the PDF | | `get_ar_status` | Read | Receivables snapshot: open and overdue invoices in ageing buckets, totalled per currency | | `list_payments` | Read | Reads registered payments and the invoices they settled | | `get_payment_options` | Read | The payment methods and accounts available when registering a payment | | `list_exchange_rates` | Read | The rates configured for the current legal entity, per currency and validity period against the base currency, so figures can be converted, restated at a historical rate, or compared with the rate actually booked | | `create_invoice` | Write | Creates a draft invoice from a subscription, or as a free-form on-account invoice. Nothing is sent | | `generate_invoice_batch` | Write | Generates a batch of draft invoices up to a target date, for the accounts and invoice batch groups you name. Both scopes must be stated explicitly — named ones, or all — and naming both limits the batch to the listed accounts' charges in the listed groups. An optional minimum invoice amount is in the legal entity's base currency | | `get_invoice_batch_status` | Read | The progress of a running batch | | `post_invoice` | Write ✋ | Posts a draft invoice — numbering it, booking it, and making it final | | `register_payment` | Write ✋ | Registers a payment against an invoice, or as a draft payment | ### Usage and measurements | Tool | Type | What it does | | -------------------- | ------- | ------------------------------------------------------ | | `list_usage` | Read | Reads reported usage for usage-based charges | | `list_measurements` | Read | Reads reported measurement records | | `report_usage` | Write | Reports usage quantities against a subscription charge | | `report_measurement` | Write | Reports measurement values | | `correct_usage` | Write ✋ | Corrects or removes a usage record reported wrongly | ### Insights | Tool | Type | What it does | | ------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------- | | `get_insights_context` | Read | What analytics data exists, how fresh it is, and which measures and dimensions are available | | `list_insights_columns` | Read | Every dimension and measure on a dataset, custom fields included, so you can see what you are able to slice by | | `query_kpi` | Read | Aggregated figures — MRR, ARR, churn, TCV — grouped by any dimension, such as month, country, product or owner | | `analyze_revenue_changes` | Read | Revenue movement broken down as new business, expansion, contraction and churn | | `query_recurring_revenue` | Read | The same figures at account, subscription and charge level | | `query_cash_flow` | Read | Cash-flow figures — forecast, invoiced, settled and expected inflow — by cash month or invoice month, in group or base currency | | `query_insights_dataset` | Read | Free-form queries against any dataset, for drill-downs the aggregate tools cannot express | | `refresh_insights_data` | Write | Runs the same refresh as the Update button in Insights and waits for it to finish. Not available to read-only organizations | Insights answers reflect the last scheduled refresh rather than the current second, on the terms described in [Insights](/platform/reporting-analytics.md), where the metric definitions also live. An assistant can report how fresh the figures are and refresh them before answering, which takes several minutes. The cash-flow figures are the expected view — invoiced, settled and expected inflow — not a bank statement. *** ## Approving high-stakes actions Posting an invoice, activating or modifying a subscription, sending a quote, registering a payment: these commit money or move a live record, and none of them runs on a single instruction. Each is split in two. The assistant first calls the tool without approval and gets back a preview in plain language — the amounts, the account, the dates, how many invoices are in the batch — together with a confirmation token. It shows you that preview, and only once you have approved does it call again with the token. The token is signed, tied to your user and to that one action, and valid for fifteen minutes. An assistant cannot skip it or forge one. It also pins two things at the moment you approve. The first is the legal entity: if it changes between the preview and the confirmation, nothing executes. The second is the state of the record you were shown — its status, its amounts, the transitions it allowed. Younium re-reads the record before acting and compares. If a colleague posted the invoice or moved the quote on in between, nothing executes, the token is spent, and you get a fresh preview to approve instead. The same happens if the record cannot be re-read at all: nothing runs. The preview is exactly what will be executed, which is what makes it worth reading rather than approving on trust. An assistant can misunderstand an instruction, and the preview is where that becomes visible. After a bulk posting, it is worth looking at the result in the Younium web app as well. > **Advisory only:** Draft-stage writes — creating an account, a product, a draft subscription, a draft invoice or a batch of drafts, reporting usage, building a quote — run without the two-phase approval, because nothing is financially committed until a posting or activation step that does. Draft-stage does not always mean reversible: a draft invoice can be cancelled, but a quote cannot be deleted through the assistant, only closed as lost or declined; a created product stays in the catalogue; and reported usage is corrected rather than removed. An assistant should check these with you before creating them. *** ## Privacy and data handling Every call carries your own identity, so the connector reaches only the data your Younium user can reach, in the legal entity you are currently in. The server holds no credentials: your Younium password never passes through it, and Younium stores nothing belonging to your AI platform. What the tools return does pass through that AI platform, in the same way as anything else in the conversation. The judgment to apply is the one you would apply to pasting business data into an AI chat, and the platform's own data-handling terms govern what happens to it there. *** ## Good to know | | | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Analytics are as fresh as the last refresh** | Insights answers reflect the last refresh, not the current second. The assistant can report the freshness and refresh on request. | | **Quotes in Younium Core are read-only** | Creating and editing them happens in the web app, and full quote workflows need CPQ. If a quote cannot be found, it is worth looking in both places. | | **One organization per connection** | Switching organization means reconnecting. Legal entities switch freely within a session. | | **Large result sets are paged** | An assistant narrows a query rather than returning thousands of rows. | | **Invoice batches are never scoped by default** | The assistant must state which accounts and which invoice batch groups a batch covers, or that it covers all of them. A request that leaves either out is refused rather than invoicing the whole legal entity. A batch runs as soon as it is requested, so an assistant should confirm an all-accounts batch with you first. | | **A new batch may report an unknown status** | Immediately after a batch is scheduled its status can read as unknown. It resolves within seconds. | | **Sessions expire** | After a long period without use, or after a Younium security update, you sign in again. Nothing is lost. | | **An assistant can be wrong** | The preview before an approval is what will be executed. Read it. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.younium.com/mcp-server-integrations/mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.