Port MCP Interface Server

The implementation described herein serves as a Model Context Protocol (MCP) server proxy, specifically engineered to interface with the Port IO ecosystem. This allows for the deployment of sophisticated automation routines and natural language command execution across developer and autonomous agent workflows.

Capabilities Unlocked via Port MCP Interface

Rapid Data Acquisition

• Entity Property Retrieval - "What personnel manages asset X?"
• Availability Check - "Identify the currently assigned on-call engineer."
• Catalog Metrics - "Determine the aggregate count of active services residing in the production environment."

Scorecard Evaluation & Diagnosis

• Deficiency Identification - "Pinpoint the root causes for services failing to meet the 'Gold' service level agreement."
• Regulatory Adherence Status - "List all operational units that do not satisfy mandated security prerequisites."
• Quality Improvement Path - "What remedial actions are necessary to advance to the next defined scorecard tier?"

Asset Configuration

• Scorecard Definition - "Provision a new evaluation framework named 'Security Posture' featuring tiers: Basic, Silver, and Gold."
• Rule Establishment - "Institute a prerequisite rule demanding service ownership for attainment of the Silver threshold."
• Quality Gate Deployment - "Construct a validation mechanism to confirm the presence of requisite documentation for all services."

Access Control Management (RBAC)

• Privilege Inspection - "Retrieve the established permission matrix for this specific operational function."
• Policy Modification - "Configure the approval pipeline governing the deployment functionality."
• Decentralized Access Setup - "Implement team-centric authorization parameters for this designated action."

We are perpetually augmenting the functionality set of the Port MCP Gateway. Encountering a feature gap or having suggestions? Please contribute your ideas on our official roadmap portal!

Deployment Instructions

Prerequisites for Operation

Before initialization, ensure the following prerequisites are met:

1. Port Account Provisioning:
2. If unestablished, register at Port.io

3. Complete the account registration process.

4. Credential Acquisition:

5. Navigate to your Port administrative dashboard.
6. Access Configuration > Credentials section.

7. Securely record both the Client Identifier and the corresponding Client Secret.

8. Runtime Environment Requirements:

9. Either the Docker containerization platform must be installed on the host machine,
10. OR the uvx dependency manager must be available.

[!NOTE] You must also specify the designated Port operational region, which is either 'EU' or 'US'. If this is omitted, the system defaults to the 'EU' region.

Installation Modalities

The Port MCP Interface Server supports deployment via two primary avenues:

Package Deployment (using uvx)

Leverage the officially published Port MCP server package integrated with uvx for streamlined setup and dependency handling.

Step-by-Step Setup Guide

1. Establish a Python Isolated Environment (Strongly advised) bash python -m venv venv

2. Activate the Isolated Environment ```bash # For Unix-like systems: source venv/bin/activate

# For Windows: venv\Scripts\activate ```

1. Install the UV Package Manager Utility ```bash # Via Homebrew (Linux/macOS): brew install uv

# Or via pip: pip install uv ```

1. Validate UV Installation bash which uv

2. Configure Essential Environment Variables bash export PORT_CLIENT_ID="your_port_client_id" export PORT_CLIENT_SECRET="your_port_client_secret" export PORT_REGION="EU" # Specify "US" if required

3. Set Python Search Path (Only needed when operating within a virtual environment) bash export PYTHONPATH="/path/to/your/venv/bin/python"

4. Initiate the MCP Server Process bash uvx mcp-server-port --client-id your_port_client_id --client-secret your_port_client_secret --region EU --log-level DEBUG

5. Confirm Server Operational Status Monitor the console output for server initialization messages. Alternatively, review the dedicated log file: bash cat /tmp/port-mcp.log

Containerized Deployment (Docker)

Utilize the official container image provided by the registry:

docker pull ghcr.io/port-labs/port-mcp-server:latest

Detailed integration instructions for various MCP clients follow below.

Supplementary Configuration Directives

Advanced configuration can be managed by supplying the subsequent arguments:

Configuration Item	UVX Command Flag	Docker Environment Variable	Purpose	Default Setting
Verbosity Level	log-level	PORT_LOG_LEVEL	Governs the detail level of output logging	ERROR
API Schema Check	api-validation-enabled	PORT_API_VALIDATION_ENABLED	Enables/disables validation against the API schema; disables on failure	False

