Skip to main content

Connect Claude (MCP)

The tools of the AI assistant can answer an external client — Claude Desktop, claude.ai, Claude Code — through the server's MCP endpoint, /mcp. The client acts as a Liberty Next user: it is offered what that user is offered in the chat drawer, each call goes through the same permission checks and the same data scope, and each call is recorded.

Three things are needed: the endpoint turned on, the mcp:use permission, and a personal access token the user creates in their profile.


At a glance​

ProfileProfileSecurityAccess tokensA personal access token lets an external client — Claude, through a custom connector —use the assistant's tools as you: with your permissions and your data scope, never more.CONNECTOR URLhttps://liberty.example.com/mcpVALID FOR (DAYS)90YOUR TOKEN — THE CONNECTOR'S REQUEST HEADER: AUTHORIZATION: BEARER <TOKEN>7Qd2mVx4…x9LkCopyCopy it now: it is shown once and not stored. It expires on 16/02/2027.A token also ends when your account is deactivated or loses the permission,and when you change your password — do that if a token leaks.Create a tokenAccess tokens tabwith the mcp:use permissionConnector URLto paste in ClaudeShown oncenever stored on the serverValidity90 days, capped by the serverThe request headerAuthorization: Bearer …One token per clickno list, no revoke button

Turn the endpoint on​

In Liberty Next → Administer → App → AI Assistant:

FieldDefaultDescription
MCP endpoint (/mcp)OffThe server answers on /mcp. Applied on save, without a restart.
Personal access token: longest life (days)366The longest validity a user may ask for.

The endpoint needs the mcp extra of the package (pip install "liberty-next[mcp]"); liberty-next[all] and the Docker image include it.


Grant the permission​

In Liberty Next → Administer → Access, give the role the rule AI assistant → AI tools from an external client (MCP) — create a personal access token (mcp:use), in Beyond the menus. The user then sees the Access tokens tab in their profile; a superuser always does.

mcp:use only opens the endpoint: what the client reaches still depends on the user's other permissions — see Who can use it, and on what.


Create a token​

The user opens their profile — their name in the top bar — then Access tokens:

  1. Valid for (days): 90 by default. A longer validity than the server allows is shortened to the server's maximum; the expiry date shown with the token is the one that applies.
  2. Create a token.
  3. Copy the token (Copy): it is shown once and not stored.

The tab also gives the Connector URL, the address of the server followed by /mcp.


Declare the connector in Claude​

In the client, add a custom connector with:

SettingValue
URLThe Connector URL of the tab — https://<server>/mcp.
Request headerAuthorization: Bearer <token>
AnswerMeaning
404The endpoint is off.
401No token, or a token that is invalid or ended.

What the client can do​

  • The client is offered the tools the user is offered in the chat drawer, with the same descriptions; a tool the user cannot use is not listed.
  • Every call checks the user's permissions and applies their data scope, as in the drawer.
  • The tools whose result is a card of the chat drawer are not offered: the scaffold proposals and the notes.
  • A tool that saves something — a Data Explorer analysis or dashboard — tells the client so, which lets it ask for a confirmation.
  • A personal access token opens the MCP endpoint only: the rest of the API refuses it.

When a token ends​

The account is read again at every call, so a token carries the user's rights of the moment, never more. It ends:

  • at its expiry date;
  • when the account is deactivated, or loses mcp:use;
  • when the account's password changes.

There is no list of tokens and no button to revoke one: changing the password ends every token of the account. That is what to do when a token has leaked.


What is recorded​

Each call is in the usage record, with the model mcp: the user, the tool, what it was called on, whether it failed, its size and its time — never a row it returned. See Monitoring → AI usage.


Tips​

  • Keep the validity short for a first trial, and create a new token rather than sharing one: a token is the user's own access.
  • Grant mcp:use to the roles that already use the assistant in the application; the answers depend on the same sql: and explorer: permissions.
  • Serve the endpoint over HTTPS only: the token travels in a request header.