API Reference

Complete reference for all available MCP tools in the Azure DevOps MCP Server.

Tool Categories

Core Azure DevOps Tools

list_projects

{
  "tool": "list_projects"
}

list_repositories

Lists all repositories in a specific project.

Parameters:

• projectName (required) - Name of the Azure DevOps project

Returns: Array of repository objects with:

• id - Repository unique identifier
• name - Repository name
• url - Repository URL
• defaultBranch - Default branch name
• size - Repository size in bytes

Example:

{
  "tool": "list_repositories",
  "parameters": {
    "projectName": "MyProject"
  }
}

list_repository_items

Lists files and folders in a repository path.

Parameters:

• projectName (required) - Name of the Azure DevOps project
• repositoryId (required) - Repository ID or name
• path (optional) - Path within repository (default: “/”)
• branch (optional) - Branch name (default: default branch)

Returns: Array of item objects with:

• objectId - Git object ID
• gitObjectType - Type (blob, tree, commit)
• path - Full path to the item
• isFolder - Boolean indicating if item is a folder
• size - File size in bytes (for files)

Example:

{
  "tool": "list_repository_items",
  "parameters": {
    "projectName": "MyProject",
    "repositoryId": "my-repo",
    "path": "/src",
    "branch": "main"
  }
}

get_file_content

Gets the content of a specific file from a repository.

Parameters:

• projectName (required) - Name of the Azure DevOps project
• repositoryId (required) - Repository ID or name
• path (required) - Path to the file
• branch (optional) - Branch name (default: default branch)

Returns: File content object with:

• content - File contents (text or base64 for binary)
• encoding - Content encoding
• path - File path
• size - File size in bytes

Example:

{
  "tool": "get_file_content",
  "parameters": {
    "projectName": "MyProject",
    "repositoryId": "my-repo",
    "path": "/README.md",
    "branch": "main"
  }
}

list_work_items

Lists work items in a specific project with optional filtering.

Parameters:

• projectName (required) - Name of the Azure DevOps project
• workItemType (optional) - Filter by work item type (Bug, Task, etc.)
• assignedTo (optional) - Filter by assignee
• state (optional) - Filter by state (Active, Closed, etc.)
• top (optional) - Maximum number of items to return (default: 50)

Returns: Array of work item objects with:

• id - Work item ID
• title - Work item title
• workItemType - Type (Bug, Task, User Story, etc.)
• state - Current state
• assignedTo - Assigned user
• createdDate - Creation date
• tags - Array of tags

Example:

{
  "tool": "list_work_items",
  "parameters": {
    "projectName": "MyProject",
    "workItemType": "Bug",
    "state": "Active",
    "top": 20
  }
}

get_work_item

Gets detailed information about a specific work item.

Parameters:

• projectName (required) - Name of the Azure DevOps project
• workItemId (required) - Work item ID

Returns: Detailed work item object with:

• id - Work item ID
• title - Work item title
• description - Full description/details
• workItemType - Type
• state - Current state
• assignedTo - Assigned user
• priority - Priority level
• severity - Severity (for bugs)
• tags - Array of tags
• relations - Related work items
• comments - Work item comments
• history - Change history

Example:

{
  "tool": "get_work_item",
  "parameters": {
    "projectName": "MyProject",
    "workItemId": 1234
  }
}

Safe Write Tools

Write operations that require explicit opt-in configuration

add_pull_request_comment

Adds a comment to a pull request.

Requirements:

• PullRequestComments must be enabled in configuration
• PAT token must have Code: Write permission

Parameters:

• projectName (required) - Name of the Azure DevOps project
• repositoryId (required) - Repository ID or name
• pullRequestId (required) - Pull request ID
• comment (required) - Comment text
• confirm (required) - Must be true to confirm the operation

Returns: Comment object with:

• id - Comment ID
• content - Comment content
• author - Comment author
• publishedDate - Publication date

Example:

{
  "tool": "add_pull_request_comment",
  "parameters": {
    "projectName": "MyProject",
    "repositoryId": "my-repo",
    "pullRequestId": 123,
    "comment": "LGTM! Great work on this feature.",
    "confirm": true
  }
}

create_draft_pull_request

Creates a draft pull request (not published until ready).

Requirements:

• CreateDraftPullRequest must be enabled in configuration
• PAT token must have Code: Write permission

Parameters:

• projectName (required) - Name of the Azure DevOps project
• repositoryId (required) - Repository ID or name
• sourceBranch (required) - Source branch name
• targetBranch (required) - Target branch name
• title (required) - Pull request title
• description (optional) - Pull request description
• confirm (required) - Must be true to confirm the operation

Returns: Pull request object with:

• pullRequestId - PR ID
• title - PR title
• status - PR status (draft)
• url - PR URL

Example:

{
  "tool": "create_draft_pull_request",
  "parameters": {
    "projectName": "MyProject",
    "repositoryId": "my-repo",
    "sourceBranch": "feature/new-component",
    "targetBranch": "main",
    "title": "Add new authentication component",
    "description": "This PR adds JWT authentication support",
    "confirm": true
  }
}

update_work_item_tags

Adds or removes tags from work items.

Requirements:

• UpdateWorkItemTags must be enabled in configuration
• PAT token must have Work Items: Write permission

Parameters:

• projectName (required) - Name of the Azure DevOps project
• workItemId (required) - Work item ID
• tagsToAdd (optional) - Array of tags to add
• tagsToRemove (optional) - Array of tags to remove
• confirm (required) - Must be true to confirm the operation

Returns: Updated work item with new tag list

Example:

