IBM Planning Analytics (TM1) Enterprise MCP Integration: API Key & OAuth 2.0 Authentication Flows

By Markus van Kempen | Series: WXO Labs & Tutorial Guide (Part 16 of 15)
Interactive Lab Portal: https://markusvankempen.github.io/wxo-labs/
GitHub Repository: https://github.com/markusvankempen/wxo-labs

Why This Pattern Matters

Enterprise financial analysts and business planners rely on IBM Planning Analytics (TM1) for multi-dimensional cube budgeting, rolling forecasts, and variance modeling. Connecting watsonx Orchestrate agents to TM1 via the Model Context Protocol (MCP) enables conversational querying of TM1 servers, cubes, dimensions, and MDX views. This lab covers two end-to-end authentication patterns: Flow 1 (API Key/Basic Auth with realm='apikey') which works seamlessly on both SaaS trials and enterprise tenants, and Flow 2 (OAuth 2.0 Authorization Code Flow via PA Workspace with the mandatory v0userContext scope).

📋 Prerequisites & Setup

Ensure your environment has the required dependencies:

pip install ibm-watsonx-orchestrate

Verify active environment:

orchestrate env list

🛠️ Step 1: Implement the Logic (toolkit_pa_apikey.yaml)

spec_version: v1
kind: mcp
name: planning_analytics_apikey
description: "IBM Planning Analytics MCP Universal Endpoint (API Key / Basic Auth)"
transport: streamable_http
url: "https://<region>.planninganalytics.saas.ibm.com/api/<tenant_id>/v0/agentic-ai/ibm-pa-tools/mcp"
tools:
  - "*"

📦 Step 2: Declare Dependencies (requirements.txt)

ibm-watsonx-orchestrate>=2.9.0

🤖 Step 3: Configure the AI Agent (agent.yaml)

spec_version: v1
kind: native
name: planning_analytics_agent
title: "IBM Planning Analytics AI Agent"
description: "Enterprise financial and operational planning agent connected to IBM Planning Analytics via MCP."
model: ibm/granite-3-8b-instruct
instructions: |
  You are an expert IBM Planning Analytics (TM1) financial and operational planning assistant.
  Inspect available TM1 servers or cube schemas, and execute queries using the appropriate tool.
tools:
  - planning_analytics_apikey:get_available_tm1_servers
  - planning_analytics_apikey:get_tm1_cubes
  - planning_analytics_apikey:get_cube_dimensions
  - planning_analytics_apikey:list_cube_views
  - planning_analytics_apikey:get_cube_sample_members
  - planning_analytics_apikey:execute_mdx_and_get_view

🚀 Step 4: Import & Test Live in Terminal

Import tool and test conversationally:

orchestrate chat ask -n planning_analytics_agent "What are the available TM1 servers?"

Live Response:

╭─ 🤖 planning_analytics_agent ────────────────────────────────────────────────╮
│                                                                              │
│  The TM1 environment currently has the following server available:           │
│                                                                              │
│  - **BusinessFlow**                                                          │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

💡 Pro Tips & Gotchas

• CM-UNKNOWN-001: Failed to obtain access token: PA Workspace OAuth strictly mandates the scope `v0userContext`. Without this scope, the OAuth token endpoint rejects the exchange.
• Trial vs Enterprise Subscriptions: In trial accounts, the Administration > Integrations menu is restricted. Always use Flow 1 (API Key / Basic Auth with realm='apikey') which is 100% supported on all tiers.
• Universal Route Handshake: Ensure the remote endpoint URL matches your account and tenant ID: `https://.planninganalytics.saas.ibm.com/api//v0/agentic-ai/ibm-pa-tools/mcp`.

🏷️ Recommended Community Tags

When publishing this blog post, select or enter the following tags in the community editor:

watsonx Orchestrate, IBM Planning Analytics, TM1, Model Context Protocol, MCP, OAuth 2.0, API Key Auth, Enterprise AI

🗺️ Series Roadmap (15 Hands-On Labs)

This tutorial is Part 16 of 15 in the complete enterprise hands-on series:

• 🟢 Part 1: Building Your First Custom Python Tool & AI Agent in 15 Minutes
• 🟢 Part 2: Input Defaults & UI Patterns (Pydantic Schemas)
• 🟢 Part 3: File Upload & Spreadsheet Analytics (Pandas Pipeline)
• 🟡 Part 4: Ambient User Context & Identity Injection
• 🟡 Part 5: Asynchronous Non-Blocking Workers & Polling
• 🟡 Part 6: Dynamic PDF Generation & File Streaming
• 🟡 Part 7: Model Context Protocol (MCP) STDIO Basics
• 🔴 Part 8: MCP Enterprise Security & Bearer Token Injection
• 🔴 Part 9: Role-Based Access Control (RBAC) Pre-Invoke Plugins
• 🔴 Part 10: Microsoft Entra ID (Azure AD) SSO & SAML Federation
• 🔴 Part 11: Agent CI/CD Lifecycle & Automated Multi-Env Promotion
• 🏆 Part 12: Tamper-Proof Audit Vault & Conversation Archiving
• 🏆 Part 13: Real-Time Telemetry & Token Observability Dashboard
• 🏆 Part 14: Quantitative RAG Pipeline Evaluation with Ragas
• 🔴 Part 15: Remote Containerized MCP Gateways on IBM Cloud Code Engine

Explore the interactive curriculum and code repository:

• 🌐 Interactive Portal: https://markusvankempen.github.io/wxo-labs/
• 📦 GitHub Repository: https://github.com/markusvankempen/wxo-labs
• 🏢 Author Research: https://markusvankempen.github.io/