CNH Polarion–Jira MCP Server

v2.9.0 — Per-user self-service portal & secure per-user access

Author: Purush Ramu  |  Date: Jun 15, 2026

This release lets each engineer connect once and then ask across Polarion and Jira as themselves. You set your role and credentials in a branded portal; the assistant acts with your own access, with your own audit trail.

Per-user configuration portal

A self-service web app at /mcp/config. Sign in with Microsoft (Entra SSO), then set your role profile, your default Polarion and Jira projects, and store your Polarion Personal Access Token plus your Jira credentials.

• Credentials are encrypted at rest (AES-256-GCM) and are never shown back to you — the form displays only whether a secret is set and when it was last validated.
• Saving runs a live validation against Polarion and Jira before anything is stored, so a bad token is caught immediately rather than on first use.
• Your configuration is private to you and is keyed to your Entra identity.

Secure per-user downstream access (no shared service account)

A new downstream auth mode, user-config-db, lets OAuth clients — Claude and Microsoft Copilot — call Polarion and Jira using each signed-in user's own stored credentials, resolved from their Entra identity.

• This removes the need for header-passing, which OAuth clients cannot do, and resolves the Jira 401 those clients previously hit.
• Calls are attributed to the real person, not a shared service account.

Per-user usage dashboard

Each user sees their own call count, estimated token usage, success and error totals, a 7-day trend, and a recent-activity log. Capture is asynchronous and non-blocking, and old rows are pruned on a retention schedule.

Project pickers

Polarion projects are now a searchable multi-select sourced from the in-memory project index. Jira projects load from your saved Jira token, so the picker reflects exactly what you can see.

Role profiles, per request

The X-MCP-Profile header now accepts multiple comma-separated profiles, applied as a de-duplicated union. New systems and planning profiles join dev, quality and full. X-Polarion-Project / X-Jira-Project set a default search scope.

• When recommended headers are absent, the initialize response advertises them under serverNotices and clientConfig.configTemplate.
• A _configHint is attached to tool responses so header-less clients are guided to the right configuration.

New tool: polarion.v2.getWorkflowActions

Returns the legal workflow transitions for a work item, with each target status's enum id and human label, so a status change uses the correct value rather than a guess.

Reliability fixes

• Status transitions now use the correct HTTP method and qualified id, fixing the 405.
• Authorship and assignee queries preserve author.id / assignee.id and are no longer silently rewritten, which had returned zero results.
• A project hint that is a tracker prefix (e.g. PTGENIII) now resolves to its project.
• MCP clients can POST to the endpoint without a trailing slash; the context-root redirect that dropped the request is fixed.

Full details: RELEASE_NOTES_2_9_0.md · Onboarding: SETUP_COPILOT_AND_CLAUDE.md

Release 2.8.1 — Cross-System Orchestration, Reliability & Bug Reporting

Author: Purush Ramu  |  Date: Jun 10, 2026

One-call cross-system orchestration

bridge.v2.getJiraTestContext — a Jira issue key returns, in a single call, the issue, its linked Polarion test run, run records, and the requirements those test cases verify, with link confidence/method, warnings, and provenance. Pass testRunId to skip link discovery. Replaces the N+1 getIssueBundle + multi-Polarion-call pattern.

New tools

Role-based tool profiles

MCP_TOOL_PROFILE = standard (13) | quality (21) | dev (20) | systems (17) | planning (19) | full (85). Profiles control discovery only; every tool stays callable by name via tools/call regardless of profile.

Per-user profiles & faster search

The server-wide MCP_TOOL_PROFILE is now overridable per request — no restart, no shared config. Send the X-MCP-Profile header to pick the tools your role needs; absent or blank, the server default is used unchanged.

