Connect an AI assistant to Kompass (MCP)

Kompass has a built-in MCP server, so AI assistants such as Claude can work with your Kompass data as native tools: look up clients and projects, summarise a client's position, list overdue tasks, log time, and create or update records, all as you, with your permissions. MCP (Model Context Protocol) is the open standard these assistants use to connect to external systems.

The server address is your Kompass instance followed by /mcp , with no trailing slash:

https://your-instance.kompassbms.com/mcp

How access works

Every request the assistant makes runs as a Kompass user and is subject to that user's permissions, organisation scoping and audit trail, exactly as if the same person had used the Kompass web app. There are two ways to sign in:

Sign in through Kompass (recommended). Clients that support it (claude.ai, Claude Code) take the address alone. The first time you connect, Kompass asks you to sign in and approve the connection. Each person connects as themselves.
Personal access token. Clients that can send a fixed header use a token instead. Mint one from your Kompass profile under Personal Access Tokens; see Personal access tokens (PATs). The token grants the same access as your account, so treat it like a password.

A caution on shared settings. Some clients let an administrator enter a header once for a whole organisation. A token entered that way is shared by everyone in that organisation, and every request they make runs as the person who minted it. Prefer signing in through Kompass wherever the client offers it.

Who can use it

The MCP server is switched off until a Kompass administrator turns it on, and it is off for everyone by default. Administrators control it in two places in Kompass Admin:

MCP configuration, one entry per organisation, with a mode of Off, Read only or Read and write. Read only lets assistants look things up and summarise; Read and write also lets them create and update records. Users who belong to more than one organisation get the widest mode among theirs.
Group permissions: each user additionally needs Can read Kompass data through the MCP server, and Can change Kompass data through the MCP server for changes. Neither is granted to anyone until an administrator adds it to a group, so a common first step is a small pilot group with read access only.

Whatever the mode, an assistant can never do more than the connected user could do in Kompass themselves. When access is read only, the sign-in page says so and the assistant is not offered any tool that changes data. If access is off, or the user lacks the permission, the connection is refused with a message saying who can change that. Kompass support can also withdraw the MCP server for a whole account on request.

claude.ai

Open Settings, then Connectors.
Choose Add custom connector.
Enter a name (for example Kompass) and the address https://your-instance.kompassbms.com/mcp . Leave the advanced settings empty.
Choose Add, then Connect. You are taken to Kompass to sign in and approve the connection.
In a new chat, enable the Kompass connector from the tools menu.

Claude Code

Add the server, then authenticate when prompted (or run /mcp inside Claude Code to sign in):

claude mcp add --transport http kompass https://your-instance.kompassbms.com/mcp

Claude Code signs in through Kompass and stores its own credentials; no token is needed.

ChatGPT

ChatGPT connects the same way, by address alone, and each person signs in to Kompass as themselves. You need ChatGPT on the web with a Plus, Pro, Business, Enterprise or Education plan. In a Business or Enterprise workspace, your workspace administrator may need to allow custom apps first.

Open Plugins from the sidebar, choose Add, then Create MCP App. If that option is missing, turn on Developer mode under Settings, Security and login, if your account offers it (see Troubleshooting).
Enter a name (for example Kompass) and the address https://your-instance.kompassbms.com/mcp , and choose OAuth as the authentication method. Leave the advanced OAuth settings as they are: ChatGPT reads them from Kompass.
Tick I understand and want to continue, then choose Create.
Choose Continue, sign in to Kompass and choose Authorise. The app then appears under Plugins, Personal.
In a chat, type @ , choose the Kompass app, and ask your question, for example "who am I in Kompass?".

ChatGPT asks you to confirm before it runs a tool that changes data. The Kompass permissions and modes described above apply exactly as for Claude.

ChatGPT's deep research and company knowledge features use two extra tools, search and fetch , which Kompass provides; ordinary chat uses the full tool list.

Claude Desktop and other local clients

Claude Desktop connects to local programs rather than web addresses. Install and sign in to the Kompass CLI, then add it to claude_desktop_config.json :

{
  "mcpServers": {
    "kompass": { "command": "kompass", "args": ["mcp"] }
  }
}

