Skip to main content

MCP Server Integration

Pidima provides a Model Context Protocol (MCP) server that enables AI assistants like Claude, Cursor, GPT, and other LLM-based tools to interact directly with your Pidima instance. This allows AI assistants to manage requirements, test cases, architecture, and more through natural language conversations.

What is MCP?​

The Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect to external data sources and tools. By implementing an MCP server, Pidima allows AI assistants to:

  • Query and search requirements, test cases, and documents
  • Create and update engineering artifacts programmatically
  • Leverage AI features like test generation and requirement analysis
  • Maintain context across complex engineering workflows

Quick Start​

Step 1: Create an API Key​

API keys are long-lived credentials that don't expire (unless you set an expiration). This is the recommended approach for MCP integrations.

  1. Log in to Pidima
  2. Go to Settings → API Keys
  3. Click Create API Key
  4. Give it a descriptive name (e.g., "Cursor MCP Integration")
  5. Copy the key immediately — it won't be shown again!

Or use the API:

# Get a temporary token
TOKEN=$(curl -s -X POST "https://your-pidima-host/api/v1.0/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"your-email@example.com","password":"your-password"}' | jq -r '.token')

# Create an API key
curl -X POST "https://your-pidima-host/api/v1.0/api-keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MCP Integration Key",
    "expiresInDays": null
  }'

Response:

{
  "apiKey": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "MCP Integration Key",
    "keyPrefix": "pdk_a1b2c3d4",
    "createdAt": "2026-07-31T10:00:00Z"
  },
  "key": "pdk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
}
Save Your API Key

The full API key is only shown once. Save it immediately — it cannot be retrieved later.

Step 2: Configure Your AI Client​

Cursor IDE​

  1. Open Cursor Settings (Cmd+, on Mac, Ctrl+, on Windows/Linux)
  2. Search for "MCP" or navigate to Features → MCP Servers
  3. Click Add MCP Server or edit ~/.cursor/mcp.json directly:
{
  "mcpServers": {
    "pidima": {
      "url": "https://your-pidima-host/mcp",
      "transport": "streamable-http",
      "headers": {
        "X-API-Key": "pdk_your_api_key_here"
      }
    }
  }
}
  1. Restart Cursor to load the configuration
  2. Open the MCP panel to verify connection

Configuration file locations:

  • macOS: ~/.cursor/mcp.json
  • Linux: ~/.cursor/mcp.json
  • Windows: %USERPROFILE%\.cursor\mcp.json

Claude Desktop​

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/config.json Linux: ~/.config/claude/config.json Windows: %APPDATA%\Claude\config.json

{
  "mcpServers": {
    "pidima": {
      "url": "https://your-pidima-host/mcp",
      "transport": "streamable-http",
      "headers": {
        "X-API-Key": "pdk_your_api_key_here"
      }
    }
  }
}

Step 3: Verify Connection​

Test the connection by listing available tools:

curl -X POST "https://your-pidima-host/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream, application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
Accept Header

The MCP endpoint requires Accept: text/event-stream, application/json header for proper response handling.

API Key Management​

Create API Key​

POST /api/v1.0/api-keys
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "name": "My Integration Key",
  "expiresInDays": 365  // Optional: null for no expiration
}

List API Keys​

GET /api/v1.0/api-keys
Authorization: Bearer <jwt-token>

Revoke API Key​

POST /api/v1.0/api-keys/{id}/revoke
Authorization: Bearer <jwt-token>

Delete API Key​

DELETE /api/v1.0/api-keys/{id}
Authorization: Bearer <jwt-token>

Available Tools (92 total)​

The Pidima MCP server exposes 92 tools for comprehensive platform access:

Project Management (6 tools)​

ToolDescription
list_projectsLists all projects accessible to the authenticated user
get_projectGet detailed information about a specific project including all its requirement levels
get_project_overviewGet a comprehensive project overview including project details, requirement levels, and statistics
create_projectCreate a new project in an account
update_projectUpdate an existing project
delete_projectDelete a project
list_project_levelsList all requirement levels in a project

Requirements Management (10 tools)​

ToolDescription
list_requirementsList requirements for a project with pagination and filtering
get_requirementGet a single requirement by its ID, including links to test cases
create_requirementCreate a new requirement
update_requirementUpdate an existing requirement
delete_requirementDelete a requirement
approve_requirementApprove a requirement, changing its status to APPROVED
reject_requirementReject a requirement, changing its status to REJECTED
search_requirementsSearch requirements by query text using semantic embedding search
get_requirement_status_distributionGet requirement status distribution for a project
refine_requirementRefine requirements using AI

Test Case Management (8 tools)​

