Connect an MCP client

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, cancel a booking, change the AI preferences.

You start on the API access screen in the KonversAI console. That screen carries the Connect a client card, with the address of your workspace and the three steps, 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

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

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 a client 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.

Steps

1. Select Settings in the left sidebar of the KonversAI console, then select API access.

2. Go to the Connect a client card and select Copy address under 1. Copy the server address. The address looks like https://app.prod.konversai.no/mcp/your-workspace/.

3. Add the server to your MCP client. Under 2. Add the server to your client, the API access screen shows the command with your own address already in it. Select Copy command and run the command in a terminal:

   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.

4. Sign in. Run /mcp in Claude Code and choose to authenticate. The client opens a browser on the KonversAI Connect screen, which names the client asking for access.

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

6. Ask your client to list the tools it now has. Claude Code shows the server as connected under /mcp.

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

A script, a scheduled job or a client with no browser signs in with a personal access token instead.

1. Select Settings in the left sidebar of the KonversAI console, then select API access.
2. 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.
3. 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.
4. Give the token to your client as a bearer token on every request to the server address on the Connect a client 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

Reads answer at once: the workspace overview, the knowledge gaps, documents, bookings, conversations, workspace members, entry-points, tool sets and the AI preferences.

Three changes also run at once, because each one is a single click in the KonversAI console and tells no customer anything: closing a conversation, handing a conversation over to a human, and saving the AI preferences.

Every other change waits for you. 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.

FAQ

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?

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 ten minutes after the client makes the proposal. Three changes run at once instead: closing a conversation, handing a conversation over, and saving the AI preferences.

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?

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?

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?

No. The address on the Connect a client 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?

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?

Yes, for the tools listed on this page. Reading a workspace, searching and writing knowledge documents, managing bookings and conversations, and changing the AI preferences all work from a client. Screens with no tool behind them — billing, invitations, the widget appearance — stay in the KonversAI console.

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.