Overview

Connect your AI Colleague to any third-party application that speaks the Model Context Protocol (MCP) — SAP Joule, Microsoft Copilot, IBM watsonx Orchestrate, a custom agent, an internal LLM app, or any MCP-compatible client. Once connected, your application can talk to your Leena AI Colleague in plain natural language and get back grounded, permission-aware answers and actions, exactly as if the user were chatting in the Leena web app.

---

1. Overview

The Leena MCP Server turns your AI Colleague into a sub-agent that any MCP client can use as a single, intelligent tool.

Instead of exposing dozens of individual skills, forms, and workflows to the connecting application, Leena exposes one conversational surface. Your third-party app sends a natural-language instruction; the AI Colleague decides — on its own — which skills, knowledge sources, approval workflows, case-management actions, or organisation-specific AOPs to run, and returns the result. This is the same "agent brain" that powers the Leena web app, Slack, and Teams — only reachable programmatically.

What you can do once connected:

• Ask HR, IT, and policy questions and get answers grounded in your knowledge base, complete with clickable, authenticated source links.
• Trigger approval workflows, case creation, and custom AOPs through conversation.
• Carry on stateful, multi-turn conversations — the agent remembers the thread, pauses to ask follow-up questions, and resumes paused workflows automatically.

Who it's for: teams who want to embed their Leena AI Colleague inside another assistant or build a custom front-end, rather than using Leena's own channels. The consumer on the other end is typically another AI/LLM application, not a human clicking buttons — so the entire surface is text-in, text-out.

Key idea to keep in mind: every interaction is tied to a specific Leena end-user. The MCP connection authenticates as a person, so the AI Colleague applies that user's permissions, audience rules, and data access — just like any other channel. It is not an anonymous or "service account" firehose into your data.

Why a single orchestrator beats a flat list of tools

There are two ways to expose an enterprise system over MCP. The tool method publishes each capability as its own named tool — one for "search the knowledge base," one for "create a ticket," one per workflow — and expects the connecting app's model to pick and sequence them. The orchestrator method, which Leena uses, publishes a single conversational sub-agent and lets Leena's own orchestrator do the routing. For an enterprise assistant, the orchestrator method is the stronger choice:

• One stable contract. Your integration depends on three tools that never change. Skills, workflows, and AOPs can be added, renamed, or retired on the Leena side and your connected app keeps working — no re-integration, no broken tool schemas. With a flat tool list, every catalog change is a breaking change for every connected client.
• The reasoning happens on Leena's side. Choosing the right skill, chaining a multi-step AOP, filling a form, asking a follow-up, and grounding the answer in the knowledge base are all handled by Leena's orchestrator — the model it's tuned for. The connecting app doesn't need to understand dozens of tool schemas or sequence multi-step flows itself.
• Less for the client's model to get wrong. Exposing many tools bloats the connecting model's tool list, costs tokens, and raises the odds it picks the wrong tool or the wrong arguments. One conversational entry point keeps the client focused and the failure modes simple.
• Governance stays server-side. Permissions, audience targeting, guardrails (PII detection, moderation, jailbreak detection), citations, and audit logging are enforced once, inside Leena, for every request. A flat tool list would force each client to re-implement or be trusted to respect these — which doesn't scale and isn't safe.
• Grounding and citations are preserved. Answers come back already grounded, with authenticated source links attached. A raw tool call hands back data that the client then has to assemble, cite, and secure on its own.
• Statefulness is built in. Threads, multi-turn memory, and automatic resumption of paused workflows live in the orchestrator. A flat tool list is inherently stateless and pushes all of that complexity onto the client.

In short, the tool method gives a client deterministic, low-level control at the cost of a brittle, high-maintenance, governance-heavy integration. The orchestrator method trades that fine-grained control for a single durable surface that stays correct, secure, and grounded as your AI Colleague evolves. (The one thing you give up — naming an exact skill yourself — is covered under Limitations.)

---

2. Authentication

Supported method: OAuth 2.0, per user

The Leena MCP server supports exactly one authentication method — OAuth 2.0 — with the access token sent as a Bearer token in the Authorization header on every call. There is no API-key mode and no anonymous access: every connection is an authenticated, individual user.

The OAuth roles line up like this:

• Leena MCP server — the resource server. It validates the bearer token on each request and resolves it to a specific AI Colleague and end-user.
• Leena's chat/auth service — the authorization server. This is where users actually sign in and where access and refresh tokens are issued. The authorization, token, and refresh URLs on the settings page all point here.
• Your third-party app — the OAuth client. It holds the Client ID and secret issued from the dashboard and drives the login flow.

Discovery: automatic where supported

Leena publishes standard OAuth discovery metadata, so a compliant MCP client pointed at the MCP URL can find the sign-in endpoints on its own — you don't have to wire them by hand. For clients that need the endpoints spelled out (for example, a "manual OAuth" configuration), the authorization, token, and refresh URLs are all listed on the MCP server settings page.

Identity is per-user — and that shapes everything

A token represents the person who signed in, not your application in the abstract. On every call, Leena resolves the token to that user and runs the request under their permissions, audience membership, and data scope. In practice:

• The same connection returns different results for different users — each sees only the data they're entitled to.
• There is no service-account or machine-to-machine bulk access; the connecting principal is always a real, provisioned AI Colleague user.
• Guardrails and audit logging apply exactly as they do on any human channel.

Prerequisite

Authentication only succeeds when the MCP server is enabled for that AI Colleague (see Section 4). Until it's enabled, even valid tokens are rejected.

---

3. The Tools

When your application connects, the Leena MCP Server advertises exactly three tools. You do not see individual Leena skills as separate tools — you only see these three, and the agent routes everything internally.

send_message

The primary tool. Sends a natural-language instruction to the AI Colleague.

• Start a new conversation: call send_message with just your message. A new conversation thread is created and its ID is returned.
• Continue a conversation: pass the thread_id from a previous response along with the new message. The agent picks up where it left off and automatically resumes any paused workflow.

send_message waits for the agent to finish and then returns one of these outcomes:

While the agent is working, send_message streams lightweight progress updates roughly every 10 seconds so your client knows it's alive.

Source links are special. When a response contains a Sources section with markdown links, those are authenticated deep links the user can click to open the underlying article (often jumping straight to the highlighted passage). Always pass them through to the user exactly as provided — don't drop or rewrite them.

request_details

Checks the current state of a conversation without sending a new message. You pass a thread_id (and optionally a specific request_id) and get back the same status shape as send_message. This is how you poll a long-running request after send_message returns running.

cancel

Stops a running or paused request in a thread. Pass the thread_id. Returns canceled on success, or tells you the request was already finished.

The conversation model in one line

Threads are stateful. Start without a thread_id, continue with the one you were given, poll with request_details, and stop with cancel. Handle input_required by asking the user and replying on the same thread.

---

4. How to Enable It and Generate Credentials

Everything is configured in the dashboard. You'll need a Leena admin/dashboard user to do this.

Step 1 — Turn on the MCP server

1. Open your AI Colleague's Settings → Orchestrator Settings.
2. Find the MCP server option (the outbound-exposure one, not the MCP client).
3. Toggle it on.

Turning this on does two things: it allows MCP clients to authenticate against this AI Colleague, and it automatically provisions an OAuth application behind the scenes for external access. If that provisioning fails for any reason, the toggle is rolled back automatically — so if it stays on, your OAuth app exists.

MCP and A2A (agent-to-agent) share the same OAuth application for a given AI Colleague. Enabling either one provisions it; you don't set up credentials twice.

Step 2 — Read your connection details

Once enabled, the MCP server settings page shows everything your third-party app needs:

• MCP URL — the endpoint your MCP client points at (ends in /mcp/).
• Client ID — the OAuth client identifier for your AI Colleague.
• OAuth endpoints — the authorization URL, token URL, and refresh URL. (These point to Leena's chat/auth service, which acts as the OAuth authorization server.)
• Redirect URIs — currently registered (empty until you add one).
• Client secret status — whether a secret exists and when it expires.

Step 3 — Register your redirect URI(s)

If your MCP client uses the interactive OAuth login flow (most do), you must register the redirect URI(s) it will use.

• Redirect URIs must use HTTPS.
• The only exception is loopback addresses (localhost, 127.0.0.1, [::1]) over plain HTTP — useful for local development and desktop MCP clients.
• Any other plain-HTTP URI is rejected.

Add your app's callback URL(s) in the redirect-URI field and save.

Step 4 — Generate a client secret

Click Generate secret on the MCP server settings page.

• The full secret is shown exactly once, at generation time. Copy it immediately and store it securely — Leena keeps only a hint/reference afterward, never the full value.
• The secret has an expiry date (shown on the settings page). Plan to rotate it before it lapses; generating a new secret replaces the old one.

Step 5 — Connect from your third-party app

In your MCP client, configure a new MCP server using:

• Server URL: the MCP URL from Step 2.
• Authentication: OAuth, using the Client ID, client secret, and the authorization/token URLs from the dashboard.

Leena follows standard OAuth discovery: a well-behaved MCP client pointed at the MCP URL can discover the authorization server automatically and walk the user through login. After the user logs in, the client receives a token and is connected.

When the user authenticates, the connection is bound to that user's identity — so the AI Colleague will only ever see and do what that user is allowed to.

Turning it off

Toggling the MCP server off disables external access and clears the associated OAuth application. Re-enabling provisions a fresh one.

---

5. Limitations and How It Differs from Other Leena Channels

The MCP server runs your request through the same orchestration engine as the Leena web app — same skills, same AOPs, same knowledge base, same case management, same guardrails, and the same audience/permission enforcement. Functionally, the capabilities are identical. What differs is the surface: MCP is a text-only, programmatic channel meant to be driven by another application, whereas web, Slack, and Teams are rich, human-facing channels.

Here's what that means in practice.

Everything comes back as text

Leena's human channels render rich interactive elements natively — forms, tables, charts, carousels, auth cards, and confirmation cards. Over MCP there is no UI to render these, so the agent returns plain text / markdown. Your consuming application is responsible for presenting it.

Forms and file uploads fall back to web links

The MCP channel has no composer, so a user cannot attach files inline the way they can in the web or Slack chat box. When a skill needs a file upload or a structured form, the agent returns a pre-filled webview link instead — the user opens that link in a browser to complete the form or attach the file, then the conversation continues. This is the same fallback used for phone voice calls. (Web, Slack, and Teams support inline attachments directly.)

Long-running work needs polling

For quick answers, send_message returns the final result in a single call. But the agent only waits a bounded amount of time (around 5 minutes) before returning running. Long workflows and AOPs will exceed that, so your app must poll with request_details until the request reaches a terminal state. Human channels handle this invisibly with live UI updates; over MCP you orchestrate the polling.

Follow-up questions are your app's responsibility

When the agent needs more information it returns input_required with a prompt. In the web app, the user just sees the question and types back. Over MCP, your application must relay that prompt to the user and send the answer back on the same thread. Nothing happens automatically until you do.

It's per-user, not a service connection

Every MCP call is authenticated as a specific Leena end-user via their bearer token. There is no anonymous or shared "machine" access. The connecting user must be a valid, provisioned user of that AI Colleague, and they will only get the data and actions their permissions and audience rules allow. This is a deliberate safety property, but it means you can't use MCP as a generic bulk-data API.

The agent decides; you don't pick skills

Unlike a traditional tool API where you call a named endpoint, MCP gives you one conversational entry point. You describe what you want in natural language and the AI Colleague chooses the skill/workflow. You gain the agent's reasoning, but you give up direct, deterministic "call exactly this function" control.

Credential hygiene

The client secret is shown once and expires. If you lose it you must generate a new one (which invalidates the old), and you must rotate before expiry to avoid an outage. Redirect URIs are restricted to HTTPS (plus loopback for local dev).

Quick comparison

---

6. Quick Start Checklist

1. Enable the MCP server in Orchestrator Settings → MCP server.
2. Copy the MCP URL, Client ID, and OAuth endpoints from the settings page.
3. Add your app's redirect URI (HTTPS, or loopback for local dev).
4. Generate a client secret and store it securely (shown only once).
5. Configure your MCP client with the URL + OAuth credentials and log in as a valid AI Colleague user.
6. Send a send_message with no thread_id to start; reuse the returned thread_id to continue.
7. Handle input_required (relay to user) and running (poll with request_details).
8. Pass through any Sources links to the user verbatim.
9. Rotate your client secret before it expires.