Add and Manage MCP Registry

[kodjomiles]

User description

Description

Added new guide for managing MCP Server Registry with governance and automation

Added docs pages

Please also include the path for the added docs

• Manage MCP Server Registry (/guides/all/manage-mcp-registry)

Updated docs pages

Please also include the path for the updated docs

• None

---

PR Type

Enhancement, Documentation

---

Description

• Add comprehensive guide for building centralized MCP server registry in Port

• Create two blueprints: MCP Registry and MCP Tool Specification for governance and discovery

• Implement self-service action for requesting new MCP servers with approval workflow

• Add Python script and GitHub workflow for automated MCP tool extraction and syncing

• Integrate AI agent capabilities for intelligent MCP server discovery and recommendations

---

Diagram Walkthrough

flowchart LR
  A["MCP Registry Blueprint"] --> B["Self-Service Action"]
  B --> C["Create MCP Server Entity"]
  C --> D["Pending Approval Status"]
  D --> E["Approved Status"]
  E --> F["MCP Tool Specification"]
  G["GitHub Workflow"] --> H["Extract MCP Tools Script"]
  H --> I["Connect to MCP Server"]
  I --> J["List Tools & Prompts"]
  J --> F
  F --> K["AI Agent Integration"]
  K --> L["Discovery & Recommendations"]

Loading

File Walkthrough

	Relevant files
Configuration changes	consts.js Add MCP Registry guide to guides navigation                            src/components/guides-section/consts.js Add new guide entry for "Manage MCP Server Registry" to available guides list Include description highlighting governance, discovery, and automated metadata extraction Set tags as AI, Actions, Automations, RBAC with AI and GitHub logos Link to new guide path /guides/all/manage-mcp-registry +8/-0
Documentation	manage-mcp-registry.md Add complete MCP registry management guide with automation docs/guides/all/manage-mcp-registry.md Create comprehensive 967-line guide for building MCP server registry in Port Define two blueprints: MCP Registry (for servers) and MCP Tool Specification (for tools with AI governance) Implement self-service action "Request New MCP Server" for creating entities with pending approval status Provide Python extraction script with Port API client, MCP connection, and secret management patterns Include GitHub workflow for automated weekly tool extraction and syncing from all MCP servers Document AI agent integration for intelligent discovery queries and tool recommendations Add sections for prerequisites, use cases, GitHub secrets setup, and verification steps +967/-0

---

