Setup in IBM watsonx Orchestrate

This guide walks you through adding your Leena AI Colleague to an IBM watsonx Orchestrate agent as an MCP toolkit, one step at a time. By the end, a watsonx Orchestrate agent will be able to talk to your AI Colleague in natural language — asking HR/IT/policy questions, triggering workflows, and running AOPs — on behalf of the signed-in user.

This page assumes you've already enabled the Leena MCP server. If you haven't, do that first (see Leena MCP Server → How to Enable It and Generate Credentials), then come back here.

This is about the MCP server, not the MCP client. In Leena's Orchestrator Settings, the MCP server lets external apps (like watsonx Orchestrate) call into your AI Colleague. That's the direction this guide uses. (The separate MCP client setting is for Leena calling out to other MCP tools — not relevant here.)

---

What you'll need before you start

On the Leena side — open your AI Colleague's Settings → Orchestrator Settings → MCP server page and have these ready:

On the watsonx Orchestrate side:

• An agent you can edit in Agent Builder (or create a new one).
• Permission to create Connections in your watsonx Orchestrate instance.

Two compatibility facts worth knowing up front:

• Transport: watsonx Orchestrate connects to remote MCP servers over Streamable HTTP (or SSE). Leena uses Streamable HTTP, so choose that — the two are compatible.
• Auth standard: watsonx Orchestrate supports OAuth 2.0 for MCP connections, but it does not support OAuth 2.1 or Dynamic Client Registration. This is exactly right for Leena, which issues you a fixed Client ID and secret from its dashboard rather than self-registering. So OAuth 2.0 is the correct choice and there's no compatibility gap.

Tip — generate the Leena secret right before you start. Leena shows the full client secret only once. If you lose it, generate a new one (which replaces the old).

---

Step-by-step

The recommended path is the Agent Builder UI: first create a reusable Connection that holds the OAuth credentials, then import the Leena MCP server into your agent and point it at that Connection. (An ADK CLI alternative is at the end.)

Step 1 — Create a new Connection

In watsonx Orchestrate, go to Manage → Connections and select Add new connection +.

Give it a connection ID and display name (e.g. leena-ai-colleague), then Save and continue. This connection is where the OAuth credentials live; you'll attach it to the MCP server in a later step.

Step 2 — Choose OAuth 2.0 Authorization Code and enter the Leena credentials

Configure credentials for draft & live environments. For the authentication type, select OAuth 2.0 Authorization Code, then fill in the values from the Leena settings page:

• Client ID → the Leena Client ID. Identifies your registered application to Leena.
• Server URL → the Leena MCP Server URL.
• Client secret → the Leena Client secret you generated. Proves the application is authorized.
• Authorization URL → the Leena Authorization URL. Where the user signs in to Leena and grants consent.
• Token URL → the Leena Token URL. Where watsonx exchanges the sign-in for an access token (and refresh token).
• Scopes → mention openid.

Step 3 — Set the credential type to Member credentials

When configuring the connection, choose Member credentials (per-user), not Team credentials.

This is the most important choice in the whole setup. Member credentials means each person who uses the agent authenticates to Leena as themselves — which is exactly how Leena works (every call is tied to a real user, with their own permissions). Team credentials would make everyone share one identity, which breaks Leena's per-user permissions and audience rules. Always use Member credentials for Leena.

Step 4 — Copy the callback URL and register it in Leena

When you configure an OAuth 2.0 connection, watsonx Orchestrate shows a callback URL (also called a redirect URL). It follows the pattern of your environment, for example:

https://<your-watsonx-orchestrate-env-url>/mfe_connectors/api/v1/agentic/oauth/_callback

Copy the exact callback URL shown, then switch to the Leena MCP server settings page and add it to the Redirect URIs field, and save.

This is the step people most often miss, and skipping it makes sign-in fail. A few notes:

• Leena requires redirect URIs to be HTTPS — the watsonx callback URL is HTTPS, so it's accepted.
• There's a natural ordering here: register the callback URL in Leena before anyone tries to sign in, otherwise Leena will reject the login.
• Always copy the exact value watsonx shows rather than typing it from memory — it varies by environment/region.

Save the connection in watsonx Orchestrate once the callback is registered in Leena.

Step 5 — Add your own credential to the connection (required)

With Member credentials, the connection starts out empty — it holds the OAuth configuration, but nobody's token yet. Before you can import the server, you (the admin doing the setup) must add your own credential by connecting your account to the connection. Open the credentials inside connections, use Add credential and select connection; watsonx sends you through the Leena sign-in and consent flow and stores your token against the connection.

Do this before Step 6. If you try to import the MCP server while the connection has no credential, the import fails — watsonx has no authorized token to reach Leena and list the tools. Once your account is connected, the import succeeds.

Step 6 — Import the Leena MCP server into your agent

Go to Build → Agent Builder and open your agent. In the Toolset section, select Add tool +, then MCP server, and choose Add MCP server.

Fill in:

• Select Remote MCP server.

• Give it a Server name (e.g. leena-mcp), then Save and continue.

• A short description of what the server does (e.g. "Answers HR/IT/policy questions and runs approval workflows, grounded in company knowledge"). The agent's model uses this to decide when to call Leena, so make it clear.

• MCP server URL → the Leena MCP URL (ends in /mcp/).

• Transport → Streamable HTTP.

• Connection → the connection you created and connected in Steps 1–5.

  

watsonx Orchestrate connects to Leena, validates the available tools (it waits up to ~30 seconds for the server to list them), and brings them in.

