diff --git a/docs/guides/all/manage-mcp-registry.md b/docs/guides/all/manage-mcp-registry.md new file mode 100644 index 0000000000..bc4915d29a --- /dev/null +++ b/docs/guides/all/manage-mcp-registry.md @@ -0,0 +1,616 @@ +--- +displayed_sidebar: null +description: Learn how to build and manage a centralized MCP server registry in Port for governance, discovery, and team collaboration +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Manage MCP Server Registry + +This guide demonstrates how to build a centralized MCP (Model Context Protocol) server registry using Port, enabling your organization to govern, discover, and share approved MCP servers across development teams. + + + +## Common use cases + +This guide addresses five key use cases for MCP server management: + +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. + +## Prerequisites + +This guide assumes you have: + +- A Port account and have completed the [onboarding process](/getting-started/overview). + +- A GitHub account and repository (optional, required only for the automated metadata extraction section). + +- [AI agents feature enabled](/ai-interfaces/ai-agents/overview#access-to-the-feature) in your Port account (optional, required only for AI-powered discovery). + + +## Set up data model + +We'll create a blueprint to represent MCP registry in your organization's catalog, tracking their approval status, capabilities, and metadata. + +

Create MCP registry blueprint

+ +1. Go to the [builder](https://app.getport.io/settings/data-model) page of your portal. + +2. Click on `+ Blueprint`. + +3. Click on the `{...} Edit JSON` button. + +4. Copy and paste the following JSON configuration: + +
+ MCP Registry blueprint (Click to expand) + + ```json showLineNumbers + { + "identifier": "mcpRegistry", + "title": "MCP Registry", + "icon": "Microservice", + "schema": { + "properties": { + "type": { + "title": "Server Type", + "type": "string", + "enum": ["internal", "external"], + "enumColors": { + "internal": "blue", + "external": "purple" + }, + "description": "Whether this is an internally-built or external third-party MCP server" + }, + "status": { + "title": "Approval Status", + "type": "string", + "enum": ["approved", "pending", "rejected"], + "enumColors": { + "approved": "green", + "pending": "yellow", + "rejected": "red" + }, + "description": "Current approval status for organizational use" + }, + "description": { + "title": "Description", + "type": "string", + "format": "markdown", + "description": "What this MCP server does and when to use it" + }, + "labels": { + "title": "Labels", + "type": "array", + "items": { + "type": "string" + }, + "description": "Tags representing server labels (e.g., java, database, testing)" + }, + "installation_instructions": { + "title": "Installation Instructions", + "type": "string", + "format": "markdown", + "description": "Step-by-step installation and setup instructions for this MCP server" + }, + "repository_url": { + "title": "Repository URL", + "type": "string", + "format": "url", + "description": "Source code repository location" + }, + "endpoint": { + "title": "Endpoint", + "type": "string", + "description": "Endpoint URL for the MCP server (if applicable)" + }, + "command": { + "title": "Command", + "type": "string", + "description": "Command to run the MCP server (e.g., 'npx -y @modelcontextprotocol/server-filesystem')" + }, + "tools": { + "title": "Available Tools", + "type": "array", + "items": { + "type": "string" + }, + "description": "List of MCP tools provided by this server" + }, + "prompts": { + "title": "Available Prompts", + "type": "array", + "items": { + "type": "string" + }, + "description": "List of MCP prompts provided by this server" + } + }, + "required": ["type", "status", "description"] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "owningTeam": { + "title": "Owning Team", + "target": "_team", + "required": false, + "many": false + }, + "requestedBy": { + "title": "Requested By", + "target": "_user", + "required": false, + "many": false + } + } + } + ``` + +
+ +5. Click `Create` to save the blueprint. + +

Create MCP Tool Specification blueprint

+ +Create an MCP Tool Specification blueprint to catalog individual tools provided by MCP servers with governance metadata. This blueprint works with the GitHub Workflow ingestion method to automatically extract and track tools. + +1. Go to the [builder](https://app.getport.io/settings/data-model) page of your portal. + +2. Click on `+ Blueprint`. + +3. Click on the `{...} Edit JSON` button. + +4. Copy and paste the following JSON configuration: + +
+ MCP Tool Specification blueprint (Click to expand) + + ```json showLineNumbers + { + "identifier": "mcpToolSpecification", + "title": "MCP Tool Specification", + "icon": "Microservice", + "description": "Details of an MCP Tool Specification with AI Governance metadata", + "schema": { + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the MCP tool" + }, + "description": { + "type": "string", + "title": "Description", + "description": "Description of what the tool does" + }, + "parameters": { + "type": "object", + "title": "Parameters", + "description": "Tool parameters and their descriptions" + }, + "ai_category": { + "type": "string", + "title": "AI Category", + "icon": "AI", + "description": "The AI category this tool belongs to", + "enum": [ + "generative_ai", + "ml_prediction", + "nlp", + "computer_vision", + "recommendation", + "data_processing", + "automation", + "other" + ], + "enumColors": { + "generative_ai": "purple", + "ml_prediction": "blue", + "nlp": "green", + "computer_vision": "orange", + "recommendation": "pink", + "data_processing": "turquoise", + "automation": "yellow", + "other": "lightGray" + } + }, + "risk_classification": { + "type": "string", + "title": "Risk Classification", + "icon": "Alert", + "description": "Risk level associated with this tool", + "enum": ["low", "medium", "high", "critical"], + "enumColors": { + "low": "green", + "medium": "yellow", + "high": "orange", + "critical": "red" + } + }, + "data_access_level": { + "type": "string", + "title": "Data Access Level", + "icon": "Lock", + "description": "Level of data access this tool requires", + "enum": ["none", "read_only", "read_write", "admin"], + "enumColors": { + "none": "green", + "read_only": "yellow", + "read_write": "orange", + "admin": "red" + } + }, + "last_governance_review": { + "type": "string", + "title": "Last Governance Review", + "format": "date-time", + "icon": "AuditLog", + "description": "When this tool was last reviewed for governance compliance" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "mcpServer": { + "title": "MCP Server", + "target": "mcpRegistry", + "required": false, + "many": false + } + } + } + ``` + +
+ +5. Click `Create` to save the blueprint. + + +## Ingest MCP server using a self-service action + +Now that we have our data model setup, let's explore how to populate MCP servers using a self-service action. + + +1. Go to the [self-service](https://app.getport.io/self-serve) page of your portal. + +2. Click on `+ New Action`. + +3. Click on the `{...} Edit JSON` button. + +4. Copy and paste the following JSON configuration: + +
+ Request MCP Server action (Click to expand) + + ```json showLineNumbers + { + "identifier": "request_mcp_server", + "title": "Request New MCP Server", + "icon": "Microservice", + "description": "Request approval for a new MCP server to be added to the organization's approved registry", + "trigger": { + "type": "self-service", + "operation": "CREATE", + "userInputs": { + "properties": { + "server_name": { + "title": "Server Name", + "type": "string", + "icon": "DefaultProperty", + "description": "Name of the MCP server (e.g., 'Filesystem MCP', 'PostgreSQL MCP')" + }, + "type": { + "title": "Server Type", + "type": "string", + "icon": "DefaultProperty", + "enum": ["internal", "external"], + "enumColors": { + "internal": "blue", + "external": "purple" + }, + "description": "Is this an internally-built or external third-party MCP server?" + }, + "repository_url": { + "title": "Repository URL", + "type": "string", + "format": "url", + "icon": "DefaultProperty", + "description": "Link to the source code repository" + }, + "description": { + "title": "Description", + "type": "string", + "format": "markdown", + "icon": "DefaultProperty", + "description": "What does this MCP server do? Why should it be approved?" + }, + "labels": { + "title": "Labels", + "type": "array", + "items": { + "type": "string" + }, + "icon": "DefaultProperty", + "description": "Tags representing labels (e.g., database, filesystem, testing)" + }, + "command": { + "title": "Server Command", + "type": "string", + "icon": "DefaultProperty", + "description": "Command to run the MCP server (e.g., 'npx -y @modelcontextprotocol/server-filesystem')" + }, + "endpoint": { + "title": "Endpoint", + "type": "string", + "format": "url", + "icon": "DefaultProperty", + "description": "Endpoint URL for the MCP server (optional)" + }, + "business_justification": { + "title": "Business Justification", + "type": "string", + "format": "markdown", + "icon": "DefaultProperty", + "description": "Explain the business need and expected benefits" + } + }, + "required": [ + "server_name", + "type", + "repository_url", + "description", + "labels" + ], + "order": [ + "server_name", + "type", + "repository_url", + "description", + "labels", + "command", + "endpoint", + "business_justification" + ] + }, + "blueprintIdentifier": "mcpRegistry" + }, + "invocationMethod": { + "type": "UPSERT_ENTITY", + "blueprintIdentifier": "mcpRegistry", + "mapping": { + "identifier": "{{ .inputs.server_name | gsub(\" \"; \"-\") | ascii_downcase }}", + "title": "{{ .inputs.server_name }}", + "properties": { + "type": "{{ .inputs.type }}", + "status": "pending", + "description": "{{ .inputs.description }}", + "labels": "{{ .inputs.labels }}", + "repository_url": "{{ .inputs.repository_url }}", + "installation_instructions": "{{ .inputs.business_justification }}", + "command": "{{ .inputs.command }}", + "endpoint": "{{ .inputs.endpoint }}" + }, + "relations": { + "requestedBy": "{{ .trigger.by.user.email }}" + } + } + }, + "requiredApproval": false + } + ``` + +
+ +5. Click `Save` to create the action. + + +This action creates a new MCP Server entity with `status: pending`, allowing your team to track and manage MCP server requests. + + + +Once the MCP server is approved, it will be added to the catalog and the status will be updated to `approved`. + + + + + + +## Ingest MCP servers tools into the catalog + +Now that we have our mcp server entities in the catalog, let's explore how to automatically extract the mcp tools from the mcp server using GitHub Workflows. + +

Add GitHub secrets

+ +In your GitHub repository, [go to **Settings > Secrets**](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) and add the following secrets: + +**Required for Port API:** +- `PORT_CLIENT_ID` - Port Client ID [learn more](/build-your-software-catalog/custom-integration/api/#get-api-token). +- `PORT_CLIENT_SECRET` - Port Client Secret [learn more](/build-your-software-catalog/custom-integration/api/#get-api-token). + + +### Add MCP tools extraction script + +Create a Python script `scripts/extract_mcp_tools.py` in your repository. Visit the [Port product experiments repository](https://github.com/port-labs/port-product-experiments/blob/main/scripts/extract_mcp_tools.py) to copy the script used in this guide. + +The script performs the following operations: + +- **Authenticates with Port API** using your `PORT_CLIENT_ID` and `PORT_CLIENT_SECRET` credentials +- **Fetches all MCP servers** from your Port catalog that have a `command` property defined +- **Connects to each MCP server** using the MCP protocol and extracts available tools +- **Handles secret placeholders** in commands by replacing patterns like `YOUR__SECRET_NAME` or `` with environment variable values +- **Creates or updates tool entities** in Port's `mcpToolSpecification` blueprint, linking them to their parent MCP server +- **Updates MCP server entities** with the list of available tool names + +:::info Secret management pattern +The script uses a secure pattern for handling MCP server credentials: + +**Use placeholder patterns in commands:** +- **Pattern 1**: `YOUR__SECRET_NAME` (double underscore) +- **Pattern 2**: `` (angle brackets, single underscore) +- Example: `uvx mcp-server-port@latest --client-id --client-secret --region EU` + +**The workflow automatically:** +1. Detects placeholder patterns in commands +2. Replaces them with values from GitHub Secrets (e.g., `` → value of `PORT_CLIENT_ID` secret) +3. Executes the command with actual credentials +::: + +

Create GitHub workflow for MCP tools extraction

+ +Create the file `.github/workflows/extract_mcp_tools.yml` in the `.github/workflows` folder of your repository. + +
+ GitHub workflow for tool extraction (Click to expand) + + ```yaml showLineNumbers + name: Sync All MCP Tools to Port + + on: + workflow_dispatch: # Allow manual trigger + schedule: + - cron: '0 0 * * 0' # Weekly on Sunday at midnight + + jobs: + sync-all-mcp-tools: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + pip install mcp httpx + pip install uv # Install uv which provides uvx + + - name: Sync tools from all MCP servers + 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 + + - name: Report completion + if: always() + run: | + echo "✅ MCP tools sync workflow completed" + ``` + +
+ +:::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 ` 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. +::: + +The workflow runs automatically every Sunday at midnight (syncs all MCP servers) but can be adjusted to fit your organization's use case. + +## Let's test it + +Trigger the workflow manually or set it to run automatically on a schedule. + +1. Go to the Actions page of your repository. + +2. Click on the `extract_mcp_tools` workflow. + +3. Click on the `Run workflow` button. + +4. Wait for the workflow to complete. + +5. Check the logs to see if the tools were synced successfully. + + + +

Verify the tools in the catalog

+ +1. Go to the [MCP Registry](https://app.getport.io/mcpServers) page of your portal. + +2. Click on the `MCP Server` you want to inspect. + +3. Verify that the available MCP tools were synced successfully. + + + + + + + + +## AI agent integration + +Leverage Port's AI capabilities to enable intelligent discovery and recommendations for MCP servers. +With your MCP server registry in Port, you can use [Port AI](/ai-interfaces/port-ai/overview) to answer questions like: + +**Discovery queries:** +- "Which MCP servers are approved for our team to use?" +- "Show me all MCP servers that support database operations" +- "What internal MCP servers do we have?" + +**Tool-specific recommendations:** +- "Which MCP servers can I use for Java development?" +- "Find MCP servers with filesystem labels" +- "What MCP servers provide testing tools?" + +**Installation guidance:** +- "Show me the installation instructions for the PostgreSQL MCP server" +- "What are the setup steps for approved MCP servers?" +- "How do I configure the Filesystem MCP server?" + + + + + + + + + + + + + + + + + + + + + + + + +## Related resources + +- [Port MCP Server](/ai-interfaces/port-mcp-server/overview-and-installation) - Connect AI assistants to your Port catalog +- [Port AI Agents](/ai-interfaces/ai-agents/overview) - Build intelligent agents for developer workflows +- [Self-Service Actions](/actions-and-automations/create-self-service-experiences/) - Learn more about creating actions in Port +- [Automations](/actions-and-automations/define-automations/) - Deep dive into Port's automation capabilities + diff --git a/src/components/guides-section/consts.js b/src/components/guides-section/consts.js index c94f6acece..ee8952fd00 100644 --- a/src/components/guides-section/consts.js +++ b/src/components/guides-section/consts.js @@ -1479,14 +1479,23 @@ export const availableGuides = [ logos: ["AI", "GitHub"], link: "/guides/all/manage-ai-instructions", }, + { + title: "Manage MCP Server Registry", + description: "Build a centralized MCP server registry with governance, discovery, and automated metadata extraction", + tags: ["AI", "Actions", "Automations", "RBAC"], + logos: ["AI", "GitHub"], + link: "/guides/all/manage-mcp-registry", + + }, { title: "Auto-enhance PR descriptions with AI", description: "Automatically generate comprehensive, template-compliant PR descriptions using Claude Code", tags: ["SDLC", "GitHub", "AI", "Automations"], logos: ["AI", "GitHub", "Claude Code"], link: "/guides/all/auto-enhance-pr-descriptions-with-ai", - } - ,{title: "Streamline IaC with AI", + }, + { + title: "Streamline IaC with AI", description: "Use Port AI agents to automate IaC provisioning and management", tags: ["IaC for devs", "Github Copilot", "AI", "Actions"], logos: ["AI", "AWS"], diff --git a/static/img/ai-agents/MCPRegistry.png b/static/img/ai-agents/MCPRegistry.png new file mode 100644 index 0000000000..dce23d2605 Binary files /dev/null and b/static/img/ai-agents/MCPRegistry.png differ diff --git a/static/img/guides/ApprovedMCPServersCursor.png b/static/img/guides/ApprovedMCPServersCursor.png new file mode 100644 index 0000000000..93257252a5 Binary files /dev/null and b/static/img/guides/ApprovedMCPServersCursor.png differ diff --git a/static/img/guides/ApprovedMCPServersPortAI.png b/static/img/guides/ApprovedMCPServersPortAI.png new file mode 100644 index 0000000000..c3550c8fe3 Binary files /dev/null and b/static/img/guides/ApprovedMCPServersPortAI.png differ diff --git a/static/img/guides/ApprovedMCPServersVSCode.png b/static/img/guides/ApprovedMCPServersVSCode.png new file mode 100644 index 0000000000..ca81d3d743 Binary files /dev/null and b/static/img/guides/ApprovedMCPServersVSCode.png differ diff --git a/static/img/guides/IngestedMCPToolsExtractorWorkflow copy.png b/static/img/guides/IngestedMCPToolsExtractorWorkflow copy.png new file mode 100644 index 0000000000..afe74220ab Binary files /dev/null and b/static/img/guides/IngestedMCPToolsExtractorWorkflow copy.png differ diff --git a/static/img/guides/IngestedMCPToolsExtractorWorkflow.png b/static/img/guides/IngestedMCPToolsExtractorWorkflow.png new file mode 100644 index 0000000000..821876e46e Binary files /dev/null and b/static/img/guides/IngestedMCPToolsExtractorWorkflow.png differ diff --git a/static/img/guides/MCPRegistryOverview.png b/static/img/guides/MCPRegistryOverview.png new file mode 100644 index 0000000000..402c250b55 Binary files /dev/null and b/static/img/guides/MCPRegistryOverview.png differ diff --git a/static/img/guides/MCPToolsExtractorWorkflow.png b/static/img/guides/MCPToolsExtractorWorkflow.png new file mode 100644 index 0000000000..d8138d2954 Binary files /dev/null and b/static/img/guides/MCPToolsExtractorWorkflow.png differ diff --git a/static/img/guides/MCPToolsExtractorWorkflowDetails.png b/static/img/guides/MCPToolsExtractorWorkflowDetails.png new file mode 100644 index 0000000000..0aa838fe8c Binary files /dev/null and b/static/img/guides/MCPToolsExtractorWorkflowDetails.png differ diff --git a/static/img/guides/mcpRequestEntityApproved.png b/static/img/guides/mcpRequestEntityApproved.png new file mode 100644 index 0000000000..cd445a704c Binary files /dev/null and b/static/img/guides/mcpRequestEntityApproved.png differ diff --git a/static/img/guides/mcpRequestImagePendingApproval.png b/static/img/guides/mcpRequestImagePendingApproval.png new file mode 100644 index 0000000000..25fe812c59 Binary files /dev/null and b/static/img/guides/mcpRequestImagePendingApproval.png differ diff --git a/static/img/guides/moreMcpDetailsInMCPRegistry.png b/static/img/guides/moreMcpDetailsInMCPRegistry.png new file mode 100644 index 0000000000..96157ab8b7 Binary files /dev/null and b/static/img/guides/moreMcpDetailsInMCPRegistry.png differ