Connect an MCP client
Summary
Section titled “Summary”KonversAI publishes an MCP server for each workspace. You connect an MCP client — Claude Code, the Claude desktop or web app, or any other client that speaks MCP — and then run the same administrative tools the KonversAI console gives you: read conversations, search documents, write a knowledge document, book, move or cancel a booking, change the AI preferences.
You start on the API access screen in the KonversAI console. That screen carries the Connect your assistant card, with the address of your workspace and the steps for each common client, and it manages the credentials your clients use.
An MCP client acts as you. The client can do only what your role and your permissions already allow in the KonversAI console, and KonversAI records every call.
Who can do this
Section titled “Who can do this”You need the Tenant Admin or the Tenant Operator role in the workspace. Both roles see API access under Settings in the left sidebar of the KonversAI console, and both manage their own credentials there. Each tool you call needs the same permission the console screen needs. A Tenant Operator without View conversations cannot read a conversation through an MCP client either.
Before you start
Section titled “Before you start”API access is a workspace feature. When API access is missing from Settings in the left sidebar of the KonversAI console, the feature is off for your workspace. Ask your KonversAI contact to switch it on.
Install an MCP client. Claude Code is a command-line client, and the instructions below use it. The Claude desktop and web apps connect the same server as a custom connector.
Have your workspace name ready. The address on the Connect your assistant card ends with the short name of your workspace, so the client reaches one workspace and no other. A person who works in three KonversAI workspaces connects three servers.
-
Select Settings in the left sidebar of the KonversAI console, then select API access.
-
Go to the Connect your assistant card and select the copy button next to Your workspace address. The address looks like
https://app.prod.konversai.no/mcp/your-workspace/. -
Add the server to your MCP client. Select your client on the Connect your assistant card: Claude, ChatGPT, Claude Code, VS Code or Other client. The card shows the steps for that client, with your own address already in each command. For Claude Code, select the copy button next to the command and run the command in a terminal:
Terminal window claude mcp add --transport http konversai https://app.prod.konversai.no/mcp/your-workspace/In the Claude desktop or web app, open the connector settings, choose to add a custom connector, and paste the server address instead.
-
Sign in. Run
/mcpin Claude Code and choose to authenticate. The client opens a browser on the KonversAI Connect screen, which names the client asking for access. -
Choose your workspace under Workspace on the Connect screen, then select Connect. KonversAI sends the browser back to your client. There is no token to copy.
-
Ask your client to list the tools it now has. Claude Code shows the server as connected under
/mcp. -
Go back to Settings → API access in the KonversAI console. Your client is listed under Connected apps, with the date it connected.
Use a token when the client cannot open a browser
Section titled “Use a token when the client cannot open a browser”A script, a scheduled job or a client with no browser signs in with a personal access token instead.
- Select Settings in the left sidebar of the KonversAI console, then select API access.
- Type a name in the box under Tokens for clients that cannot sign in. Name
the machine, not yourself — for example
Claude Code on my laptop. - Select Create token. KonversAI shows the token once, under Your new token, and never again. Select Copy and store the token in a password manager.
- Give the token to your client as a bearer token on every request to the server address on the Connect your assistant card.
A token starts with kvai_. You can hold ten active tokens per workspace. A
token carries your identity and your permissions, so treat a token exactly like
your password.
What the client can do
Section titled “What the client can do”The client sees only the tools your role and your permissions allow. Each tool description starts with who the tool is for:
- Operations tools handle customers: conversations, notes, cases, drafts waiting for review, bookings and event sign-ups.
- Workspace admin tools set the workspace up and improve the assistant: knowledge documents, the AI preferences and the business profile, tool sets, chat widgets, and the record of why the assistant answered as it did.
- Help searches this help documentation.
Reads answer at once: the workspace overview, the knowledge gaps, documents, bookings, calendars and their free times, conversations with the reply that waits for review, the drafts waiting for review, cases, workspace members, entry-points, tool sets and the AI preferences. The knowledge reads also cover the quality-check findings on documents and the web pages that website imports skip (excluded URLs).
A client can go through the whole knowledge base. The document list comes in pages of up to 50, and the client asks for the next page until there is none. A document read returns the first 8,000 characters and says when it cut the text, and the client can then ask for the whole document.
Some changes run at once, because each one is a single click in the KonversAI console and tells no customer anything: closing or reopening a conversation, handing a conversation over to a human, adding a note to a conversation, changing a case’s status, assignee, queue, follow-up date or title, and dismissing a quality finding as a false positive.
Every other change waits for you, excluding a crawled page’s URL and running a document’s quality checks again among them. Changing the AI preferences waits, because the preferences shape every answer your assistant gives. A note that the assistant must take into account waits too, because the assistant follows that note in every later reply on the conversation. Running the checks again counts as 0.1 conversation per 1,000 characters of the document, rounded to the nearest whole conversation, so a document under 5,000 characters costs nothing. The client gets back a description of the change and a link, and nothing happens until you select Confirm on the Pending actions screen. See Approve a pending action.
Review a conversation from your client
Section titled “Review a conversation from your client”The server offers a ready-made prompt called review_conversation. It works
like the conversation doctor in the console: give it a conversation and say what
bothered you, and the client finds out why the assistant answered that way and
proposes the smallest change that fixes it. In Claude Code, type
/mcp__konversai__review_conversation.
Can an MCP client see more of my KonversAI workspace than I can?
Section titled “Can an MCP client see more of my KonversAI workspace than I can?”No. A client connected to your KonversAI workspace acts as you. KonversAI checks your role and your permissions on every single tool call, against your membership as it stands at that moment. A tool you may not use is not even offered to the client. When your administrator removes a permission, the client loses that tool immediately, with no reconnection.
What happens when a connected MCP client tries to change something?
Section titled “What happens when a connected MCP client tries to change something?”Most changes wait for a human. The client sends a proposal, KonversAI stores it, and the client gets back a description and a link into the console. Nothing changes until you select Confirm on the Pending actions screen under Settings in the KonversAI console. A proposal expires 24 hours after the client makes the proposal. Single-click changes that tell no customer anything run at once instead. See What the client can do.
Do I need a token for Claude Code or the Claude apps?
Section titled “Do I need a token for Claude Code or the Claude apps?”No. Those clients open a browser, so they sign in on the KonversAI Connect screen and keep their own credentials. The API access screen says Most clients sign in through the browser and need none of this. Create a token only for something that cannot open a browser, such as a script or a scheduled job.
How do I cut off a client that I no longer use?
Section titled “How do I cut off a client that I no longer use?”Select Settings in the left sidebar of the KonversAI console, then select API access. For a client that signed in through a browser, find the row under Connected apps and select Disconnect. For a token, find the row under Your tokens and select Revoke. Both take effect immediately: the client stops working on its next call and must sign in again.
Why is API access missing from Settings in my KonversAI console?
Section titled “Why is API access missing from Settings in my KonversAI console?”API access is a per-workspace feature, and the item appears in the left sidebar of the KonversAI console only when the feature is on. The Connect screen tells a client the same thing in different words: None of your workspaces has API access switched on. Ask an administrator to enable it, then try again. Ask your KonversAI contact to switch the feature on for your workspace.
Does one connection reach all of my KonversAI workspaces?
Section titled “Does one connection reach all of my KonversAI workspaces?”No. The address on the Connect your assistant card names one workspace, and a credential reaches that workspace only. Add one server per workspace in your MCP client, and sign in to each. A leaked token reaches one workspace, not your whole account.
Is a call from an MCP client recorded?
Section titled “Is a call from an MCP client recorded?”Yes. KonversAI writes every tool call from a connected client to the audit log, with your name, the tool, and whether the call succeeded, was refused or is waiting for confirmation. A refused call is recorded too.
Can I use an MCP client instead of the KonversAI console?
Section titled “Can I use an MCP client instead of the KonversAI console?”Yes, for the tools listed on this page. Reading a workspace, searching and writing knowledge documents, managing bookings, conversations and cases, and changing the AI preferences all work from a client. Sending a reply to a customer, sending a reviewed draft, billing, invitations and the widget appearance stay in the KonversAI console.
Is this the same as the MCP Server tool under AI tools?
Section titled “Is this the same as the MCP Server tool under AI tools?”No, and the two point in opposite directions. The MCP Server tool under Settings → AI tools lets your assistant call someone else’s MCP server while answering a customer. See Give the assistant a tool. The server on the API access screen is the other direction: your MCP client manages your KonversAI workspace.
Last reviewed . Tell us when a step no longer matches the product.