Witivio Documentation

# MCP Server (Preview)

# Overview

AI desk PRO exposes a Model Context Protocol (MCP) server for each agent. MCP is an open standard that allows AI applications, development tools, and orchestration platforms to interact with external tools in a standardized way.

When MCP is enabled on an agent, any MCP-compatible client (Claude Desktop, VS Code Copilot, custom orchestrators, etc.) can chat with the agent using its full knowledge base, documents, and configured data sources — just as a user would in Microsoft Teams or the webchat.

# Use cases

  • AI-assisted development — Connect your agent to Claude Desktop or VS Code so developers can query internal documentation, HR policies, or IT procedures without leaving their IDE.
  • Multi-agent orchestration — Use AI desk PRO agents as tools within a larger AI pipeline or agent framework.
  • Internal system integration — Let internal platforms call the agent programmatically to answer user questions.
  • Custom applications — Build your own chat interface or workflow that leverages the agent's knowledge.

# How it works

The MCP server uses the HTTP + SSE (Server-Sent Events) transport. MCP clients connect to a dedicated endpoint for the agent and authenticate with a Microsoft Entra ID token. Once connected, the client can invoke two tools:

  • chat — send questions and receive answers with citations.
  • get_reference — turn any citation returned by chat into something openable: a preview link for a local document, Microsoft Graph coordinates for a SharePoint document, or the full question/answer content for a QnA.

# Prerequisites

Before configuring MCP, ensure you have:

  • Administrator access to the agent in AI desk PRO
  • Access to the Microsoft Entra ID portal (to register or configure a client application)
  • An MCP-compatible client application

# Enable MCP on an agent

  1. Sign in to AI desk PRO
  2. Open the agent you want to expose via MCP
  3. Navigate to Configuration > Agent Customization
  4. Go to the Features tab
  5. Toggle MCP to On
  6. Save your changes

WARNING

MCP is a Preview feature. Review the Preview Terms before enabling it.

Once MCP is enabled, connection information appears on the agent's Information page:

Field Description
MCP Endpoint The base URL for the MCP server (e.g., https://api.aidesk-pro.com/mcp/{agent-id})
Application ID The Microsoft Entra ID application ID used for authentication
Audience URI The audience value to request in the OAuth token (e.g., api://api.aidesk-pro.com/botid-{application-id})

You will need these three values to configure both the Azure client application and the MCP client.

# Configure the Microsoft Entra ID client application

To authenticate with the MCP server, you need to register (or update) a client application in Microsoft Entra ID that has permission to request tokens for the agent's API.

# Step 1 — Register a client application (or use an existing one)

  1. Go to the Azure Portal (opens new window) > Microsoft Entra ID > App registrations
  2. Click New registration (or select an existing application)
  3. Enter a name (e.g., MCP Client - AI desk PRO)
  4. Set Supported account types to Accounts in this organizational directory only
  5. Click Register
  6. Note the Application (client) ID — you will need it for the MCP client configuration

# Step 2 — Create a client secret

  1. In your client application, go to Certificates & secrets
  2. Click New client secret
  3. Enter a description and expiration period
  4. Click Add
  5. Copy the Value immediately — it will not be shown again

TIP

For production scenarios, consider using a certificate or managed identity instead of a client secret.

# Step 3 — Add API permissions

You need to grant your client application permission to call the agent's API. The agent's API is exposed by the SSO application shown on the agent's Information page.

Delegated authentication only

The MCP Server only supports the delegated (on-behalf-of-user) flow. Application permissions (service-to-service / client credentials) are not supported: every call must be made on behalf of a signed-in user so that the agent can enforce per-user permissions on the underlying knowledge sources.

  1. In your client application, go to API permissions
  2. Click Add a permission > APIs my organization uses
  3. Search for the Application ID shown on the agent's Information page
  4. Select Delegated permissions — the MCP client acts on behalf of a signed-in user
  5. Select the available permission scope and click Add permissions

# Step 4 — Acquire a token

Your MCP client must obtain a JWT access token from Microsoft Entra ID before connecting, using the delegated (user) flow:

POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id={your-client-app-id}
&scope={audience-uri}/.default
&code={authorization-code}
&redirect_uri={your-redirect-uri}
&client_secret={your-client-secret}

Replace {audience-uri} with the Audience URI from the agent's Information page.

# Connect an MCP client

# Connection settings

All MCP clients need the following information:

Setting Value
Server URL The MCP Endpoint from the agent's Information page
Transport HTTP + SSE (Streamable HTTP)
Authentication Bearer token (Microsoft Entra ID JWT)

# Claude Desktop

Add the following to your Claude Desktop MCP configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "aidesk-pro": {
      "url": "https://api.aidesk-pro.com/mcp/{agent-id}/sse",
      "headers": {
        "Authorization": "Bearer {your-access-token}"
      }
    }
  }
}

TIP

Since access tokens expire, you may want to use a helper script or proxy that refreshes the token automatically.

# VS Code (GitHub Copilot)

In your VS Code settings.json, add an MCP server entry:

{
  "mcp": {
    "servers": {
      "aidesk-pro": {
        "type": "sse",
        "url": "https://api.aidesk-pro.com/mcp/{agent-id}/sse",
        "headers": {
          "Authorization": "Bearer {your-access-token}"
        }
      }
    }
  }
}

# Custom client (programmatic)

Any MCP SDK can connect to the server. Here is an example using the TypeScript MCP SDK:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const transport = new SSEClientTransport(
  new URL("https://api.aidesk-pro.com/mcp/{agent-id}/sse"),
  {
    requestInit: {
      headers: {
        Authorization: "Bearer {your-access-token}",
      },
    },
  }
);

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log(tools);

