Part 16 of 15 • 🔴 Advanced • ⏱️ 120 minutes

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

Connecting watsonx Orchestrate AI agents to Planning Analytics SaaS over Model Context Protocol with dual authentication patterns.

#watsonxOrchestrate#IBMPlanningAnalytics#TM1#ModelContextProtocol#MCP#OAuth2.0#APIKeyAuth#EnterpriseAI

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

Step 1: Write Tool 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: Dependencies (`requirements.txt`)

ibm-watsonx-orchestrate>=2.9.0

Step 3: Agent Manifest (`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: Live Execution

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

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

💡 Pro Tips & Architecture Insights

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

📋 Open IBM Community Ready HTML