Step 7 — Select the tools

You'll see the Leena MCP server expose its three tools:

• send_message — the main one; sends a natural-language instruction to the AI Colleague.
• request_details — checks the status of an in-progress request.
• cancel — requests cancellation of a running or paused request.

Select the tools you want (keeping all three is fine) and add them. You don't see individual Leena skills here — Leena is a single conversational sub-agent, and send_message is how the agent talks to it.

Step 8 — Test it

Use the agent preview/chat in watsonx Orchestrate and try a prompt your AI Colleague can answer, for example: "What's our work-from-home policy?" or "Raise an IT ticket — my laptop won't connect to VPN."

---

How users sign in to Leena when using the agent

Because you chose Member credentials + OAuth 2.0, authentication is per user — not shared. Setup above used your identity; once the agent is in use, each person who uses it signs in to Leena themselves the first time the agent needs to call it.

What the user sees

1. A user chats with the agent and asks something that routes to Leena (e.g. "What's my leave balance?").

2. Because they haven't connected their Leena account yet, watsonx Orchestrate prompts them to connect / sign in rather than answering immediately.

   

3. They're taken to Leena's login — your organisation's normal sign-in (SSO/IdP) for Leena. They authenticate exactly as they would opening the Leena web app.

4. They approve the one-time consent that lets the agent talk to Leena on their behalf.

5. They return to the chat and get their answer — now scoped to their data and permissions.

   

After this first time, the user does not sign in on every message. watsonx Orchestrate stores their connection and uses the refresh URL to renew access quietly in the background, so it stays seamless until they revoke access or the connection expires.

Why each user signs in individually

The token a user gets represents that person. Leena resolves it on every call and runs the request under their own permissions, audience membership, and data scope. So:

• Two employees asking the same question get different, correctly-scoped answers — each only sees what they're entitled to.
• There is no shared/service login that would let one person's connection expose another's data. (This is precisely why Team credentials are the wrong choice for Leena.)
• Leena's guardrails and audit logging attribute every action to the real user, just like on the Leena web app.

What to tell your users (and set up)

• First-use prompt is expected. Let users know the one-time "connect to Leena" step is normal and safe — it's how the agent acts as them.
• They must be a provisioned Leena user. Anyone who isn't a valid user of that AI Colleague won't be able to connect; sort out access before rollout.
• Same SSO as Leena. Login goes through your existing Leena sign-in, so usually there's no new password.
• Re-consent is occasional. If a user revokes access, switches accounts, or the connection lapses, they'll simply be asked to connect again.

---

How the integration behaves at runtime

A few Leena-specific behaviors — and a few watsonx-specific limits — are worth understanding so you set the right expectations and agent instructions:

• Conversations are threaded. Leena returns a thread_id. To keep a multi-turn conversation coherent, the same thread_id should be reused on follow-up calls. Add a line to your agent's instructions reminding it to continue an existing Leena conversation rather than starting fresh each turn.
• Follow-up questions (input_required). When Leena needs more information it returns an input_required status in the tool response. The agent relays that question to the user and sends the answer back on the same thread. Note this works through ordinary send_message round-trips — it does not rely on MCP "elicitation," which watsonx Orchestrate doesn't support, so the clarification flow still works.
• Long-running work. Quick questions return in one call. Longer workflows/AOPs may come back with a running status, after which the agent calls request_details to poll for the result. Because watsonx Orchestrate can't cancel a running tool, prefer Leena requests that complete within a turn, and rely on request_details to follow up on longer ones rather than expecting to interrupt them.
• cancel has limited effect here. The tool is available, but watsonx Orchestrate doesn't let users stop a tool mid-execution, so cancel is best thought of as a way to abandon a paused request rather than to halt one that's actively running.
• Source links. When Leena returns a Sources section, those are authenticated links the user can click to open the underlying article. Instruct your agent to include them verbatim and not rewrite them.
• Forms and file uploads. Since the agent chat has no Leena composer, anything needing a file upload or structured form comes back as a webview link the user opens in a browser to complete.
• Tool list isn't auto-refreshed. If Leena's tools ever change, watsonx Orchestrate won't pick that up automatically — you'd reimport. In practice Leena's three tools are stable, so this rarely matters.

---

Troubleshooting

• Sign-in fails / "redirect URI mismatch": The watsonx callback URL isn't registered in Leena. Re-copy the exact callback URL from the connection config and add it to Redirect URIs in the Leena MCP settings (Step 4).
• "MCP not enabled" or connection rejected: Confirm the MCP server toggle is on for that AI Colleague, and that you're using credentials from the same AI Colleague.
• Import fails / "could not connect" with a valid URL: The connection has no credential yet. With Member credentials you must connect your own account to the connection first (Step 5); without an authorized token, watsonx can't reach Leena to list the tools.
• Import times out / no tools listed: watsonx waits up to ~30 seconds for Leena to list its tools. Re-run the import; confirm the MCP URL (ending in /mcp/) and that transport is set to Streamable HTTP.
• Everyone sees the same data, or wrong-user data: The connection is set to Team credentials. Switch it to Member credentials so each user authenticates as themselves.
• Token/secret errors after a while: The Leena client secret has an expiry. If it lapsed, generate a new secret in Leena and update the connection's credentials.
• Agent doesn't call Leena when it should: Sharpen the server/tool description (Step 6) so the model knows what kinds of requests belong to Leena.

---

Reference

IBM — MCP servers in watsonx Orchestrate: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=tools-mcp-servers