Integration with Claude Desktop

1. Navigate to Settings, select Developer, and choose "Edit config".
2. Modify the claude_desktop_config.json file, inserting the configuration snippet corresponding to your chosen installation method.
3. Save the file and trigger a restart of the Claude application.
4. In any new dialogue session, check the available Tools section to confirm Port integration.

Docker Setup Snippet

[!TIP] For robust operation, supply the fully qualified path to the Docker executable (e.g., /usr/local/bin/docker) rather than relying solely on the docker command alias. This mitigates potential environment PATH resolution inconsistencies.

{
  "mcpServers": {
    "port": {
      "command": "docker",
      "args": [
               "run",
                "-i",
                "--rm",
                "-e",
                "PORT_CLIENT_ID",
                "-e",
                "PORT_CLIENT_SECRET",
                "-e",
                "PORT_REGION",
                "-e",
                "PORT_LOG_LEVEL",
                "ghcr.io/port-labs/port-mcp-server:latest"
              ],
              "env": {
                "PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
                "PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
                "PORT_REGION": "<PORT_REGION>",
                "PORT_LOG_LEVEL": "<PORT_LOG_LEVEL>"
              }
    }
  }
}

uvx Setup Snippet

[!NOTE] Should you execute the command from within an active Python virtual environment, incorporate a PYTHONPATH entry into the env object, referencing the environment's binary path (e.g., /path/to/your/venv/bin/python).

{
  "mcpServers": {
    "Port": {
          "command": "uvx",
          "args": [
              "mcp-server-port@0.2.8",
              "--client-id",
              "<PORT_CLIENT_ID>",
              "--client-secret",
              "<PORT_CLIENT_SECRET>",
              "--region",
              "<PORT_REGION>"
          ],
          "env": {
              "PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
              "PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
              "PORT_REGION": "<PORT_REGION>",
              "PYTHONPATH": "/Users/matangrady/.venv-port-mcp/bin/python"
          }
      }
  }
}

Integration with Cursor IDE

1. Access Cursor Settings via the main menu and navigate to Cursor Settings.
2. Select the MCP tab and choose the option to "Add new global MCP server".
3. Manually edit the mcp.json configuration file, inserting the relevant setup block below based on your deployment mechanism.
4. Persist the changes and return to the Cursor Settings panel.
5. The newly configured Port server and its toolkit should now be visible and accessible.

Docker Configuration for Cursor

[!TIP] For robust operation, supply the fully qualified path to the Docker executable (e.g., /usr/local/bin/docker) rather than relying solely on the docker command alias. This mitigates potential environment PATH resolution inconsistencies.

{
  "mcpServers": {
    "port": {
      "command": "docker",
      "args": [
               "run",
                "-i",
                "--rm",
                "-e",
                "PORT_CLIENT_ID",
                "-e",
                "PORT_CLIENT_SECRET",
                "-e",
                "PORT_REGION",
                "-e",
                "PORT_LOG_LEVEL",
                "ghcr.io/port-labs/port-mcp-server:latest"
              ],
              "env": {
                "PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
                "PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
                "PORT_REGION": "<PORT_REGION>",
                "PORT_LOG_LEVEL": "<PORT_LOG_LEVEL>"
              }
    }
  }
}

uvx Configuration for Cursor

[!NOTE] Should you execute the command from within an active Python virtual environment, incorporate a PYTHONPATH entry into the env object, referencing the environment's binary path (e.g., /path/to/your/venv/bin/python).

{
  "mcpServers": {
    "Port": {
          "command": "uvx",
          "args": [
              "mcp-server-port@0.2.8",
              "--client-id",
              "<PORT_CLIENT_ID>",
              "--client-secret",
              "<PORT_CLIENT_SECRET>",
              "--region",
              "<PORT_REGION>"
          ],
          "env": {
              "PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
              "PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
              "PORT_REGION": "<PORT_REGION>",
              "PYTHONPATH": "/Users/matangrady/.venv-port-mcp/bin/python"
          }
      }
  }
}

Integration with VS Code

[!TIP] VS Code possesses native capability to discover and utilize MCP servers already configured within Cursor installations.