{
  "tool": "update_work_item_tags",
  "parameters": {
    "projectName": "MyProject",
    "workItemId": 1234,
    "tagsToAdd": ["security", "urgent"],
    "tagsToRemove": ["low-priority"],
    "confirm": true
  }
}

Batch Tools

High-performance operations for bulk data retrieval

batch_get_work_items

Retrieves multiple work items efficiently in parallel.

Parameters:

• projectName (required) - Name of the Azure DevOps project
• workItemIds (required) - Array of work item IDs (max 200)

Returns: Array of work item objects with same structure as get_work_item

Example:

{
  "tool": "batch_get_work_items",
  "parameters": {
    "projectName": "MyProject",
    "workItemIds": [1234, 1235, 1236, 1237]
  }
}

batch_get_repositories

Gets multiple repository details in parallel.

Parameters:

• projectName (required) - Name of the Azure DevOps project
• repositoryIds (required) - Array of repository IDs or names (max 50)

Returns: Array of detailed repository objects

Example:

{
  "tool": "batch_get_repositories",
  "parameters": {
    "projectName": "MyProject",
    "repositoryIds": ["repo1", "repo2", "repo3"]
  }
}

Test Plan Tools

Test management operations for comprehensive test oversight

get_test_plans

Gets test plans for a specific Azure DevOps project.

Parameters:

• projectName (required) - Name of the Azure DevOps project

Returns: Array of test plan objects with:

• id - Test plan ID
• name - Test plan name
• state - Plan state (Active, Inactive)
• startDate - Plan start date
• endDate - Plan end date

Example:

{
  "tool": "get_test_plans",
  "parameters": {
    "projectName": "MyProject"
  }
}

get_test_plan

Gets detailed information about a specific test plan.

Parameters:

• projectName (required) - Name of the Azure DevOps project
• planId (required) - Test plan ID

Returns: Detailed test plan object with suites and configuration

Example:

{
  "tool": "get_test_plan",
  "parameters": {
    "projectName": "MyProject",
    "planId": 123
  }
}

get_test_suites

Gets test suites for a specific test plan.

Parameters:

• projectName (required) - Name of the Azure DevOps project
• planId (required) - Test plan ID

Returns: Array of test suite objects with test cases

Example:

{
  "tool": "get_test_suites",
  "parameters": {
    "projectName": "MyProject",
    "planId": 123
  }
}

get_test_runs

Gets test runs for a specific Azure DevOps project.

Parameters:

• projectName (required) - Name of the Azure DevOps project
• planId (optional) - Filter by test plan ID

Returns: Array of test run objects with execution details

Example:

{
  "tool": "get_test_runs",
  "parameters": {
    "projectName": "MyProject",
    "planId": 123
  }
}

get_test_run

Gets detailed information about a specific test run.

Parameters:

• projectName (required) - Name of the Azure DevOps project
• runId (required) - Test run ID

Returns: Detailed test run object with all test results

Example:

{
  "tool": "get_test_run",
  "parameters": {
    "projectName": "MyProject",
    "runId": 456
  }
}

get_test_results

Gets test results for a specific test run.

Parameters:

• projectName (required) - Name of the Azure DevOps project
• runId (required) - Test run ID

Returns: Array of test result objects with pass/fail status

Example:

{
  "tool": "get_test_results",
  "parameters": {
    "projectName": "MyProject",
    "runId": 456
  }
}

Performance Tools

System management and monitoring capabilities

get_performance_metrics

View operation timings, API call statistics, and cache performance.

Parameters: None

Returns: Performance metrics object with:

• operationTimings - Average response times by operation
• apiCallCounts - Number of API calls by endpoint
• cacheHitRates - Cache performance statistics
• memoryUsage - Current memory consumption
• systemMetrics - Overall system performance

Example:

{
  "tool": "get_performance_metrics"
}

get_cache_statistics

Detailed cache performance and hit rate statistics.

Parameters: None

Returns: Cache statistics object with:

• hitRate - Overall cache hit percentage
• missRate - Cache miss percentage
• evictionCount - Number of cache evictions
• totalRequests - Total cache requests
• memoryUsage - Cache memory consumption

Example:

{
  "tool": "get_cache_statistics"
}

clear_cache

Clear all cached data to force fresh API calls.

Parameters:

• confirm (required) - Must be true to confirm the operation

Returns: Confirmation message

Example:

{
  "tool": "clear_cache",
  "parameters": {
    "confirm": true
  }
}

Error Handling

All tools return standardized error responses:

{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Invalid personal access token",
    "details": {
      "operation": "list_projects",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  }
}

Common Error Codes

• AUTHENTICATION_FAILED - Invalid or expired PAT token
• AUTHORIZATION_DENIED - Insufficient permissions
• PROJECT_NOT_FOUND - Project does not exist or no access
• REPOSITORY_NOT_FOUND - Repository does not exist
• WORK_ITEM_NOT_FOUND - Work item does not exist
• OPERATION_NOT_ENABLED - Write operation not enabled in configuration
• CONFIRMATION_REQUIRED - Write operation requires confirm=true
• RATE_LIMIT_EXCEEDED - Too many API calls
• VALIDATION_ERROR - Invalid parameters

Rate Limiting

The server implements intelligent rate limiting:

• Default: 60 requests per minute, 1000 per hour
• Batch Operations: Count as single request regardless of item count
• Cached Results: Don’t count toward rate limits
• Circuit Breaker: Automatic fallback when Azure DevOps is overloaded

Caching Strategy

Intelligent caching improves performance:

• Project/Repository Metadata: 30 minutes
• Work Item Details: 15 minutes
• File Contents: 60 minutes
• Test Results: 5 minutes
• Performance Metrics: Real-time (no cache)

Cache can be cleared using the clear_cache tool when fresh data is needed.