• Multi-value union: X-MCP-Profile takes a comma/space-separated list (e.g. dev,quality). The effective tool set is the union of standard + each named profile, de-duplicated by canonical name. standard is always the base, so the core tools are never lost. full returns the whole catalog; unknown names are ignored (logged).
• Role → profile map: quality (QA/test/compliance) · dev (implementation engineers) · systems (System Engineers: spec quality, requirement test-coverage, defect impact, implementation summaries) · planning (TPM/RTE/PM/Scrum: project plans, release work items, unified my-work, cross-system sync, Jira velocity, compliance matrix) · full (admin/Inspector).
• Default search scope: X-Polarion-Project and X-Jira-Project set your main project. They are applied only as a fallback when a tool call omits the project — explicit project arguments are never overridden.
• Profile-miss hint: calling a tool that is not in your active profile still works; the response carries a soft _profileHint telling you which profile exposes it and how to add it.
• Discoverability: when these recommended headers are absent, the initialize response advertises them under serverNotices and clientConfig.recommendedHeaders / clientConfig.missingRecommended.
• Auto-config prompt: if any recommended header is missing, initialize also returns a ready-to-paste clientConfig.configTemplate — a complete mcp.json (auth headers shown as placeholders) plus configTemplateNote — so the agent can show the user exactly what to add rather than just naming the header.
• Hint on tool responses: because generic clients (VS Code) drop custom initialize fields, the same advice is re-surfaced as a _configHint on tool-call responses (the channel agents relay). The first tool call made without the recommended headers tells the user which to add and points to the configTemplate.

Per-call observability

Every tool response carries a _metrics block (responseTimeMs, payloadChars, payloadBytes, estimatedTokens). Payload/token sizes also flow to Micrometer (mcp.tool.payload.*) and /actuator/prometheus.

Key fixes

• Work-item creation 400 (fields[workitems]): write URLs no longer carry JSON:API sparse fieldsets or pagination — these are valid only on GET. Unblocked ALL create/update once write mode was on.
• detailedStatus reliability: document tool auto-requests it, handles array-valued enums, and returns precomputed cross-tabs (byTypeStatusAndDetailedStatus); a missing field reads as UNRESOLVED, never a false zero.
• Verified-requirement resolution: link-object ids (…/verifies/…/<reqId>) are parsed so test-case requirements resolve; parent/other roles excluded.
• tools/call on non-default profiles: existence checked against the registry, so any tool is callable by name.
• Document resolution clarifies on ambiguity instead of silently guessing; OAuth 401 returns a proper WWW-Authenticate challenge.

Full details: RELEASE_NOTES_2_8_1.md · HTML

Release 2.8.0 — Write-Back Enablement, Audit & Remote OAuth

Author: Purush Ramu  |  Date: Jun 5, 2026

Write-back tools (preview-first)

v2.createWorkItem cross-system create dispatcher (asks Polarion vs Jira before writing), plus controlled comment/transition/test-record writes. Every mutating tool is dry-run gated and @WriteTool-audited under X-User-Id.

Ambiguity guardrail & audit coverage

GuardrailValidator intercepts ambiguous create intents before any write; full @WriteTool annotation coverage makes every mutation traceable in audit logs.

Full details: RELEASE_NOTES_2_8_0.md

Release 2.7.0 — Audit Identity, New Workflow Tools, Cache & Webhook

Author: Purush Ramu  |  Date: May 29, 2026

X-User-Id — zero-anonymous audit logs

Add header X-User-Id: <your-username> to your MCP client configuration. Identity resolves without any Polarion REST call. When missing, every tool response warnings[] includes setup instructions. The initialize response includes serverNotices and clientConfig.missingRecommended so agents surface the setup requirement automatically.

4 new workflow tools

Document work-items TTL cache

Repeated access to the same document returns in <5ms (vs ~1s customapi call). TTL default 300s, configurable via MCP_CACHE_DOCUMENT_TTL. Invalidated immediately by webhook on work item change.

Webhook fine-grained invalidation

POST /mcp/webhook/polarion now invalidates the specific document work-items cache entry, not just the project. Document creation events trigger a full index rebuild so new documents are discoverable immediately.

Explicit input schemas

Top 5 tools now have typed inputSchema.properties with descriptions. Agents no longer guess parameter names. require() marks mandatory fields.

Full details: RELEASE_NOTES_2_7_0.md

Release 2.6.0 — Zero-REST Resolution, Project Index & Plan Fix

Author: Purush Ramu  |  Date: May 29, 2026

Project Index — zero REST project resolution

The document index now also builds three project lookup maps (projectById, projectByName, projectByTrackerPrefix) in the same startup pass. Project resolution across all tools now hits the index first — zero REST calls when the index is ready. Previously getDocumentWorkItemsSmart triggered 369 REST calls just to resolve one project ID.