[qodo-merge-pro]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Command injection Description: The extraction script executes MCP server commands constructed from blueprint data after replacing placeholder secrets with environment variables, which could allow command injection or accidental exposure if a malicious or unvalidated command is stored in the catalog. manage-mcp-registry.md [458-811] Referred Code """ MCP Tool Extractor for Port Automatically syncs tools from all MCP servers in Port catalog """ import asyncio import json import os import sys from typing import List, Dict, Any import httpx from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client class PortAPIClient: """Client for interacting with Port API""" def __init__(self, client_id: str, client_secret: str): self.client_id = client_id self.client_secret = client_secret self.base_url = "https://api.getport.io/v1" self.access_token = None ... (clipped 333 lines)
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No audit logs: The added Python script performs authentication and data mutations without emitting structured audit logs that capture user identity, action, and outcome. Referred Code """ MCP Tool Extractor for Port Automatically syncs tools from all MCP servers in Port catalog """ import asyncio import json import os import sys from typing import List, Dict, Any import httpx from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client class PortAPIClient: """Client for interacting with Port API""" def __init__(self, client_id: str, client_secret: str): self.client_id = client_id self.client_secret = client_secret self.base_url = "https://api.getport.io/v1" self.access_token = None ... (clipped 333 lines)
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Broad exceptions: The extractor catches broad exceptions and prints messages to stdout without structured context or retries, and returns empty results which may mask failures. Referred Code except Exception as e: print(f" ❌ Error extracting tools: {type(e).__name__}: {str(e)}") import traceback print(f" Stack trace:\n{traceback.format_exc()}") return [] async def main(): print("=" * 60) print("🚀 MCP Tool Extractor for Port") print("=" * 60) port_client_id = os.getenv("PORT_CLIENT_ID") port_client_secret = os.getenv("PORT_CLIENT_SECRET") if not port_client_id or not port_client_secret: print("❌ Missing required environment variables:") if not port_client_id: print(" - PORT_CLIENT_ID is not set") if not port_client_secret: print(" - PORT_CLIENT_SECRET is not set") sys.exit(1) ... (clipped 96 lines)
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Stack trace output: The script prints full exception details and stack traces to console which in CI logs could expose internal details. Referred Code except Exception as e: print(f" ❌ Error extracting tools: {type(e).__name__}: {str(e)}") import traceback print(f" Stack trace:\n{traceback.format_exc()}") return [] async def main(): print("=" * 60) print("🚀 MCP Tool Extractor for Port") print("=" * 60) port_client_id = os.getenv("PORT_CLIENT_ID") port_client_secret = os.getenv("PORT_CLIENT_SECRET") if not port_client_id or not port_client_secret: print("❌ Missing required environment variables:") if not port_client_id: print(" - PORT_CLIENT_ID is not set") if not port_client_secret: print(" - PORT_CLIENT_SECRET is not set") sys.exit(1) ... (clipped 96 lines)
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Potential secret echo: Logs print the command after secret replacement which risks exposing injected credentials if commands include them. Referred Code # Replace secret placeholders (YOUR__SECRET_NAME pattern) command_str_with_secrets = replace_secret_placeholders(command_str) print(f" 🔐 Command after secret replacement: {command_str_with_secrets[:100]}..." if len(command_str_with_secrets) > 100 else f" 🔐 Command after secret replacement: {command_str_with_secrets}")
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Command injection risk: The script parses and executes an arbitrary command from entity properties without validation or allowlisting, which could be dangerous in CI. Referred Code for idx, server in enumerate(mcp_servers, 1): print(f"\n[{idx}/{len(mcp_servers)}] Processing MCP Server") print("-" * 60) server_id = server.get("identifier") server_title = server.get("title", server_id) command = server.get("properties", {}).get("command") print(f" 📦 Server: {server_title}") print(f" 🆔 Identifier: {server_id}") print(f" 💻 Command: {command or 'Not specified'}") if not command: print(f" ⏭️ Skipping: no command specified") servers_skipped += 1 continue # Extract tools from this MCP server try: tools = await extract_tools_from_mcp(command) ... (clipped 3 lines)
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Decouple automation from secret management Refactor the automation to fetch secrets from a secure store within Port at runtime, instead of requiring users to manually edit the GitHub workflow file for each new secret. This improves scalability and reduces maintenance. Examples: docs/guides/all/manage-mcp-registry.md [862-869] env: # Port API credentials (required) PORT_CLIENT_ID: ${{ secrets.PORT_CLIENT_ID }} PORT_CLIENT_SECRET: ${{ secrets.PORT_CLIENT_SECRET }} # Add secrets for your MCP servers here (matching YOUR__* placeholders in commands) # Example: If command uses YOUR__GITHUB_TOKEN, add: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | python scripts/extract_mcp_tools.py docs/guides/all/manage-mcp-registry.md [879-889] :::warning Important: Managing MCP server credentials For each MCP server that requires credentials, you must: 1. **Add secrets to GitHub**: Store actual credential values in GitHub Secrets. 2. **Update workflow env section**: Add the secret to the `env` block of the workflow. Example: `PORT_CLIENT_ID: ${{ secrets.PORT_CLIENT_ID }}` 3. **Use placeholder in command**: Reference using one of these patterns: - Example: `--client-id <YOUR_PORT_CLIENT_ID>` or `--client-id YOUR__PORT_CLIENT_ID` **Limitation**: GitHub Actions requires secrets to be explicitly defined in the workflow file. You cannot dynamically pass all secrets, so each MCP server's credentials must be manually added to the workflow's `env` section. ... (clipped 1 lines) Solution Walkthrough: Before: # .github/workflows/extract_mcp_tools.yml jobs: sync-all-mcp-tools: env: PORT_CLIENT_ID: ${{ secrets.PORT_CLIENT_ID }} # Each new secret must be manually added here NEW_SERVER_API_KEY: ${{ secrets.NEW_SERVER_API_KEY }} run: | python scripts/extract_mcp_tools.py # scripts/extract_mcp_tools.py def replace_secret_placeholders(command_str): # ... finds placeholder like YOUR__NEW_SERVER_API_KEY secret_name = "NEW_SERVER_API_KEY" secret_value = os.getenv(secret_name) # Reads from env var # ... replaces placeholder in command return command_str After: # .github/workflows/extract_mcp_tools.yml jobs: sync-all-mcp-tools: env: # Only Port credentials are needed in the workflow PORT_CLIENT_ID: ${{ secrets.PORT_CLIENT_ID }} PORT_CLIENT_SECRET: ${{ secrets.PORT_CLIENT_SECRET }} run: | python scripts/extract_mcp_tools.py # scripts/extract_mcp_tools.py def replace_secret_placeholders(command_str, port_client): # ... finds placeholder like YOUR__NEW_SERVER_API_KEY secret_name = "NEW_SERVER_API_KEY" # Fetches the secret directly from Port's secret store at runtime secret_value = port_client.get_secret(secret_name) # ... replaces placeholder in command return command_str Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a critical architectural flaw in the secret management strategy, which severely limits the scalability and maintainability of the proposed automation.	High
best practice	Improve secret replacement logic Refactor the secret replacement logic to use re.sub with a replacer function, preventing potential cascading replacement bugs and improving robustness. docs/guides/all/manage-mcp-registry.md [600-636] def replace_secret_placeholders(command_str: str) -> str: """Replace YOUR__SECRET_NAME placeholders with actual environment variable values Supports two patterns: 1. YOUR__SECRET_NAME -> replaces with os.getenv("SECRET_NAME") 2. <YOUR_SECRET_NAME> -> replaces with os.getenv("SECRET_NAME") Example: Command: "uvx server --key YOUR__API_KEY" Replaces YOUR__API_KEY with value from os.getenv("API_KEY") """ import re - # Pattern 1: YOUR__SECRET_NAME (double underscore) - pattern1 = r'YOUR__([A-Z_]+)' - matches1 = re.findall(pattern1, command_str) + # Combined pattern for both placeholder types + pattern = r'YOUR__([A-Z_]+)|<YOUR_([A-Z_]+)>' - # Pattern 2: <YOUR_SECRET_NAME> (angle brackets, single underscore) - pattern2 = r'<YOUR_([A-Z_]+)>' - matches2 = re.findall(pattern2, command_str) + def replacer(match): + # The secret name is in group 1 or 2, depending on which pattern matched + secret_name = match.group(1) or match.group(2) + secret_value = os.getenv(secret_name) + + if secret_value: + print(f" ✅ Replaced placeholder for {secret_name} environment variable") + return secret_value + else: + print(f" ⚠️ Warning: Environment variable {secret_name} not found. Placeholder '{match.group(0)}' not replaced.") + return match.group(0) # Return the original placeholder if secret not found - all_matches = list(set(matches1 + matches2)) - - if all_matches: - print(f" 🔑 Found secret placeholders: {all_matches}") - - for secret_name in all_matches: - secret_value = os.getenv(secret_name) - if secret_value: - # Replace both patterns - command_str = command_str.replace(f"YOUR__{secret_name}", secret_value) - command_str = command_str.replace(f"<YOUR_{secret_name}>", secret_value) - print(f" ✅ Replaced placeholder with {secret_name} environment variable") - else: - print(f" ⚠️ Warning: Environment variable {secret_name} not found") - - return command_str + return re.sub(pattern, replacer, command_str) Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a potential bug in the string replacement logic and proposes a more robust solution using re.sub to prevent incorrect cascading substitutions.	Medium
Organization best practice	Standardize details and image alt text Use lowercase "(click to expand)" in details summaries and add alt text; also include descriptive alt text for images. docs/guides/all/manage-mcp-registry.md [14-178] -<summary><b>MCP Registry blueprint (Click to expand)</b></summary> +<summary><b>MCP Registry blueprint (click to expand)</b></summary> ... -<summary><b>MCP Tool Specification blueprint (Click to expand)</b></summary> +<summary><b>MCP Tool Specification blueprint (click to expand)</b></summary> ... -<img src="/img/guides/MCPRegistryOverview.png" width="100%" border="1px" /> +<img src="/img/guides/MCPRegistryOverview.png" width="100%" border="1px" alt="Overview diagram of the MCP server registry in Port" /> [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 6 __ Why: Relevant best practice - Pattern 1 and 13: Standardize collapsible details titles with "(click to expand)" and format images with full path, width, border, and alt text.	Low
	Fix heading and list casing Use sentence case for headings and add periods at the end of list items for consistency. Also use sentence case in bolded list topic labels. docs/guides/all/manage-mcp-registry.md [9-28] -# Manage MCP Server Registry +# Manage MCP server registry ## Common use cases -1. **MCP Server Discovery** - Enable developers to find approved MCP servers available for their team. +1. **MCP server discovery** - Enable developers to find approved MCP servers available for their team. +2. **Tool-specific recommendations** - Help developers discover which MCP servers support specific capabilities (e.g., Java development, database operations). +3. **Installation guidance** - Provide clear setup instructions and configuration documentation for approved MCP servers. +4. **Governance enforcement** - Track and control which MCP servers are allowed organization-wide with approval workflows. +5. **Internal MCP management** - Catalog and distribute internally-built MCP servers to development teams. -2. **Tool-Specific Recommendations** - Help developers discover which MCP servers support specific capabilities (e.g., Java development, database operations). - -3. **Installation Guidance** - Provide clear setup instructions and configuration documentation for approved MCP servers. - -4. **Governance Enforcement** - Track and control which MCP servers are allowed organization-wide with approval workflows. - -5. **Internal MCP Management** - Catalog and distribute internally-built MCP servers to development teams. - Apply / Chat Suggestion importance[1-10]: 5 __ Why: Relevant best practice - Pattern 2: Use sentence case for headers and end list items with periods.	Low
Enhancement	Refactor identifier generation and attribute access Refactor the tool identifier generation to use re.sub() for more robust character replacement and use getattr() for more idiomatic attribute access with a default value. docs/guides/all/manage-mcp-registry.md [676-687] +import re for tool in tools_result.tools: - tool_identifier = f"{tool.name.lower().replace(' ', '_').replace('-', '_')}" + tool_identifier = re.sub(r'[^a-zA-Z0-9_]+', '_', tool.name.lower()) print(f" - {tool.name} (ID: {tool_identifier})") tools_data.append({ "identifier": tool_identifier, "title": tool.name, "properties": { "name": tool.name, "description": tool.description or "", - "parameters": tool.inputSchema if hasattr(tool, 'inputSchema') else {} + "parameters": getattr(tool, 'inputSchema', {}) } }) Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion improves code style by using the more Pythonic getattr and enhances robustness by using a regular expression for identifier generation.	Low
Performance	Combine pip install commands Combine the two pip install commands into a single command to improve the efficiency of the dependency installation step. docs/guides/all/manage-mcp-registry.md [856-859] - name: Install dependencies - run: | - pip install mcp httpx - pip install uv # Install uv which provides uvx + run: pip install mcp httpx uv Apply / Chat Suggestion importance[1-10]: 3 __ Why: The suggestion correctly points out that combining the pip install commands is more efficient and is a good practice for GitHub Actions workflows.	Low
Maintainability	Simplify repetitive print statement logic Simplify the print statement for the command string by pre-calculating the truncated string to avoid repetition and improve readability. docs/guides/all/manage-mcp-registry.md [645] -print(f" 🔐 Command after secret replacement: {command_str_with_secrets[:100]}..." if len(command_str_with_secrets) > 100 else f" 🔐 Command after secret replacement: {command_str_with_secrets}") +truncated_command = (command_str_with_secrets[:100] + '...') if len(command_str_with_secrets) > 100 else command_str_with_secrets +print(f" 🔐 Command after secret replacement: {truncated_command}") Apply / Chat Suggestion importance[1-10]: 2 __ Why: This is a minor but valid suggestion that improves code readability and maintainability by removing repetition in the print statement.	Low
Update

[aws-amplify-eu-west-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2981.d2ngvl90zqbob8.amplifyapp.com

[Matanga1-2]

@kodjomiles lets move the script just to port-experimental including the .yaml and we're goo to go

[hadar-co]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Map array inputs as strings in MCP server action

The self‑service action maps the labels input with quotes ("labels": "{{ .inputs.labels }}"). Because labels is defined as an array in the MCP Registry blueprint, quoting the template expression serializes the array to a string (e.g., "[\"db\"]") and the UPSERT request will either fail validation or store the values as a single string rather than an array. Drop the surrounding quotes so the template inserts the JSON array directly.

Useful? React with 👍 / 👎.