Skip to main content

Check out Port for yourself ➜ 

Port MCP server


The Port Model Context Protocol (MCP) Server acts as a bridge, enabling Large Language Models (LLMs)—like those powering Claude, Cursor, or GitHub Copilot—to interact directly with your Port.io developer portal. This allows you to leverage natural language to query your software catalog, analyze service health, manage resources, and even streamline development workflows, all from your preferred interfaces.

AI Agents vs. MCP Server

The Port MCP Server is currently in open beta and provides significant standalone value, independent of our AI Agents feature. Both the MCP Server and AI Agents are in open beta and available to all users. The MCP Server gives you immediate access to streamline building in Port, query your catalog, analyze service health, and streamline development workflows using natural language.

While the MCP Server can interact with Port AI Agents when available, the core MCP functionality can be used freely on its own.

Why integrate LLMs with your developer portal?​

The primary advantage of the Port MCP Server is the ability to bring your developer portal's data and actions into the conversational interfaces you already use. This offers several benefits:

  • Reduced Context Switching: Access Port information and initiate actions without leaving your IDE or chat tool.
  • Increased Efficiency: Get answers and perform tasks faster using natural language commands.
  • Improved Developer Experience: Make your developer portal more accessible and intuitive to interact with.
  • Enhanced Data-Driven Decisions: Easily pull specific data points from Port to inform your work in real-time.

As one user put it:

"It would be interesting to build a use case where a developer could ask Copilot from his IDE about stuff Port knows about, without actually having to go to Port."

The Port MCP Server directly enables these kinds of valuable, in-context interactions.

Key capabilities and use-cases​

The Port MCP Server enables you to interact with your Port data and capabilities directly through natural language within your chosen LLM-powered tools. Here's what you can achieve:

Find information quickly​

Effortlessly query your software catalog and get immediate answers. This eliminates the need to navigate through UIs or write complex API queries when you need information.

  • Ask: "Who is the owner of service X?"
  • Ask: "How many services do we have in production?"
  • Ask: "Show me all the microservices owned by the Backend team."
  • Ask: "What are the dependencies of the 'OrderProcessing' service?"

Vibe-build in Port​

Leverage Claude's capabilities to manage and build your entire Port software catalog. You can create and configure blueprints, set up self-service actions, design scorecards, and more.

  • Ask: "Please help me apply this guide into my Port instance - [[guide URL]]"
  • Ask: "I want to start managing my k8s deployments, how can we build it in Port?"
  • Ask: "I want a new production readiness scorecard to track the code quality and service alerts"
  • Ask: "Create a new self-service action in Port to scaffold a new service"

Analyze scorecards and quality​

Gain insights into service health, compliance, and quality by leveraging Port's scorecard data. Identify areas for improvement and track progress against your standards.

  • Ask: "Which services are failing our security requirements scorecard?"
  • Ask: "What's preventing the 'InventoryService' from reaching Gold level in the 'Production Readiness' scorecard?"
  • Ask: "Show me the bug count vs. test coverage for all Java microservices."
  • Ask: "Which of our services are missing critical monitoring dashboards?"

Streamline development and operations​

Receive assistance with common development and operational tasks, directly within your workflow.

  • Ask: "What do I need to do to set up a new 'ReportingService'?"
  • Ask: "Guide me through creating a new component blueprint with 'name', 'description', and 'owner' properties."
  • Ask: "Help me add a rule to the 'Tier1Services' scorecard that requires an on-call schedule to be defined."

Find your own use cases​

You can use Port's MCP to find the use cases that will be valuable to you. Try using this prompt: "think of creative prompts I can use to showcase the power of Port's MCP, based on the data available in Port"

Installing Port MCP​

Installing Port's MCP is simple. Follow the instructions for your preferred tool, or learn about the archived local MCP server.

To connect Cursor to Port's remote MCP, follow these steps:

  1. Open Cursor settings

    Go to Cursor settings, click on Tools & Integrations, and add a new MCP server.

  2. Configure the MCP server

    Add the appropriate configuration for your Port region:

{
  "mcpServers": {
    "port-eu": {
      "url": "https://mcp.port.io/v1"
    }
  }
}

  1. Authenticate with Port

    Click on "Needs login" and complete the authentication flow in the window that opens.

  2. Verify connection

    After successful authentication, you'll see the list of available tools from the MCP server.

Connect the server to multiple organizations​