ToolDescription
list_testcasesList test cases for a project with pagination
get_testcaseGet detailed information about a specific test case
create_testcaseCreate a new test case
update_testcaseUpdate an existing test case
delete_testcaseDelete a test case
mark_testcase_syncedMark a test case as synced (ready for use)
get_testcase_status_distributionGet test case status distribution for a project

Architecture Management (5 tools)​

ToolDescription
list_architecturesList all architecture diagrams for a project
get_architectureGet detailed information about a specific architecture diagram
create_architectureCreate a new architecture diagram with PlantUML code
delete_architectureDelete an architecture diagram
get_architectures_by_requirementGet architectures linked to a specific requirement

Traceability (5 tools)​

ToolDescription
create_trace_linkCreate traceability links between a requirement and test cases
get_traceabilityGet traceability links for a requirement
get_traceability_matrixGet the traceability matrix showing links between requirements and test cases
get_traceability_coverageGet traceability coverage statistics for a project level

AI Generation (6 tools)​

ToolDescription
generate_requirementsGenerate requirements using AI from project documents
generate_testcasesGenerate test cases using AI for requirements in a project
generate_architectureGenerate architecture diagram using AI based on requirements
generate_ai_linksGenerate AI-powered link suggestions between requirements and test cases
approve_ai_linksApprove and persist AI-generated link suggestions
analyze_requirementsAnalyze requirements using AI

Gap Analysis (8 tools)​

ToolDescription
create_gap_analysisStart a comprehensive gap analysis job for a project level
run_gap_analysisRun gap analysis for a project level
get_gap_analysis_jobGet the status and details of a gap analysis job
get_gap_analysis_issuesGet issues found by a gap analysis job
get_gap_analysis_metricsGet computed metrics and scores for a gap analysis job
get_latest_gap_analysisGet the latest gap analysis for a project level
resolve_gap_issueResolve a gap analysis issue using AI
get_resolution_previewGet a resolution preview for conflict/duplicate issues
get_link_suggestionsGet AI-powered link suggestions for resolving orphan issues

Compliance (5 tools)​

ToolDescription
analyze_complianceStart compliance analysis for requirements against regulatory documents
get_compliance_resultsGet the latest compliance analysis results for a requirement
resolve_compliance_issueGet AI suggestion to resolve a compliance clause conflict
apply_compliance_suggestionApply a saved AI compliance suggestion to update the requirement
mark_compliance_resolvedMark a compliance issue as resolved without changing the requirement

Impact Analysis (5 tools)​

ToolDescription
run_impact_analysisRun impact analysis for a requirement change
trigger_impact_analysisTrigger smart impact analysis for a requirement change
get_impact_reportsGet impact analysis report summaries for a project
get_impact_reportGet detailed impact analysis report by ID
get_impacted_artifactsGet impacted artifacts from an impact analysis report

Search (5 tools)​

ToolDescription
search_requirementsSearch requirements by query text within a project
search_requirements_semanticSemantic search for requirements only
search_testcases_semanticSemantic search for test cases only
search_documents_semanticSemantic search for RAG documents only
unified_searchUnified semantic search across all artifact types

Import (5 tools)​

ToolDescription
import_requirementImport a single requirement from external data
import_requirements_batchImport multiple requirements in batch
import_testcaseImport a single test case from external data
import_testcases_batchImport multiple test cases in batch
import_architectureImport a single architecture diagram

ReqIF Import/Export (7 tools)​

ToolDescription
export_requirements_reqifExport requirements to ReqIF format. Creates an async job. Parameters: projectId (required), levelId (optional), packaging (REQIF or REQIFZ), includeRelations (optional)
export_testcases_reqifExport test cases to ReqIF format. Creates an async job with same parameters as requirements export
get_reqif_job_statusGet the status of a ReqIF import/export job including progress, messages, and download availability
get_reqif_job_itemsGet preview items from a ReqIF import job awaiting confirmation. Supports pagination and filtering by action (CREATE, UPDATE, SKIP, ERROR)
confirm_reqif_importConfirm and commit a ReqIF import job. Supports conflict strategies: UPDATE_EXISTING, SKIP_EXISTING, CREATE_NEW
cancel_reqif_importCancel a ReqIF import job that is awaiting confirmation. Discards all preview items
download_reqif_artifactDownload the artifact from a completed ReqIF export job. Returns base64-encoded file content

ALM Tickets (9 tools)​