Auto-resolve project from work item ID

resolveProjectId now extracts the tracker prefix from any work item ID (e.g. PTT from PTT-3019) and resolves the project automatically from the index. Agents no longer ask users for a project ID when the work item makes it unambiguous.

Custom API URL fix

buildCustomApiUrl was appending the servlet path to baseUrl which already contained /rest/v1, producing a 404 on every call. Fixed to strip /rest/v1 before building the URL. The fast custom API path now returns all document work items in a single call with hierarchy preserved.

Silent probe logging

New RestClient.polarionGetQuiet(): expected 404s from metadata probe endpoints log at DEBUG instead of ERROR with stack traces, removing ~30 lines of log noise per request.

Correct Polarion plan Lucene syntax

getReleaseWorkItems now uses PLAN:(projectId/planId) as primary query (correct Polarion syntax). The old plannedIn/targetRelease/release field query is retained as fallback. A bare PLAN: query that caused a SystemError is now properly wrapped with error handling and Lucene escaping.

3 new MCP tools

Auth fix for index endpoints

/mcp/v2/index/* endpoints are now open paths — no token required. Previously the security filter rejected requests before the controller was reached.

Index refresh schedule

Daily refresh changed from 02:00 to 14:00 UTC. Override via MCP_DOCUMENT_INDEX_CRON env var.

Performance summary

Full details: RELEASE_NOTES_2_6_0.md

Release 2.5.0 — Document Index & Accurate Status Counts

Author: Purush Ramu  |  Date: May 29, 2026

Multi-Map Document Index

A new DocumentIndexService loads all Polarion documents at startup (async, non-blocking) and maintains four in-memory maps for O(1) or O(query-token) lookups:

Status endpoint: GET /mcp/v2/index/status. Configuration keys: mcp.document-index.enabled, mcp.document-index.cron, mcp.document-index.max-projects.

Accurate document status counts

getDocumentWorkItemsSmart now always returns statusSummary with accurate totalCount, byType, byStatus, and byTypeAndStatus. Use summarizeOnly: true for count-only requests — fetches ALL pages internally for documents of any size.

Full details: RELEASE_NOTES_2_5_0.md

Release 2.4.0 — Enterprise Observability, Identity & Resilience

Author: Purush Ramu  |  Date: May 26, 2026

Full details: RELEASE_NOTES_2_4_0.md

Release 2.3.0 — Enterprise Features & Copilot Launch Fixes

Author: Purush Ramu  |  Updated: May 26, 2026

13 new V2 tools

All write tools use the preview-first dryRun guardrail. They return a preview by default and execute only when dryRun=false, confirmed=true are both present.

Enterprise platform additions

• Structured audit logging (AuditLogger) — Wraps all 22 write tools at the dispatcher level. Actor is resolved from the OAuth JWT (preferred_username → oid → sub). Every write produces a structured JSON log entry on com.cnh.mcp.AUDIT with traceId, actor, tool, durationMs, and outcome. ISO 26262 / ASPICE compliant.
• Real health indicators — PolarionHealthIndicator and JiraHealthIndicator probe live connectivity via Spring Boot Actuator at GET /mcp/actuator/health. Returns UP with response-time detail or DOWN with error detail.
• TTL response cache (McpResponseCache) — Project entries expire after 60 s, metadata after 120 s. Fully configurable via MCP_CACHE_* env vars. Can be disabled with MCP_CACHE_ENABLED=false.
• Webhook receivers — POST /mcp/webhook/polarion and POST /mcp/webhook/jira receive push events and invalidate cache entries in real time. Protected by MCP_WEBHOOK_SECRET.
• Plugin-pattern dispatcher — MCPDispatcher replaced with ToolRegistry plugin lookup. New tools require only @Component — no dispatcher modifications needed.

Copilot launch fixes (blocking issues resolved)

Copilot readiness — all blocking issues resolved

New configuration properties

MCP_CORS_ALLOWED_ORIGINS=https://copilotstudio.microsoft.com,https://vscode.dev
MCP_WEBHOOK_SECRET=<shared-secret>
MCP_CACHE_ENABLED=true
MCP_CACHE_PROJECT_TTL=60
MCP_CACHE_METADATA_TTL=120

Bug fixes in 2.3.0

• Removed System.out.println body logging from McpController — sensitive request content was leaking to standard output.
• BaseMCPTool.paramAsInt no longer throws NumberFormatException on invalid input — returns null gracefully.
• Removed duplicate initialize intercept block in McpController that was returning a stripped capabilities:{} response to some clients.

Upgrade from 2.2.4

No breaking changes. Deploy the new WAR, set MCP_CORS_ALLOWED_ORIGINS in your environment, optionally configure webhook and audit log output. Verify with GET /mcp/actuator/health.

Release 2.2.0 — Copilot / VS Code Enterprise Hardening

Author: Purush Ramu
Updated: May 20, 2026

What changed

• Added snake_case aliases for high-value V2 tools for VS Code and GitHub Copilot Agent Mode.
• Improved tools/list metadata with canonical names, alias markers, read/write flags, recommended indicators, confirmation requirements, examples, and response-shaping parameters.
• Added /mcp/auth/jwt-test for Microsoft Entra JWT diagnostics.
• Added server-side V1 guardrail validation to return clarification_required instead of raw parameter failures.
• Added smart fallback for Polarion search from standard search to Lucene.
• Added assigned-work workflow tools for daily engineering use.
• Added controlled write-back workflow tools with dry-run and explicit confirmation.

Recommended Copilot aliases

polarion_v2_resolve_project
polarion_v2_resolve_document
polarion_v2_search_smart
polarion_v2_get_work_item_bundle
polarion_v2_get_traceability_bundle
polarion_v2_get_my_work_items
polarion_v2_get_engineering_context
jira_v2_search_smart
jira_v2_get_issue_bundle

Controlled write-back rule

{
  "dryRun": false,
  "confirmed": true
}

Without these flags, write-back tools return a preview only.

Release Summary

This release page documents both the stable V1 MCP contract and the additive V2 enhancements. V2 does not remove, rename, or change existing V1 tools.

Version 1 — Stable MCP API

• Existing JSON-RPC endpoint remains POST /mcp/.
• Existing methods remain supported: initialize, tools/list, tools/call, resources, and prompts.
• Existing V1 Jira and Polarion tool names remain unchanged.
• Strict Polarion workflow remains enforced: project → document → work items.
• Jira authentication now supports per-user request headers while preserving optional legacy fallback.

Latest Release — 2.7.0

• X-User-Id audit: Add X-User-Id: <username> header to your MCP config — no more anonymous audit logs. Missing header triggers a warning in every tool response.
• 4 new tools: getReleaseReadiness, getUnifiedMyWork, getTestCoverageForRequirement, getCrossSystemSyncStatus.
• Document cache: 5-min TTL cache for document work items. <5ms repeat access. Webhook invalidation.
• V2 tool total: 35 tools. See Release 2.7.0 for full details.

Previous Release — 2.6.0

• Project index: Zero REST calls for project resolution — all tools now resolve project ID, name, and tracker prefix from the in-memory index.
• Auto project from work item ID: Passing PTT-3019 without a project ID automatically resolves to polarionTaskTracker via tracker prefix.
• Custom API URL fix: getDocumentWorkItemsSmart now correctly calls /polarion/customapi/ instead of /polarion/rest/v1/customapi/, eliminating the REST fallback.
• 3 new tools: polarion.v2.listProjectDocuments, polarion.v2.rebuildDocumentIndex, polarion.v2.getDocumentIndexStatus.
• Plan query fix: getReleaseWorkItems now uses PLAN:(projectId/planId) — correct Polarion Lucene syntax.
• V2 tool total: 31 tools. Index refresh: 14:00 UTC daily.
• See Release 2.6.0 above for full details.

Previous Release — 2.5.0

• Multi-map document index: O(1) document resolution from in-memory index — zero REST round-trips per request.
• Accurate status counts: statusSummary now paginates all pages for correct totals on large documents.
• See Release 2.5.0 for full details.

Version 2 — Additive Enhancements

V2 adds smart workflow tools, session context support, richer capability discovery, and a dedicated information endpoint.

Authentication Summary

Agent Configuration Example

{
  "name": "Polarion-Jira MCP",
  "url": "https://p2c.cnhind.com/mcp/",
  "headers": {
    "Authorization": "Bearer <USER_POLARION_PAT>",
    "X-Jira-User": "user@example.com",
    "X-Jira-Token": "<JIRA_API_TOKEN>"
  }
}

Enterprise Documentation Addendum

The existing V1/V2 release notes remain unchanged. The following addendum adds enterprise OAuth, PAT/OAuth migration, Copilot Studio integration, security controls, and deployment validation while keeping the current documentation structure available.

Recommended migration settings

MCP_AUTH_MODE=both
MCP_PAT_ENABLED=true

Final enterprise settings

MCP_AUTH_MODE=oauth
MCP_PAT_ENABLED=false

Release History / Change Index

This index summarizes each release section and the changes delivered so teams can quickly verify what changed, what remained compatible, and what to test.

Release 2.7.0 — Audit Identity, Workflow Tools, Cache, Webhook (current)

• Fixed: Audit logs now show real username via X-User-Id header (no Polarion REST call).
• Added: getReleaseReadiness, getUnifiedMyWork, getTestCoverageForRequirement, getCrossSystemSyncStatus tools.
• Added: Document work-items TTL cache (300s, webhook-invalidated).
• Added: Fine-grained webhook invalidation — document-level cache eviction + index rebuild on document events.
• Added: Explicit inputSchema on top 5 tools. initialize response includes serverNotices and clientConfig.
• Compatibility: Fully additive and non-breaking.

Release 2.6.0 — Zero-REST Resolution, Project Index & Plan Fix

• Added: Project index (projectById, projectByName, projectByTrackerPrefix) built in the same startup pass as document index.
• Fixed: resolveProjectId now checks index first and auto-resolves from work item tracker prefix when projectId is blank.
• Fixed: buildCustomApiUrl was building wrong URL (/rest/v1/customapi/ instead of /polarion/customapi/).
• Fixed: getReleaseWorkItems now uses PLAN:(projectId/planId) Lucene syntax with escapeLucene() and fallback.
• Fixed: /mcp/v2/index/* endpoints blocked by auth filter — now open paths.
• Added: polarionGetQuiet() — probe 404s downgraded from ERROR+stack to DEBUG.
• Added: 3 new tools: listProjectDocuments, rebuildDocumentIndex, getDocumentIndexStatus.
• Changed: Index refresh time: 02:00 → 14:00 UTC.
• Compatibility: Fully additive and non-breaking.

Release 2.5.0 — Document Index (O(1) Resolution)

• Added: DocumentIndexService — four-map in-memory document index (byExactId, byModulePrefix, byTitleToken, byProject), built async at startup and refreshed daily.
• Fixed: Document-scoped status counts now accurate for any document size — REST fallback paginates all pages.
• Added: summarizeOnly parameter for count-only requests. statusSummary always returned.
• Fixed: Compilation errors from 2.4.x series restored five missing methods.
• Compatibility: Fully additive and non-breaking.

Release 2.4.0 — Enterprise Observability, Identity & Resilience

• Added: Hybrid PAT/OAuth authentication filter with Microsoft Entra ID JWT validation.
• Added: Per-request audit logging, rate limiting, structured error responses.
• Added: Response shaping, token budget controls, McpResponseCache TTL layer.
• Compatibility: Fully additive and non-breaking.

Release 2.3.0 — Enterprise Features & Copilot Launch Fixes

• Purpose: Add 13 new V2 tools, enterprise audit/cache/health/webhook platform features, and resolve two blocking Copilot Studio launch issues.
• Added: Jira V2 write tools (createIssue, addComment, transitionIssue), Polarion V2 test management (searchTestCases, getTestRunSummary, updateTestRecord), cross-system bridge tools (createJiraFromPolarion, syncStatus, getComplianceMatrix), and polarion.v2.createWorkItemSmart.
• Added: AuditLogger for write-operation traceability (ISO 26262 / ASPICE), Spring Boot Actuator real health probes, TTL response cache with webhook invalidation, plugin-pattern MCPDispatcher.
• Fixed: mcp_v2_capabilities now reflects all 28 V2 tools and 27 snake_case aliases — was listing only 19.
• Fixed: Explicit CorsConfigurationSource bean in SecurityConfig — Copilot Studio OPTIONS preflights were previously rejected.
• Fixed: McpController request body logged to System.out; BaseMCPTool.paramAsInt threw on invalid input; duplicate initialize intercept stripped tool capabilities.
• New unit tests: BaseMCPTool, McpV2Support, GuardrailValidator, McpResponseCache, ToolAliasSupport.
• Compatibility: Fully additive and non-breaking.

Release 2.2.4 — Startup Hotfix

• Purpose: Fix missing UnauthorizedException class at startup causing deployment failure.
• Changed: Packaging fix to ensure com.cnh.mcp.security.UnauthorizedException is included in the deployable WAR.
• Deployment note: Remove the old exploded WAR directory from the app server before deploying this hotfix.
• Compatibility: Non-breaking.

Release 2.2.3 — VS Code Array Schema Fix

• Purpose: Fix VS Code / GitHub Copilot Agent Mode validation rejection of tools with array parameters missing items.
• Changed: fields response-shaping parameter now emitted as array of string with items schema for all tools and aliases.
• Compatibility: Non-breaking.

Release 2.2.2 — Polarion Document Resolution Corrective Patch

• Purpose: Fix VARCH-7102 document retrieval failures where document discovery succeeded but downstream document access failed.
• Changed: polarion.v2.resolveDocument now parses matching document payloads into deterministic top-level identifiers.
• Changed: Resolver output must expose projectId, spaceId, documentId, fullDocumentId, title, and confidence metadata when a single exact match is found.
• Changed: polarion.getDocument must use resolved spaceId + documentId instead of falling back to _default/null.
• Regression guard: Validate no _default/null, no project not found: null, and no double-encoded path segments such as %2520.
• VARCH-7102 test case: Resolve and retrieve VARCH-7102 Crop and Product Application Setup System Specification in project precisionTechnologyGENIII.
• Compatibility: Non-breaking patch; existing V1/V2 tool names and request shapes remain supported.

Release 2.2.1 — Project Identifier Alias and Startup Configuration Fixes

• Purpose: Improve project/document workflow reliability after MCP calls failed with missing or null project identifiers.
• Changed: Added support for projectIdentifier as an alias where tools previously expected only projectId or projectHint.
• Changed: Added safer validation to prevent unresolved document requests from constructing invalid Polarion paths.
• Changed: Corrected startup validation behavior around polarion.bearer-token / POLARION_BEARER_TOKEN so deployment configuration errors are explicit.
• Compatibility: Non-breaking; alias support is additive.

Release 2.2.0 — Enterprise Platform Capabilities

• Purpose: Add reusable MCP platform building blocks instead of one-off end-user workflows.
• Added: Canonical ID resolution, unified query/pagination contracts, cross-system normalization, traceability core APIs, document extraction primitives, error/clarification framework, session context utilities, resilience, security/audit, bulk operations, capability discovery/versioning, field introspection, search fallback, linking/sync primitives, and output shaping utilities.
• Namespace: New platform capabilities are exposed under mcp.platform.*.
• Compatibility: Existing V1 and V2 tools remain unchanged.

Release 2.1.x — Token-Optimized Response Shaping

• Purpose: Reduce oversized responses for Copilot/OpenAI and improve predictable output size.
• Changed: Default response view is summary; detailed and full are explicit opt-ins.
• Changed: Heavy fields such as comments, history, attachments, full link trees, raw custom field dumps, and large HTML descriptions are excluded by default.
• Compatibility: Field projection and enrichment toggles are additive.

Release 2.0 — Additive V2 Smart Tools

• Added: V2 smart resolution, session context, capability discovery, Polarion bundles, traceability bundles, smart search, and Jira issue bundles.
• Compatibility: V2 is opt-in and does not remove or rename V1 tools.

Release 1.x — Stable MCP API

• Provided: Stable JSON-RPC endpoint at POST /mcp/.
• Provided: Core MCP methods, initial Polarion/Jira tools, and strict Polarion workflow guardrails: project → document → work items.
• Compatibility: Existing V1 Jira and Polarion tool names remain supported.

1. Overview

The CNH Polarion–Jira MCP Server is an API gateway that allows AI agents to safely interact with Polarion and Jira through structured tools.

It is designed for AI assistants, Microsoft Copilot, or internal custom agents that need controlled access to engineering artifacts, work items, requirements, traceability data, test runs, and Jira issues.

2. Core Architecture

User → AI Agent / LLM → MCP Server → Polarion / Jira REST APIs

The user interacts with a chat interface. The AI agent interprets the request, selects the correct MCP tool, passes validated parameters, receives structured results, and formats the response for the user.

3. What MCP Provides

• Secure access to Polarion and Jira APIs.
• Tool-based API gateway for AI agents.
• Per-user access control using Polarion Personal Access Tokens.
• Workflow guardrails for project, document, and work-item retrieval.
• Structured JSON responses for final data and clarification cases.

4. Authentication

Every Polarion request must include a user-specific Polarion Personal Access Token. Jira credentials are passed per user only when a Jira tool is called.

Polarion Headers

Authorization: Bearer <USER_POLARION_PAT>
X-Polarion-PAT: <USER_POLARION_PAT>

If both Polarion headers are present, X-Polarion-PAT should take precedence.

Jira Headers for V1 and V2 Jira Tools

Jira headers are required only for Jira-related tools such as jira.getIssue, jira.searchIssues, jira.v2.searchSmart, and jira.v2.getIssueBundle.

X-Jira-User: <jira-user-email>
X-Jira-Token: <jira-api-token>

Alternative Jira Header

X-Jira-Auth: Basic base64(email:token)

5. Configuration Guide

Configuration has three parts: endpoint setup, tool registration, and runtime authentication.

MCP Endpoint

https://p2c.cnhind.com/mcp/

Basic JSON-RPC Request Shape

{
  "jsonrpc": "2.0",
  "id": "request-1",
  "method": "polarion.getDocumentWorkItems",
  "params": {
    "projectId": "precisionTechnologyGENIII",
    "spaceId": "VARCH-23 Job Data Flow and Field Sync",
    "documentId": "VARCH-23_Job_Data_Flow_and_Field_Sync_System_Specification"
  }
}

curl Test

curl -X POST "https://p2c.cnhind.com/mcp/" \
  -H "Authorization: Bearer <USER_POLARION_PAT>" \
  -H "X-Jira-User: user@example.com" \
  -H "X-Jira-Token: <JIRA_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "request-1",
    "method": "polarion.getDocumentWorkItems",
    "params": {
      "projectId": "precisionTechnologyGENIII",
      "spaceId": "VARCH-23 Job Data Flow and Field Sync",
      "documentId": "VARCH-23_Job_Data_Flow_and_Field_Sync_System_Specification"
    }
  }'

6. AI Agent Setup

An AI agent does not automatically know how to call this MCP server. You must expose MCP actions as tools and implement a middleware layer that forwards tool calls to the MCP JSON-RPC endpoint.

Recommended Flow

Example Tool Schema

{
  "name": "polarion_getDocumentWorkItems",
  "description": "Retrieve work items from a Polarion document after projectId, spaceId, and documentId are known.",
  "parameters": {
    "type": "object",
    "properties": {
      "projectId": { "type": "string" },
      "spaceId": { "type": "string" },
      "documentId": { "type": "string" },
      "fields": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Optional list of fields to return."
      }
    },
    "required": ["projectId", "spaceId", "documentId"]
  }
}

Required System Prompt

You are an AI agent that interacts with Polarion and Jira through MCP tools.

Rules:
1. Always resolve projectId first.
2. Search or list documents only inside the resolved project.
3. Resolve both spaceId and documentId before retrieving document work items.
4. Never guess project, space, document, or work-item identifiers.
5. Ask a clarification question when required identifiers are missing or ambiguous.
6. Return concise summaries to the user, but preserve IDs and important status fields.

7. Microsoft Copilot Setup

For Copilot Studio or enterprise Copilot scenarios, MCP should be exposed through a connector or plugin-style action layer.

Recommended Configuration

1. Create a custom connector in Copilot Studio or the enterprise integration platform.
2. Use the MCP OpenAPI descriptor if available: /mcp/openapi.yaml.
3. Configure authentication with an HTTP header.
4. Map high-value MCP methods as Copilot actions.
5. Add topic instructions that enforce workflow guardrails.

Authentication Header

Authorization: Bearer <USER_POLARION_PAT>

Suggested Copilot Actions

8. Custom Agent Setup

A custom agent gives the most control over authentication, logging, workflow enforcement, and response formatting.

Node.js MCP Client

import axios from "axios";

const MCP_ENDPOINT = "https://p2c.cnhind.com/mcp/";

export async function callMCP(method, params, userPat) {
  const response = await axios.post(
    MCP_ENDPOINT,
    {
      jsonrpc: "2.0",
      id: crypto.randomUUID(),
      method,
      params
    },
    {
      headers: {
        Authorization: `Bearer ${userPat}`,
        "Content-Type": "application/json"
      }
    }
  );

  return response.data;
}

Python MCP Client

import uuid
import requests

MCP_ENDPOINT = "https://p2c.cnhind.com/mcp/"

def call_mcp(method, params, user_pat):
    response = requests.post(
        MCP_ENDPOINT,
        json={
            "jsonrpc": "2.0",
            "id": str(uuid.uuid4()),
            "method": method,
            "params": params,
        },
        headers={
            "Authorization": f"Bearer {user_pat}",
            "Content-Type": "application/json",
        },
        timeout=60,
    )
    response.raise_for_status()
    return response.json()

Agent Tool Wrapper Example

const tools = [
  {
    name: "getDocumentWorkItems",
    description: "Get work items from a resolved Polarion document.",
    execute: async (args, context) => {
      return await callMCP(
        "polarion.getDocumentWorkItems",
        args,
        context.userPolarionPat
      );
    }
  }
];

9. Workflow Guardrails

The MCP workflow is intentionally strict to avoid ambiguous or incorrect document retrieval.

1. Resolve projectId first.
2. List or search documents only inside that project.
3. Resolve spaceId and documentId.
4. Retrieve document work items only after all three identifiers are known.
5. Return structured JSON for final data or clarification.

Clarification Response Example

{
  "status": "clarification_required",
  "clarificationRequired": true,
  "finalData": false,
  "stage": "document",
  "message": "Multiple matching documents were found. Please choose one."
}

10. End-to-End Examples

Example 1: Retrieve Work Items from a Polarion Document

User prompt:

Get id, title, type, status, and outline number for all work items in the VARCH-23 specification.

Agent sequence:

1. Call polarion.listProjects.
2. Resolve the intended project.
3. Call polarion.listDocuments in that project.
4. Resolve spaceId and documentId.
5. Call polarion.getDocumentWorkItems.
6. Summarize results for the user.

Example 2: Search Jira Bugs

User prompt:

Search Jira for open bugs assigned to me.

Agent sequence:

1. Call jira.searchIssues with an appropriate JQL query.
2. Return issue key, summary, status, priority, and assignee.

Example 3: Traceability

User prompt:

Show linked and backlinked work items for PTGENIII-12345.

Agent sequence:

1. Resolve the project if not already known.
2. Call polarion.getWorkItemTraceability or related linked-work-item tools.
3. Group results by relationship type.

11. Tool Catalog

12. Testing and Debugging

Use the following assets to validate configuration and troubleshoot integrations.

Debug Checklist

• Confirm the PAT is valid and belongs to the current user.
• Confirm the user has Polarion/Jira permissions for the requested project.
• Check whether project, space, and document identifiers are resolved exactly.
• Inspect JSON-RPC request and response payloads.
• Verify that the agent is not guessing identifiers.

13. Common Pitfalls

14. 10-Minute Quick Start

15. Final Summary

The CNH Polarion–Jira MCP Server provides a secure, structured tool gateway for AI agents. To make it usable, teams must configure an agent layer, register tools, attach per-user authentication, and enforce the required Polarion workflow.

Token-Optimized Response Shaping

Large Polarion and Jira tools now have a documented response-shaping contract for Copilot/OpenAI safety. The default view is summary; detailed and full are explicit opt-ins. Heavy fields such as comments, history, attachments, full link trees, raw custom field dumps, and large HTML descriptions are excluded by default.

Covered tools include polarion.getWorkItem, polarion.searchWorkItems, polarion.queryWorkItemsLucene, polarion.getDocumentWorkItems, polarion.v2.getWorkItemBundle, polarion.v2.searchSmart, jira.getIssue, jira.searchIssues, jira.v2.getIssueBundle, and jira.v2.searchSmart.

{
  "view": "summary",
  "fields": ["id", "title", "status", "assignee"],
  "includeComments": false,
  "includeHistory": false,
  "includeAttachments": false,
  "maxResponseTokens": 8000
}