> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Installation

No Port AI terms required

The Port MCP server does not use Port AI capabilities. You can install and use it without enabling Port AI features or accepting the Port AI Terms.

This section details the installation process of the Port MCP server for your preferred IDE or AI assistant.

Follow the instructions for your preferred tool below:

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

  1. Open Cursor settings

    In the settings, click Customize, select MCPs, and then click New MCP Server.

    Cursor Customize settings with MCPs selected and New MCP Server highlighted

  2. Configure the MCP server

    Add the appropriate configuration for your Port region:

    {
      "mcpServers": {
        "port-eu": {
          "url": "https://mcp.port.io/v1",
          "headers": {
            "x-read-only-mode": "0"
          }
        }
      }
    }
    Read-only mode

    The x-read-only-mode header defaults to 0, which allows all tools based on your permissions. You can change it to 1 to restrict the MCP server to only expose read-only tools. When set to 1, write tools are completely hidden from the available tools list, ensuring you can only query data without making modifications.

    Cursor mcp.json defining a port-remote server with the Port US MCP URL

  3. Authenticate with Port

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

    Cursor MCP Tools settings showing port-remote enabled with Needs login status
    Cursor OAuth session persistence

    Port MCP authentication works on the initial connection. If Cursor prompts you to re-authenticate every day or two, this is typically caused by a known Cursor OAuth issue rather than a Port-side session or configuration problem.

    When Cursor refreshes your OAuth session, it may fail to persist or update tokens correctly. This is especially common when you have multiple Cursor windows open. Port's logs may show invalid_grant errors when Cursor attempts to refresh with a stale token.

    For more details and workarounds, see these Cursor community discussions:

    Cursor has reported fixes for some MCP OAuth issues in stable releases after May 12, 2026. If you experience frequent re-authentication, update Cursor to the latest stable version and check whether the issue persists.

  4. Verify connection

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

    Connected port-remote server in Cursor listing available blueprint, entity, scorecard, and action tools
Extended session duration

MCP clients can maintain authenticated sessions for up to 30 days (as long as you're not idle for 15 days). This applies to OAuth-based authentication for interactive use, providing a more seamless experience for long-running integrations.

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.

External tools via MCP connectors

In addition to Port's native tools, you can also access external MCP servers (like Notion, Slack, Jira, and more) through the same interface. If you have configured MCP connectors, authenticate to them in Port and they will automatically be available in your IDE alongside Port's native capabilities.

Platform teams can also run an MCP registry in the software catalog to track which MCP servers are approved, let developers request new servers, and publish installation guidance.

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:

Port error page showing Oops something went wrong when connecting to 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 machine authentication for automated environments like CI/CD pipelines where interactive authentication isn't possible. Request a token from the MCP OAuth endpoint:

curl -X POST "https://mcp.port.io/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

For complete examples and detailed setup instructions, see our machine authentication guide.

MCP server headers​

The Port MCP Server supports several headers that allow you to customize its behavior:

HeaderTypeDefaultDescription
x-read-only-modeString0Controls whether write tools are available. Set to 1 to restrict the MCP server to only expose read-only tools, completely hiding write tools from the available tools list. Set to 0 to allow all tools based on your permissions.
x-allowed-actions-to-runStringAll actionsComma-separated list of action identifiers that controls which actions are available through the run_action tool. Only the specified actions will be available. If not specified, all actions you have permission to run will be available. If set to an empty string, no actions will be allowed to run. Example: "create_github_issue,create_incident".

Configuring headers in your MCP client​

Headers are set in your MCP client's configuration file, not in Port itself. The exact syntax depends on your client.

Add an env block to your claude_desktop_config.json. Claude Desktop uses mcp-remote, which maps environment variables of the form MCP_REMOTE_HEADER_<HEADER_NAME_IN_SCREAMING_SNAKE_CASE> to HTTP headers.

{
  "mcpServers": {
    "port": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.port.io/v1"],
      "env": {
        "MCP_REMOTE_HEADER_X_READ_ONLY_MODE": "1",
        "MCP_REMOTE_HEADER_X_ALLOWED_ACTIONS_TO_RUN": "create_github_issue,deploy_service"
      }
    }
  }
}
US region

If your Port organization is in the US region, replace https://mcp.port.io/v1 with https://mcp.us.port.io/v1.

Restricting to specific actions

Use x-allowed-actions-to-run to scope a connection to only the actions relevant for a given context - for example, allowing a developer's IDE session to run only deployment actions, or giving a CI/CD integration access to a single scaffold action. To find an action's identifier, open the self-service page and copy the identifier from the action.

Prompts​

The MCP server exposes static and custom prompts in supported MCP clients. For setup, the prompt blueprint, and using prompts in Port AI Assistant, see the Prompts overview.

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 machine authentication guide.

FAQ and troubleshooting​