Port uses your browser's OAuth session to approve MCP connections. When your MCP client opens the authentication prompt, you approve access in the organization where you are currently logged in. Follow these steps to connect to the correct organization:

  • Make sure you are logged in to the desired organization in your browser before you start the MCP connection flow.
  • Approve the OAuth prompt from your MCP client while you remain logged in to that organization.
  • Continue using the MCP client; changing your browser session afterward does not change the connected organization.

To connect another organization from the same MCP client, add a second configuration and repeat the flow while logged in to the other organization. Each configuration keeps its own OAuth approval, so you can work with multiple organizations in parallel.

Connecting the server when SSO is enabled​

If your organization uses SSO (Single Sign-On) and you see an error like the one below when trying to connect to the MCP Server:

This error occurs because the SSO connection needs to be configured for domain-level authentication to work with the MCP Server's OAuth flow.

Why this happens - When SSO is initially configured in Port, the authentication connection starts as a standard type. For the MCP Server to authenticate users through SSO, the connection needs to be upgraded to "domain level" mode, which enables Dynamic Client Registration (DCR). This configuration change can only be made by Port on the backend.

How to resolve - Contact our support team and let them know you're experiencing an SSO authentication error when connecting to the MCP Server. The support team will update your SSO connection configuration to enable domain-level authentication, which will allow the MCP Server OAuth flow to work correctly with your SSO provider.

Once the configuration is updated, retry the MCP Server connection and the authentication should work as expected.

Token-based authentication​

You can also connect using token-based authentication for automated environments like CI/CD pipelines where interactive authentication isn't possible:

curl -X POST "https://api.getport.io/v1/auth/access_token" \
  -H "Content-Type: application/json" \
  -d '{"clientId":"YOUR_CLIENT_ID","clientSecret":"YOUR_CLIENT_SECRET"}'

For complete examples and detailed setup instructions, see our token-based authentication guide.

Connecting to AI Agents​

To connect the Port MCP server to AI agents in CI/CD environments or other automated contexts where interactive authentication isn't possible, see our token-based authentication.

FAQ​

Can I change the organization after connecting? (Click to expand)

You cannot move an existing MCP connection. Update the configuration for your MCP client and reconnect while you are logged in to the organization you want to use.

How does the remote MCP server work with multiple organizations? (Click to expand)

Each organization requires a separate connection. Create separate MCP configurations and start each one while you are logged in to the desired organization in your browser. Each configuration keeps its own connection.

Do I need to stay logged in to the same browser session? (Click to expand)

You do not need to keep the browser logged in after approval. Your MCP client stays connected to the organization you authorized.

What happens if I approve the OAuth prompt in the wrong organization? (Click to expand)

Disconnect the MCP client or remove its credentials, then reconnect while logged in to the correct organization in your browser so you grant access to the right workspace.

How do I connect without using my browser for approval? (Click to expand)

Use token-based authentication when you are in CI/CD or another non-interactive environment. Generate a token with your client credentials and configure the MCP client with that token instead of signing in through the browser.

Why do I get an error when trying to connect with SSO enabled? (Click to expand)

If your organization uses SSO and you see an authentication error when connecting to the MCP Server, your SSO connection may need to be configured for domain-level authentication. This is a one-time configuration change that enables the MCP Server's OAuth flow to work with your SSO provider. Contact Port support to have this enabled for your organization. See the Connecting the server when SSO is enabled section for more details.

How can I connect to the MCP? (Click to expand)

Refer back to the setup instructions for your specific application (Cursor, VSCode, or Claude). Make sure you're using the correct regional URL for your Port organization.

I completed the connection but nothing happens (Click to expand)

Check that you've followed all the setup steps correctly for your application. Ensure you're authenticated with Port and have the necessary permissions. If you've followed all the steps and still have issues, please reach out to our support team.

Why do I see an error about too many tools? (Click to expand)

Each self-service action in your Port instance becomes an individual tool (as run_<action_identifier>). If your organization has many actions, this can result in a large number of tools being available.

While most AI models handle this well, some have restrictions and may limit you to around 40 tools total. If you encounter errors about tool limits:

  1. Reduce the number of tools by customizing which tools are enabled (see select which tools to use).
  2. Focus on essential tools by only enabling the read-only tools you need plus a few key actions.
  3. Contact your Port Admin to review which actions are essential for your workflow.

This is completely normal behavior and doesn't indicate a problem with Port MCP - it's just a limitation of some AI models.

Getting help

If you continue to experience issues, please reach out to Port support with:

  • Your IDE/application version.
  • The specific error messages you're seeing.
  • Your Port region (EU/US).
  • Steps you've already tried.

This information will help us provide more targeted assistance.