[!NOTE] For rapid deployment, leverage the provided single-click installation hyperlinks, specifying the desired configuration destination. Remember to substitute all bracketed placeholders with your proprietary Port authentication details.

Docker Express Setup uvx Express Setup

Follow these manual configuration steps:

1. Access the Command Palette: Cmd + Shift + P (macOS) or Ctrl + Shift + P (Windows/Linux).
2. Input Preferences: Open User Settings (JSON) and execute.
3. Update the settings.json file by appending the server definition under the mcp > servers structure.
4. Save the file. Activate Agent mode in Copilot and confirm the Port toolkit's availability by interacting with it.

Docker Configuration for VS Code (settings.json)

[!TIP] For robust operation, supply the fully qualified path to the Docker executable (e.g., /usr/local/bin/docker) rather than relying solely on the docker command alias. This mitigates potential environment PATH resolution inconsistencies.

  "Port": {
      "type": "stdio",
      "command": "docker",
      "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "PORT_CLIENT_ID",
          "-e",
          "PORT_CLIENT_SECRET",
          "-e",
          "PORT_REGION",
          "ghcr.io/port-labs/port-mcp-server:latest"
      ],
      "env": {
          "PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
          "PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
          "PORT_REGION": "<PORT_REGION>"
      }
  }

uvx Configuration for VS Code (settings.json)

[!NOTE] Should you execute the command from within an active Python virtual environment, incorporate a PYTHONPATH entry into the env object, referencing the environment's binary path (e.g., /path/to/your/venv/bin/python).

  "Port": {
      "type": "stdio",
      "command": "uvx",
      "args": [
          "mcp-server-port@0.2.8",
          "--client-id",
          "<PORT_CLIENT_ID>",
          "--client-secret",
          "<PORT_CLIENT_SECRET>",
          "--region",
          "<PORT_REGION>"
      ],
      "env": {
          "PORT_CLIENT_ID": "<PORT_CLIENT_ID>",
          "PORT_CLIENT_SECRET": "<PORT_CLIENT_SECRET>",
          "PORT_REGION": "<PORT_REGION>"
      }
  }

Utilization within Neovim (mcphub.nvim)

To integrate the Port MCP Gateway with Neovim, deploy the mcphub.nvim plugin alongside a compatible LLM interface plugin, such as Avante or CodeCompanion.

Once plugin installation is complete, configure the Port server connection:

1. Invoke the server configuration interface using the command :MCPHub and navigate to the 'Config' view, or directly open the configuration file, typically situated at ~/.config/mcphub/servers.json.
2. Inject the Port MCP server definition beneath the mcpServers top-level key (refer to schemas below).
3. Commit the configuration changes.
4. Ensure that the environment variables PORT_CLIENT_ID and PORT_CLIENT_SECRET are actively set within the Neovim runtime context.
5. Refresh the server processes by executing :MCPHub and then initiating a restart via the 'R' command within that view.
6. The server status should reflect as active in the MCPHub dashboard. Verification can be performed by invoking the @mcp utility within your LLM client. For instance, query: @mcp list my blueprints.

Refer to the mcphub.nvim documentation for comprehensive usage guidance.

Docker Configuration Schema for mcphub.nvim

[!NOTE] Confirmation is required that PORT_CLIENT_ID and PORT_CLIENT_SECRET environment variables hold your valid Port access credentials.

{
    "mcpServers": {
        "port": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "PORT_CLIENT_ID",
                "-e",
                "PORT_CLIENT_SECRET",
                "-e",
                "PORT_REGION",
                "ghcr.io/port-labs/port-mcp-server:latest"
            ],
            "env": {
                "PORT_REGION": "EU",
                "PORT_CLIENT_ID": "",
                "PORT_CLIENT_SECRET": ""
            }
        }
    }
}

uvx Configuration Schema for mcphub.nvim

[!NOTE] Confirmation is required that PORT_CLIENT_ID and PORT_CLIENT_SECRET environment variables hold your valid Port access credentials.

{
    "mcpServers": {
        "port": {
            "command": "uvx",
            "args": [
                "mcp-server-port@0.2.8",
                "--client-id",
                "PORT_CLIENT_ID",
                "--client-secret",
                "PORT_CLIENT_SECRET",
                "--region",
                "PORT_REGION"
            ],
            "env": {
                "PORT_CLIENT_ID": "",
                "PORT_CLIENT_SECRET": "",
                "PORT_REGION": "EU"
            }
        }
    }
}