// Chat with the agent
const result = await client.callTool("chat", {
  message: "What is our company's remote work policy?",
});
console.log(result);

# Protocol reference (advanced)

This section describes the raw SSE + JSON-RPC flow for developers building a custom client without an MCP SDK. If you use an MCP SDK (TypeScript, Python, C#), these steps are handled automatically.

# 1 — Open the SSE connection

Connect to the SSE endpoint with the Bearer token:

GET /mcp/{agent-id}/sse HTTP/1.1
Host: api.aidesk-pro.com
Authorization: Bearer {access-token}
Accept: text/event-stream

The server responds with a stream. Wait for the endpoint event:

event: endpoint
data: /mcp/message?sessionId=abc123

This gives you the message URL to send JSON-RPC requests to. Prepend the base URL and insert the agent ID:

POST https://api.aidesk-pro.com/mcp/{agent-id}/message?sessionId=abc123

Keep the SSE connection open — all responses will arrive through it.

# 2 — Initialize the session

Send a JSON-RPC initialize request to the message endpoint:

{
  "jsonrpc": "2.0",
  "id": "init-1",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

The server responds (via SSE) with its capabilities and server info.

# 3 — List available tools

{
  "jsonrpc": "2.0",
  "id": "tools-1",
  "method": "tools/list",
  "params": {}
}

The response includes the chat and get_reference tools with their parameter schemas.

# 4 — Call the chat tool

{
  "jsonrpc": "2.0",
  "id": "chat-1",
  "method": "tools/call",
  "params": {
    "name": "chat",
    "arguments": {
      "message": "What is our remote work policy?",
      "chatId": null
    }
  }
}

The response arrives via the SSE stream with the JSON-RPC result containing the chat response (answer, citations, chatId, etc.).

# Available tools

The MCP server exposes two tools: chat and get_reference.

# chat

Chat with the AI desk PRO agent using its knowledge base, documents, and configured data sources.

Parameters:

Parameter Type Required Description
message string Yes The user's question or query
chatId string No A chat session ID to continue an existing conversation

Response (JSON):

Field Type Description
answer string The complete answer from the agent
chatId string The chat session ID (use this to continue the conversation)
chatMessageId string The unique ID of this response message
citations array Sources and documents used to generate the answer (see below)
error object Error details if the request failed (contains code and message)

Citation shape:

Each item in citations carries the metadata you need to display the source and, if wanted, retrieve it via get_reference:

Field Type Description
referenceId string Identifier to pass back to get_reference. Empty when the source has no resolvable backing entity
sourceType string The kind of source: Document or Qna. Pass it to get_reference alongside referenceId
sourceName string Human-readable name — filename or QnA question
snippet string The passage of text that supports the citation
mimeType string MIME type of the source file (empty for QnAs)
relevanceScore number Relevance of the citation against the query (higher is better)
fileVersion string File version when known (empty for QnAs / unversioned sources)
fileLastUpdate string Last-update timestamp of the source when known

# get_reference

Resolve a citation returned by chat into an openable preview URL (local documents), Microsoft Graph coordinates (SharePoint documents), or the full QnA content. The agent re-checks that the reference belongs to it and re-validates the signed-in user's permissions before returning anything.

Parameters:

Parameter Type Required Description
referenceId string Yes The referenceId from a citation returned by chat
sourceType string Yes The citation's sourceType — Document or Qna

Response (JSON): the same response shape is used for every kind of source; only the relevant fields are populated. The sourceType in the response is more specific than the input (it tells local documents apart from SharePoint ones).

Local document (sourceType = Local) — a file stored by AI desk PRO:

Field Type Description
fileName string The document filename
mimeType string MIME type of the file
previewUrl string A ready-to-open, Office Online-compatible preview link. The link is signed and short-lived
expiresAt string Expiry timestamp of previewUrl (default TTL: 1 hour)

SharePoint document (sourceType = Sharepoint or SharepointPage) — an indexed SharePoint file or page:

Field Type Description
fileName string The document filename
mimeType string MIME type of the file
webUrl string The SharePoint URL of the item
driveId string Microsoft Graph drive ID (typically null for pages)
driveItemId string Microsoft Graph drive item ID (typically null for pages)
siteId string Microsoft Graph site ID
pageId string Graph page ID (populated for SharePoint pages)

Microsoft Graph token required

For SharePoint sources, the MCP server returns coordinates only — it does not issue Microsoft Graph tokens. To open webUrl or download via /drives/{driveId}/items/{driveItemId}/content, your client must obtain its own Graph access token (e.g. via an interactive sign-in). The user's SharePoint permissions are re-checked server-side first, so a 403 is returned if the user is not allowed to read the document.

QnA (sourceType = Qna):

Field Type Description
question string The QnA question
answer string The QnA answer (see answerType for its format)
answerType string Simple (plain text), Card (adaptive card JSON), or Dialog (serialized dialog flow)

Error codes:

Code Cause
400 Empty referenceId or sourceType, unknown sourceType, or a non-GUID QnA referenceId
403 Reference belongs to another agent, SharePoint permission denied, or tenant mismatch
404 Document or QnA not found within the agent's scope

Example — Single question:

{
  "message": "What are the steps to request a day off?"
}

Example — Continue a conversation:

{
  "message": "And what about sick leave?",
  "chatId": "abc123-def456-..."
}

# Important information

  • MCP is currently a Preview feature — it may evolve or change during this phase
  • The MCP server version is 0.2.0
  • Authentication requires a valid Microsoft Entra ID JWT token
  • The agent must have MCP enabled in its configuration
  • Each agent has its own dedicated MCP endpoint
  • Chat sessions persist across calls when using the same chatId
  • Content filtering is applied to all MCP interactions, just like in Teams or webchat

← What’s new​ →