Model Context Protocol (MCP)

Unizo offers an MCP server that integrates SCM platforms with any LLM provider supporting the MCP protocol. This enables your AI agent to perform repository operations across GitHub, GitLab, Bitbucket, and Azure DevOps via a single MCP server.

Supported Tools & Use Cases

The following tools are available in the SCM MCP Server:

Tool Name	Description
`scm_list_integrations`	Get integrations for a specific SCM service
`scm_list_organizations`	Browse SCM organizations with pagination
`scm_get_organization`	Retrieve detailed organization information
`scm_list_repositories`	Browse repositories within an organization
`scm_get_repository`	Retrieve comprehensive repository information
`scm_list_branches`	Browse branches within a repository
`scm_get_branch`	Retrieve detailed branch information
`scm_list_commits`	Browse commit history with pagination
`scm_get_commit`	Retrieve detailed commit information
`scm_list_pull_requests`	Browse pull requests with pagination
`scm_get_pull_request`	Retrieve detailed pull request information
`scm_create_pull_request`	Create a new pull request
`scm_update_pull_request`	Update an existing pull request

Tool Reference

Service Discovery Tools

scm_list_connectors

Get list of available SCM services

Parameters:

None

Returns:
List of available SCM services (e.g., GitHub, GitLab, Bitbucket, Azure DevOps)

Example Response:

[
  {"name": "github"},
  {"name": "gitlab"},
  {"name": "bitbucket"},
  {"name": "azure_devops"}
]

scm_list_integrations

Get integrations for a specific SCM service

Parameters:

connector (string, required): Name of the service (e.g., "github", "gitlab")

Returns: List of integrations available for the specified service

Example Response:

[
  {
    "id": "integration-123",
    "name": "Production GitHub"
  },
  {
    "id": "integration-456",
    "name": "Development GitLab"
  }
]

Organization Management Tools

scm_list_organizations

Browse SCM organizations with pagination

Parameters:

integration_id (string, optional): Unique identifier for the integration

Returns: Paginated list of organizations

Example Response:

{
  "status": "success",
  "message": "Found 3 organizations",
  "data": [
    {
      "id": "acme-inc",
      "type": "Organization",
      "description": "Acme Inc main organization",
      "login": "acme-inc",
      "url": "https://api.github.com/orgs/acme-inc",
      "twoFactorRequirementEnabled": true,
      "membersCanCreatePublicRepositories": false,
      "avatarUrl": "https://avatars.githubusercontent.com/u/123456",
      "createdAt": "2020-01-15T10:00:00Z",
      "updatedAt": "2024-11-01T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 3,
    "offset": 0,
    "limit": 20,
    "next": null,
    "previous": null
  }
}

scm_get_organization

Retrieve detailed organization information

Parameters:

organization_id (string, required): Unique identifier of the organization

Returns: Comprehensive organization information

Example Response:

{
  "status": "success",
  "message": "Retrieved organization: acme-inc",
  "data": {
    "id": "acme-inc",
    "type": "Organization",
    "description": "Acme Inc main organization for all development projects",
    "login": "acme-inc",
    "url": "https://api.github.com/orgs/acme-inc",
    "twoFactorRequirementEnabled": true,
    "membersCanCreatePublicRepositories": false,
    "avatarUrl": "https://avatars.githubusercontent.com/u/123456",
    "createdAt": "2020-01-15T10:00:00Z",
    "updatedAt": "2024-11-01T14:30:00Z"
  }
}

Repository Management Tools

scm_list_repositories

Browse repositories within an organization

Parameters:

organization_id (string, required): Unique identifier of the organization

Returns: Paginated list of repositories

Example Response:

{
  "status": "success",
  "message": "Found 15 repositories",
  "data": [
    {
      "id": "backend-api",
      "description": "Main backend API service",
      "fullName": "acme-inc/backend-api",
      "language": "Python",
      "download": {
        "url": "https://github.com/acme-inc/backend-api/archive/refs/heads/main.zip",
        "type": "ONE_STEP_DOWNLOAD"
      },
      "size": "25600000",
      "private": true,
      "archived": false,
      "organization": "acme-inc",
      "url": "https://api.github.com/repos/acme-inc/backend-api",
      "defaultBranch": "main",
      "createdAt": "2021-03-15T10:00:00Z",
      "updatedAt": "2024-11-05T09:30:00Z",
      "changeLog": {
        "createdDateTime": "2021-03-15T10:00:00Z",
        "lastUpdatedDateTime": "2024-11-05T09:30:00Z"
      }
    },
    {
      "id": "frontend-app",
      "description": "React-based frontend application",
      "fullName": "acme-inc/frontend-app",
      "language": "JavaScript",
      "download": {
        "url": "https://github.com/acme-inc/frontend-app/archive/refs/heads/main.zip",
        "type": "ONE_STEP_DOWNLOAD"
      },
      "size": "18400000",
      "private": true,
      "archived": false,
      "organization": "acme-inc",
      "url": "https://api.github.com/repos/acme-inc/frontend-app",
      "defaultBranch": "main",
      "createdAt": "2021-04-20T11:00:00Z",
      "updatedAt": "2024-11-04T16:45:00Z",
      "changeLog": {
        "createdDateTime": "2021-04-20T11:00:00Z",
        "lastUpdatedDateTime": "2024-11-04T16:45:00Z"
      }
    }
  ],
  "organization_id": "acme-inc"
}

scm_get_repository

Retrieve comprehensive repository information

Parameters:

organization_id (string, required): Unique identifier of the organization
repository_id (string, required): Unique identifier of the repository

Returns: Comprehensive repository information

Example Response:

{
  "status": "success",
  "message": "Retrieved repository: backend-api",
  "data": {
    "id": "backend-api",
    "description": "Main backend API service built with FastAPI and PostgreSQL",
    "fullName": "acme-inc/backend-api",
    "language": "Python",
    "download": {
      "url": "https://github.com/acme-inc/backend-api/archive/refs/heads/main.zip",
      "type": "ONE_STEP_DOWNLOAD"
    },
    "size": "25600000",
    "private": true,
    "archived": false,
    "organization": "acme-inc",
    "url": "https://api.github.com/repos/acme-inc/backend-api",
    "defaultBranch": "main",
    "createdAt": "2021-03-15T10:00:00Z",
    "updatedAt": "2024-11-05T09:30:00Z",
    "changeLog": {
      "createdDateTime": "2021-03-15T10:00:00Z",
      "lastUpdatedDateTime": "2024-11-05T09:30:00Z"
    }
  }
}

Branch Management Tools

scm_list_branches

Browse branches within a repository

Parameters:

organization_id (string, required): Unique identifier of the organization
repository_id (string, required): Unique identifier of the repository

Returns: Paginated list of branches

Example Response:

{
  "status": "success",
  "message": "Found 8 branches",
  "data": [
    {
      "name": "main",
      "sha": "a1b2c3d4e5f6789012345678901234567890abcd",
      "url": "https://api.github.com/repos/acme-inc/backend-api/commits/a1b2c3d",
      "download": {
        "url": "https://github.com/acme-inc/backend-api/archive/refs/heads/main.zip",
        "type": "ONE_STEP_DOWNLOAD"
      },
      "enabled": true,
      "authorName": "John Doe",
      "authorDate": "2024-11-05T09:30:00Z",
      "committerName": "John Doe",
      "committerDate": "2024-11-05T09:30:00Z"
    },
    {
      "name": "develop",
      "sha": "b2c3d4e5f678901234567890123456789012bcde",
      "url": "https://api.github.com/repos/acme-inc/backend-api/commits/b2c3d4e",
      "download": {
        "url": "https://github.com/acme-inc/backend-api/archive/refs/heads/develop.zip",
        "type": "ONE_STEP_DOWNLOAD"
      },
      "enabled": true,
      "authorName": "Jane Smith",
      "authorDate": "2024-11-04T16:20:00Z",
      "committerName": "Jane Smith",
      "committerDate": "2024-11-04T16:20:00Z"
    },
    {
      "name": "feature/user-authentication",
      "sha": "c3d4e5f67890123456789012345678901234cdef",
      "url": "https://api.github.com/repos/acme-inc/backend-api/commits/c3d4e5f",
      "download": {
        "url": "https://github.com/acme-inc/backend-api/archive/refs/heads/feature/user-authentication.zip",
        "type": "ONE_STEP_DOWNLOAD"
      },
      "enabled": true,
      "authorName": "Alice Johnson",
      "authorDate": "2024-11-03T14:15:00Z",
      "committerName": "Alice Johnson",
      "committerDate": "2024-11-03T14:15:00Z"
    }
  ],
  "organization_id": "acme-inc",
  "repository_id": "backend-api"
}

scm_get_branch

Retrieve detailed branch information

Parameters:

organization_id (string, required): Unique identifier of the organization
repository_id (string, required): Unique identifier of the repository
branch_id (string, required): Name of the branch

Returns: Comprehensive branch information

Example Response:

{
  "status": "success",
  "message": "Retrieved branch: main",
  "data": {
    "name": "main",
    "sha": "a1b2c3d4e5f6789012345678901234567890abcd",
    "url": "https://api.github.com/repos/acme-inc/backend-api/commits/a1b2c3d",
    "download": {
      "url": "https://github.com/acme-inc/backend-api/archive/refs/heads/main.zip",
      "type": "ONE_STEP_DOWNLOAD"
    },
    "enabled": true,
    "authorName": "John Doe",
    "authorDate": "2024-11-05T09:30:00Z",
    "committerName": "John Doe",
    "committerDate": "2024-11-05T09:30:00Z"
  }
}

Commit Management Tools

scm_list_commits

Browse commit history with pagination

Parameters:

organization_id (string, required): Unique identifier of the organization
repository_id (string, required): Unique identifier of the repository

Returns: Paginated list of commits

Example Response:

{
  "status": "success",
  "message": "Found 150 commits",
  "data": [
    {
      "id": "a1b2c3d4e5f6789012345678901234567890abcd",
      "url": "https://api.github.com/repos/acme-inc/backend-api/commits/a1b2c3d",
      "sha": "a1b2c3d4e5f6789012345678901234567890abcd",
      "author": "john.doe",
      "parents": [
        {
          "sha": "9876543210fedcba9876543210fedcba98765432",
          "url": "https://api.github.com/repos/acme-inc/backend-api/commits/9876543",
          "htmlUrl": "https://github.com/acme-inc/backend-api/commit/9876543"
        }
      ]
    },
    {
      "id": "b2c3d4e5f678901234567890123456789012bcde",
      "url": "https://api.github.com/repos/acme-inc/backend-api/commits/b2c3d4e",
      "sha": "b2c3d4e5f678901234567890123456789012bcde",
      "author": "jane.smith",
      "parents": [
        {
          "sha": "a1b2c3d4e5f6789012345678901234567890abcd",
          "url": "https://api.github.com/repos/acme-inc/backend-api/commits/a1b2c3d",
          "htmlUrl": "https://github.com/acme-inc/backend-api/commit/a1b2c3d"
        }
      ]
    }
  ],
  "organization_id": "acme-inc",
  "repository_id": "backend-api"
}

scm_get_commit

Retrieve detailed commit information

Parameters:

organization_id (string, required): Unique identifier of the organization
repository_id (string, required): Unique identifier of the repository
commit_id (string, required): Unique identifier (SHA) of the commit

Returns: Comprehensive commit information

Example Response:

{
  "status": "success",
  "message": "Retrieved commit: a1b2c3d4e5f6789012345678901234567890abcd",
  "data": {
    "id": "a1b2c3d4e5f6789012345678901234567890abcd",
    "url": "https://api.github.com/repos/acme-inc/backend-api/commits/a1b2c3d",
    "sha": "a1b2c3d4e5f6789012345678901234567890abcd",
    "author": "john.doe",
    "parents": [
      {
        "sha": "9876543210fedcba9876543210fedcba98765432",
        "url": "https://api.github.com/repos/acme-inc/backend-api/commits/9876543",
        "htmlUrl": "https://github.com/acme-inc/backend-api/commit/9876543"
      }
    ]
  }
}

Pull Request Management Tools

scm_list_pull_requests

Browse pull requests with pagination

Parameters:

organization_id (string, required): Unique identifier of the organization
repository_id (string, required): Unique identifier of the repository

Returns: Paginated list of pull requests

Example Response:

{
  "status": "success",
  "message": "Found 12 pull requests",
  "data": [
    {
      "id": "456",
      "name": "acme-inc/backend-api/pull/456",
      "title": "Add user authentication feature",
      "description": "Implements JWT-based authentication with refresh tokens",
      "state": "opened",
      "nodeId": "PR_kwDOABcD123",
      "htmlUrl": "https://github.com/acme-inc/backend-api/pull/456",
      "creator": "alice.johnson",
      "count": 15,
      "visibility": "private"
    },
    {
      "id": "455",
      "name": "acme-inc/backend-api/pull/455",
      "title": "Fix database connection pooling",
      "description": "Resolves connection timeout issues under high load",
      "state": "merged",
      "nodeId": "PR_kwDOABcD122",
      "htmlUrl": "https://github.com/acme-inc/backend-api/pull/455",
      "creator": "bob.wilson",
      "count": 8,
      "visibility": "private"
    },
    {
      "id": "454",
      "name": "acme-inc/backend-api/pull/454",
      "title": "Update API documentation",
      "description": "Adds OpenAPI specs for all endpoints",
      "state": "closed",
      "nodeId": "PR_kwDOABcD121",
      "htmlUrl": "https://github.com/acme-inc/backend-api/pull/454",
      "creator": "jane.smith",
      "count": 3,
      "visibility": "private"
    }
  ],
  "organization_id": "acme-inc",
  "repository_id": "backend-api"
}

scm_get_pull_request

Retrieve detailed pull request information

Parameters:

organization_id (string, required): Unique identifier of the organization
repository_id (string, required): Unique identifier of the repository
pull_request_id (string, required): Unique identifier of the pull request

Returns: Comprehensive pull request information

Example Response:

{
  "status": "success",
  "message": "Retrieved pull request: 456",
  "data": {
    "id": "456",
    "name": "acme-inc/backend-api/pull/456",
    "title": "Add user authentication feature",
    "description": "This PR implements JWT-based authentication with the following features:\n- Login/logout endpoints\n- Refresh token mechanism\n- Password reset functionality\n- Email verification\n\nCloses #234",
    "state": "opened",
    "nodeId": "PR_kwDOABcD123",
    "htmlUrl": "https://github.com/acme-inc/backend-api/pull/456",
    "creator": "alice.johnson",
    "count": 15,
    "visibility": "private"
  }
}

scm_create_pull_request

Create a new pull request

Parameters:

organization_id (string, required): Unique identifier of the organization
repository_id (string, required): Unique identifier of the repository
title (string, required): Title of the pull request
source (string, required): Source branch containing the changes
target (string, required): Target branch to merge changes into

Returns: Created pull request information

Example Response:

{
  "status": "success",
  "message": "Pull request created successfully: 457",
  "data": {
    "id": "457",
    "name": "acme-inc/backend-api/pull/457",
    "title": "Implement rate limiting middleware",
    "description": "Adds rate limiting to prevent API abuse",
    "state": "opened",
    "nodeId": "PR_kwDOABcD124",
    "htmlUrl": "https://github.com/acme-inc/backend-api/pull/457",
    "creator": "john.doe",
    "count": 5,
    "visibility": "private"
  }
}

scm_update_pull_request

Update an existing pull request

Parameters:

organization_id (string, required): Unique identifier of the organization
repository_id (string, required): Unique identifier of the repository
pull_request_id (string, required): Unique identifier of the pull request

Returns: Updated pull request information

Example Response:

{
  "status": "success",
  "message": "Pull request updated successfully: 456",
  "data": {
    "id": "456",
    "name": "acme-inc/backend-api/pull/456",
    "title": "Add user authentication feature (Updated)",
    "description": "Updated description with additional implementation details",
    "state": "opened",
    "nodeId": "PR_kwDOABcD123",
    "htmlUrl": "https://github.com/acme-inc/backend-api/pull/456",
    "creator": "alice.johnson",
    "count": 18,
    "visibility": "private"
  }
}

Installation

Prerequisites

A Unizo API key
An active SCM integration (GitHub, GitLab, Bitbucket, or Azure DevOps)
Node.js v20 or higher

MCP Configuration

Here is an example configuration for setting up the Unizo SCM MCP server:

{
  "mcpServers": {
    "unizo": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.unizo.ai/mcp",
        "--header",
        "apikey:${UNIZO_API_KEY}",
        "--header",
        "x-mcp-scopes:scm"
      ],
      "env": {
        "UNIZO_API_KEY": "your_api_key"
      }
    }
  }
}