Catalogue of Accessible Operations

Blueprint Management Operations

1. get_blueprints
2. Purpose: Fetch the complete register of blueprints defined within the Port instance.
3. Optional Parameters:
   • detailed (Boolean, default: false): Request the full schema definition for each blueprint.

4. Output: A structured text representation enumerating all blueprints.

5. get_blueprint

6. Purpose: Obtain configuration data for a blueprint identified by its unique key.
7. Required Parameters:
   • blueprint_identifier (String): The specific key designating the desired blueprint.

8. Optional Parameters:

   • detailed (Boolean, default: true): Include comprehensive schema specifications.

9. create_blueprint

10. Purpose: Introduce a novel blueprint structure into Port.
11. Required Parameters:
    • Must supply all necessary schema components: identifier, title, property definitions, etc.

12. Output: The newly instantiated blueprint object.

13. update_blueprint

14. Purpose: Modify parameters of an extant blueprint.
15. Required Parameters:
    • identifier (String): The key identifying the blueprint targeted for modification.
    • Data payload containing fields to be altered.

16. Output: The resulting, modified blueprint object.

17. delete_blueprint

18. Purpose: Erase a specified blueprint from the registry.
19. Required Parameters:
    • blueprint_identifier (String): The key of the blueprint to be removed.
20. Output: Confirmation status of the deletion.

Entity Instance Operations

1. get_entities
2. Purpose: Retrieve all instances associated with a particular blueprint type.
3. Required Parameters:
   • blueprint_identifier (String): The type identifier under which entities are indexed.

4. Optional Parameters:

   • detailed (Boolean, default: false): Fetch complete entity records, including all property values.

5. get_entity

6. Purpose: Extract data for a singular entity instance.
7. Required Parameters:
   • blueprint_identifier (String): The blueprint type hosting the entity.
   • entity_identifier (String): The unique ID of the specific entity.

8. Optional Parameters:

   • detailed (Boolean, default: true): Return the entity with all associated property data.

9. create_entity

10. Purpose: Instantiate a new entity instance under a designated blueprint.

11. Required Parameters:

    • blueprint_identifier (String): The target blueprint for instantiation.
    • entity (Object): The data structure conforming to the blueprint's schema.

12. update_entity

13. Purpose: Modify the state or properties of an existing entity.

14. Required Parameters:

    • blueprint_identifier (String): The blueprint type.
    • entity_identifier (String): The entity ID to be modified.
    • entity (Object): The revised data payload for the entity.

15. delete_entity

16. Purpose: Remove an entity instance.
17. Required Parameters:
    • blueprint_identifier (String): The blueprint type.
    • entity_identifier (String): The entity ID targeted for deletion.
18. Optional Parameters:
    • delete_dependents (Boolean, default: false): Flag to cascade deletion to dependent entities.

Scorecard Assessment Operations

1. get_scorecards
2. Purpose: List all defined service scorecards.

3. Optional Parameters:

   • detailed (Boolean, default: false): Return comprehensive details for each scorecard.

4. get_scorecard

5. Purpose: Fetch the structure and rules for a specific scorecard.

6. Required Parameters:

   • scorecard_id (String): The unique ID of the scorecard.
   • blueprint_id (String, optional): The associated blueprint identifier.

7. create_scorecard

8. Purpose: Institute a new service evaluation rubric tied to a blueprint.
9. Required Parameters:
   • blueprint_id (String): Identifier of the blueprint the scorecard will measure.
   • identifier (String): Unique ID for the new scorecard.
   • title (String): Human-readable name for the scorecard.
   • levels (List): Array defining the distinct achievement tiers.

10. Optional Parameters:

    • rules (List): Collection of criteria used for level calculation.
    • description (String): Explanatory text for the scorecard.

11. update_scorecard

12. Purpose: Apply modifications to an existing scorecard definition.
13. Required Parameters:
    • blueprint_identifier (String): The blueprint scope.
    • scorecard_identifier (String): The ID of the scorecard being revised.
    • Data payload specifying updates (title, levels, rules, etc.).

14. Output: The finalized, updated scorecard object.

15. delete_scorecard