ToolDescription
create_ticketCreate a new ALM ticket (BUG, TASK, STORY, EPIC, FEATURE, IMPROVEMENT, SUBTASK). Requires linking to a requirement or test case
get_ticketGet a ticket by ID with full details including Pidima links and relationships
get_ticket_by_keyGet a ticket by its display key (e.g., PROJ-CT-00045)
update_ticketUpdate ticket fields (title, description, priority, assignee, sprint, story points)
change_ticket_statusTransition a ticket's status (OPEN, IN_PROGRESS, IN_REVIEW, BLOCKED, DONE, CLOSED, CANCELLED)
delete_ticketDelete a ticket (requires PROJECT_MANAGER role or higher)
list_ticketsList tickets for a project with filtering by level, status, type, assignee, sprint, and search query
search_ticketsAdvanced ticket search with multiple filter criteria (comma-separated statuses, types, assignees)
get_ticket_boardGet Kanban board view with tickets grouped by status columns

Analytics & Jobs (3 tools)​

ToolDescription
get_job_statusGet the status of an async job by its ID
get_project_statsGet project statistics including requirement and test case counts

Review Workflow (7 tools)​

ToolDescription
submit_for_reviewSubmit an item (requirement, testcase, or architecture) for review. Requires item type, item ID, and reviewer IDs
submit_review_decisionMake a review decision (APPROVED, REJECTED, or CHANGES_REQUESTED) on an item under review
get_current_reviewGet the current active review request for an item, including reviewer assignments and status
get_review_historyGet the complete review history for an item, showing all submissions, decisions, and status changes
get_eligible_reviewersGet a list of users who can review an item (project members excluding the submitter)
get_review_queueGet the pending review queue for the current user, showing items awaiting their review decision
bulk_submit_for_reviewSubmit multiple items for review in a single operation. Returns success/skip status for each item

Tool Usage Examples​

List Projects​

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {}
  }
}

Search Requirements​

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_requirements",
    "arguments": {
      "projectId": "your-project-uuid",
      "query": "safety critical requirements",
      "limit": 10
    }
  }
}

Create Requirement​

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_requirement",
    "arguments": {
      "projectId": "your-project-uuid",
      "levelId": "your-level-uuid",
      "name": "REQ-001",
      "description": "The system shall provide user authentication via OAuth 2.0",
      "type": "FUNCTIONAL",
      "priority": "HIGH"
    }
  }
}

Generate Test Cases with AI​

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "generate_testcases",
    "arguments": {
      "projectId": "your-project-uuid",
      "levelId": "your-level-uuid"
    }
  }
}

Run Gap Analysis​

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "run_gap_analysis",
    "arguments": {
      "projectId": "your-project-uuid",
      "levelId": "your-level-uuid"
    }
  }
}

Submit for Review​

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "submit_for_review",
    "arguments": {
      "itemType": "requirements",
      "itemId": "your-requirement-uuid",
      "reviewerIds": "reviewer-uuid-1,reviewer-uuid-2",
      "comment": "Ready for review - implemented all feedback from previous cycle"
    }
  }
}

Make Review Decision​

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "submit_review_decision",
    "arguments": {
      "itemType": "requirements",
      "itemId": "your-requirement-uuid",
      "decision": "APPROVED",
      "comment": "Meets all acceptance criteria"
    }
  }
}

Get Review Queue​

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "get_review_queue",
    "arguments": {
      "itemType": "requirements"
    }
  }
}

Export Requirements to ReqIF​

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "export_requirements_reqif",
    "arguments": {
      "projectId": "your-project-uuid",
      "levelId": "your-level-uuid",
      "packaging": "REQIFZ",
      "includeRelations": true
    }
  }
}

Response:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Export job started. Poll get_reqif_job_status to check progress."
}

Check ReqIF Job Status​

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "get_reqif_job_status",
    "arguments": {
      "jobId": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Response:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "operation": "EXPORT",
  "entityType": "REQUIREMENT",
  "progressPercentage": 100,
  "currentStep": "Completed",
  "canDownload": true,
  "artifactName": "requirements-export-2026-07-31.reqifz"
}

Create a Ticket​

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "create_ticket",
    "arguments": {
      "projectId": "your-project-uuid",
      "title": "Implement OAuth 2.0 authentication",
      "description": "Add support for OAuth 2.0 authentication flow as per REQ-AUTH-001",
      "ticketType": "TASK",
      "priority": "HIGH",
      "linkedRequirementId": "requirement-uuid"
    }
  }
}

Response:

{
  "id": "ticket-uuid",
  "ticketKey": "PROJ-CT-00001",
  "title": "Implement OAuth 2.0 authentication",
  "ticketType": "TASK",
  "status": "OPEN",
  "priority": "HIGH"
}

List Tickets with Filtering​

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "list_tickets",
    "arguments": {
      "projectId": "your-project-uuid",
      "status": "IN_PROGRESS",
      "ticketType": "BUG",
      "page": 0,
      "size": 20
    }
  }
}