Client Setup

For detailed setup instructions with specific AI clients:

Claude Desktop Setup

Environment Variables

The following environment variables are required:

UNIZO_API_KEY: Your Unizo API key

Error Handling

All tools return errors in a consistent format:

{
  "status": "error",
  "message": "Repository 'example/repo' not found",
  "traceback": "..."
}

Common Error Codes

INTEGRATION_NOT_FOUND: Invalid integration ID
ORGANIZATION_NOT_FOUND: Organization doesn't exist or no access
REPOSITORY_NOT_FOUND: Repository doesn't exist or no access
BRANCH_NOT_FOUND: Branch doesn't exist
COMMIT_NOT_FOUND: Commit doesn't exist
PULL_REQUEST_NOT_FOUND: Pull request doesn't exist
RATE_LIMIT_EXCEEDED: API rate limit reached
UNAUTHORIZED: Invalid credentials or permissions
INVALID_PARAMETER: Invalid parameter value
INVALID_STATE: Invalid pull request state value
INVALID_VISIBILITY: Invalid pull request visibility value

Supported Tools & Use Cases​

Tool Reference​

Service Discovery Tools​

scm_list_connectors​

scm_list_integrations​

Organization Management Tools​

scm_list_organizations​

scm_get_organization​

Repository Management Tools​

scm_list_repositories​

scm_get_repository​

Branch Management Tools​

scm_list_branches​

scm_get_branch​

Commit Management Tools​

scm_list_commits​

scm_get_commit​

Pull Request Management Tools​

scm_list_pull_requests​

scm_get_pull_request​

scm_create_pull_request​

scm_update_pull_request​

Installation​

Prerequisites​

MCP Configuration​

Client Setup​

Environment Variables​

Error Handling​

Common Error Codes​

Related Resources​

Supported Tools & Use Cases

Tool Reference

Service Discovery Tools

scm_list_connectors

scm_list_integrations

Organization Management Tools

scm_list_organizations

scm_get_organization

Repository Management Tools

scm_list_repositories

scm_get_repository

Branch Management Tools

scm_list_branches

scm_get_branch

Commit Management Tools

scm_list_commits

scm_get_commit

Pull Request Management Tools

scm_list_pull_requests

scm_get_pull_request

scm_create_pull_request

scm_update_pull_request

Installation

Prerequisites

MCP Configuration

Client Setup

Environment Variables

Error Handling

Common Error Codes

Related Resources