16. Purpose: Decommission a scorecard record.
17. Required Parameters:
    • blueprint_identifier (String): The blueprint scope.
    • scorecard_identifier (String): The ID of the scorecard to remove.
18. Output: Operation success confirmation.

AI Agent Interaction Operation

1. invoke_ai_agent
2. Purpose: Dispatch a query or command to a pre-configured Port AI agent.
3. Required Parameters:
   • prompt (String): The directive text submitted to the agent.
4. Output: The execution status and the agent's resulting message.

Local Development & Testing Environment

To facilitate local iteration and feature validation prior to formal release, MCP clients (like Cursor) can be directed to utilize your locally cloned source code repository.

Initial Setup

1. Source Code Cloning: Secure a local copy of the port-mcp-server repository.
2. Environment Bootstrapping:
   • Navigate to the root directory of the cloned repository.
   • Execute make install. This script is designed to establish an isolated Python environment (venv) and populate it with all required dependencies.
   • Confirm that the virtual environment directory (typically named .venv) has been successfully generated within the repository structure.

Configuration Example for Local Hookup

The subsequent JSON structure illustrates how to point your client to the local server instance. Substitute the generic paths below with the precise filesystem locations on your host machine.

Crucial Notes:

• The command directive must specify the Python interpreter located inside your local repository's virtual environment.
• The PYTHONPATH environment variable in the env section must point to the top-level directory of your cloned repository.

{
  "mcpServers": {
    "port_local": {
      "command": "/path/to/your/port-mcp-server/.venv/bin/python", // Substitute with the actual venv Python executable path
      "args": [
        "-m",
        "src",
        "--client-id",
        "<YOUR_PORT_CLIENT_ID>",
        "--client-secret",
        "<YOUR_PORT_CLIENT_SECRET>",
        "--region",
        "<YOUR_PORT_REGION>", // e.g., EU or US
        "--log-level",
        "DEBUG" // Adjust log verbosity as needed
      ],
      "env": {
        "PORT_CLIENT_ID": "<YOUR_PORT_CLIENT_ID>",
        "PORT_CLIENT_SECRET": "<YOUR_PORT_CLIENT_SECRET>",
        "PORT_REGION": "<YOUR_PORT_REGION>",
        "PORT_LOG_LEVEL": "DEBUG",
        "PYTHONPATH": "/path/to/your/port-mcp-server" // Substitute with the actual repository root path
      }
    }
  }
}

Upon successful configuration, your MCP client will route requests through your locally running server instance, enabling real-time testing of modifications committed to your current development branch.

Feedback Channel and Development Timeline

We actively solicit user input regarding feature requirements and potential enhancements for the Port MCP Gateway. Direct your suggestions and feedback via our dedicated ideas board.

Troubleshooting Common Issues

Should authentication failures manifest during operation, systematically verify the following:

1. Confirmation that the supplied Port credentials within the command-line arguments are accurate.
2. Verification that the execution context possesses the necessary authorization scope.
3. Double-check that credentials have been correctly transposed into the client configuration files.

Software Licensing

This MCP server component is distributed under the permissive MIT License. This grants broad freedoms to utilize, adapt, and disseminate the software, contingent upon adherence to the stipulations outlined in the MIT License.

WIKIPEDIA CONTEXT: Business administration utilities encompass all systems, applications, control mechanisms, computational frameworks, and methodologies employed by enterprises to navigate shifting market dynamics, maintain competitive standing, and elevate overall corporate efficacy. There exists a departmental functional classification for these tools—covering areas like resource planning, workflow management, record-keeping, human resources administration, decision support, and performance monitoring. Modern administrative software has undergone rapid technological transformation over the past decade, driven by the persistent imperative to lower operational expenditure and maximize revenue, alongside a deep commitment to understanding consumer requirements and delivering tailored product solutions. Consequently, executive leadership must adopt a strategic stance toward selecting and tailoring these tools to organizational specifics, rather than passively adopting the newest available solution. In 2013, Bain & Company research indicated global usage patterns favoring tools like Strategic Planning, CRM, Benchmarking, and Balanced Scorecards. Business applications (software collections for specific organizational tasks) have evolved from basic MIS to complex, cloud-based ERP suites, where successful value addition hinges on effective implementation and precise tool selection matching organizational needs.