Get Ticket Board (Kanban View)​

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "get_ticket_board",
    "arguments": {
      "projectId": "your-project-uuid",
      "sprintId": "sprint-uuid"
    }
  }
}

Response:

{
  "projectId": "your-project-uuid",
  "sprintId": "sprint-uuid",
  "columns": {
    "OPEN": [{"id": "...", "ticketKey": "PROJ-CT-00001", "title": "..."}],
    "IN_PROGRESS": [{"id": "...", "ticketKey": "PROJ-CT-00002", "title": "..."}],
    "DONE": []
  },
  "columnTotals": {"OPEN": 5, "IN_PROGRESS": 3, "DONE": 12}
}

Endpoints​

EndpointMethodDescription
/mcp/loginPOSTAuthenticate and obtain bearer token
/mcpPOSTMCP protocol endpoint (JSON-RPC 2.0)
/mcp-healthGETHealth check endpoint
/api/v1.0/api-keysPOSTCreate a new API key
/api/v1.0/api-keysGETList all API keys
/api/v1.0/api-keys/{id}/revokePOSTRevoke an API key
/api/v1.0/api-keys/{id}DELETEDelete an API key

Authentication Methods​

API keys are long-lived credentials perfect for MCP integrations:

{
  "headers": {
    "X-API-Key": "pdk_your_api_key_here"
  }
}

Bearer Token​

Bearer tokens expire after 24 hours. Use for testing or short-term access:

# Get token
curl -X POST "https://your-pidima-host/mcp/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"your-email@example.com","password":"your-password"}'
{
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN_HERE"
  }
}

Custom Integration​

For custom integrations, implement an MCP client that:

  1. Connects to the Pidima MCP endpoint via HTTP
  2. Sends JSON-RPC 2.0 messages
  3. Includes the appropriate authentication header
import requests
import json

class PidimaMCPClient:
    def __init__(self, base_url: str, api_key: str):
        self.url = f"{base_url}/mcp"
        self.headers = {
            "Content-Type": "application/json",
            "Accept": "text/event-stream, application/json",
            "X-API-Key": api_key
        }
        self.request_id = 0
    
    def call_tool(self, tool_name: str, arguments: dict) -> dict:
        self.request_id += 1
        payload = {
            "jsonrpc": "2.0",
            "id": self.request_id,
            "method": "tools/call",
            "params": {
                "name": tool_name,
                "arguments": arguments
            }
        }
        response = requests.post(self.url, headers=self.headers, json=payload)
        return response.json()

# Usage
client = PidimaMCPClient("https://your-pidima-host", "pdk_your_api_key")
projects = client.call_tool("list_projects", {})
print(projects)

Error Handling​

The MCP server returns standard JSON-RPC 2.0 error responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid request",
    "data": "Additional error details"
  }
}

Common Error Codes​

CodeMeaningResolution
-32700Parse errorCheck JSON syntax
-32600Invalid requestVerify request structure
-32601Method not foundCheck method name spelling
-32602Invalid paramsVerify parameter types and required fields
-32603Internal errorContact support if persistent
401UnauthorizedAPI key invalid or expired—re-authenticate
403ForbiddenUser lacks permission for this operation
404Not foundResource ID does not exist

Security Best Practices​

  1. Never hardcode API keys in source control
  2. Use environment variables for key storage
  3. Rotate keys regularly for production integrations
  4. Use separate keys for different environments (dev, staging, prod)
  5. Limit key scope by using service accounts with minimal permissions
# Store API key in environment variable
export PIDIMA_API_KEY="pdk_your_api_key_here"

Health Check​

Monitor MCP server availability:

curl "https://your-pidima-host/mcp-health"

Response:

{
  "status": "healthy",
  "timestamp": "2026-07-31T10:00:00Z",
  "version": "1.0.0"
}

Troubleshooting​

Connection Issues​

  1. Verify the endpoint URL is correct and accessible
  2. Check the Accept header — must include text/event-stream, application/json
  3. Check firewall rules allow outbound HTTPS connections
  4. Confirm the API key is valid and not revoked

Authentication Failures​

  1. Verify API key starts with pdk_ prefix
  2. Check key status in Settings → API Keys
  3. Create a new key if the current one may be compromised

Tool Execution Errors​

  1. Review parameter requirements for the tool
  2. Confirm resource IDs exist and are accessible
  3. Check user permissions for the requested operation

Cursor-Specific Issues​

  1. Restart Cursor after changing mcp.json
  2. Check file permissions on the config file
  3. Verify JSON syntax — use a JSON validator
  4. Check Cursor logs for MCP connection errors