The CLI uses the token and instance address you configured with kompass auth login .

Other clients: VS Code, Cursor, Windsurf and similar

Many coding tools connect to an MCP server by address and can send a fixed header. Their built-in sign-in expects the server to register clients on the fly, which Kompass does not do, so use a personal access token as a bearer token instead. Read the caution above before entering this in a shared or organisation-wide setting.

{
  "mcpServers": {
    "kompass": {
      "url": "https://your-instance.kompassbms.com/mcp",
      "headers": { "Authorization": "Bearer <your token>" }
    }
  }
}

If the client offers only a small number of tools or your assistant struggles with long tool lists, add ?minimal=1 to the address to receive the basic list, get, create and update tools only.

What the assistant can do

Tools	What they do
`kompass_whoami`	Confirms the connection and which user the assistant is acting as.
`kompass_search`	Finds projects, quotes, clients, contacts and staff by name or reference.
`kompass_clients_list`, `kompass_clients_get`	Lists clients with the same filters the web app offers, and fetches one client in full.
`kompass_projects_list`, `kompass_projects_get`	Lists accepted projects, filtered by phase, client, manager and more. Fetches one project or quote in full, with every lifecycle date.
`kompass_quotes_list`	Lists quotes and projects whether or not they have been accepted, with the same filters as projects. Ask for quotes awaiting a decision to see only open quotes. To see one quote in full, the assistant uses `kompass_projects_get`.
`kompass_quote_items_list`, `kompass_quote_items_get`	Lists the quote items on projects and quotes, and fetches one in full. Quote items can be read but not created or changed.
`kompass_tasks_list`, `kompass_tasks_get`	Lists tasks, open ones by default, and fetches one task in full.
`kompass_diary_list`, `kompass_diary_get`	Lists diary (time) entries, and fetches one entry in full.
`kompass_users_list`, `kompass_users_get`	Lists staff, and fetches one person's details.
`search`, `fetch`	Search and fetch by reference, used by ChatGPT deep research and by assistants that prefer these two general tools.
`kompass_client_summary`, `kompass_project_summary`	One-call overviews: recent projects, open tasks, recent diary entries, and financial figures for users allowed to see them.
`kompass_tasks_overdue`, `kompass_diary_recent`	Open tasks past their end date, and recent time entries, optionally for one client, project or person.
`kompass_clients_create`, `kompass_projects_create`, `kompass_tasks_create`, `kompass_diary_create` and their `_update` counterparts	Create records and change fields on existing ones.
`kompass_tasks_complete`	Marks a task complete by setting its closed date.

Changes need confirmation. Every tool that changes data must be called with an explicit confirmation, and each one can be run as a preview that shows exactly what would be sent without sending it. In practice this means the assistant describes the change and asks you before it goes ahead. Anything your account is not allowed to do in Kompass is refused in the same way here, and validation messages come back word for word so the assistant can correct itself.

Troubleshooting

The connector asks me to sign in again. Sign-in sessions expire and are renewed automatically; if renewal fails, disconnect and reconnect the connector. For token-based clients, check that the token has not been revoked in your profile.
ChatGPT has no Create MCP App option under Plugins, Add. OpenAI is still making this feature available to ChatGPT accounts, and some Plus and Pro accounts do not have it yet. Nothing in Kompass controls this: contact OpenAI support, or connect from a ChatGPT account that has the option. In a Business or Enterprise workspace, also check with your workspace administrator.
Kompass tools do not appear. Check the address ends in /mcp with no trailing slash and no /api , and that the connector is enabled for the current chat.
The connection says access is switched off, or that a permission is missing. Ask a Kompass administrator to set your organisation's MCP configuration and grant your group the MCP permissions (see Who can use it).
The assistant says it cannot make changes. Your organisation is set to read only, or your group lacks the change permission. Either is an administrator's decision.
A change was refused. The assistant may have skipped the confirmation step: ask it to confirm and try again. If the refusal names a field, the value did not pass Kompass validation.
The first call is slow. The server switches off when idle and restarts on the first request, which can add a moment. Later calls are quick.