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

Check out Port for yourself ➜ 

Installation

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

    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",
          "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.

  3. Authenticate with Port

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

    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.

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.

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.port.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.

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.

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 and troubleshooting​

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.

Why does Cursor prompt me to re-authenticate every day or two? (Click to expand)

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.

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

Refer back to the setup instructions for your specific application (Cursor, VS Code, Claude AI, Claude Code, or Codex CLI). 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.

How do I connect from Augment Code if OAuth fails? (Click to expand)

If you use Augment Code in VS Code and OAuth fails while connecting to Port MCP, configure the server with the command-based npx mcp-remote setup (instead of a direct HTTP OAuth MCP server configuration). This is a known issue documented by Augment in their MCP setup guide.

MCP tools appear but fail when using a corporate VPN or firewall (Click to expand)

If your MCP client shows the Port tools but all tool calls fail when connected to a corporate VPN or behind a firewall, your network may be blocking outbound traffic to Port's servers.

To resolve this, ask your network administrator to whitelist the following IP addresses:

US region:

  • 44.221.30.248
  • 44.193.148.179
  • 34.197.132.205

EU region:

  • 3.251.12.205
  • 34.252.219.131
  • 54.75.236.107
How can I disable the Port MCP installation option? (Click to expand)

Port does not provide a built-in setting to disable the MCP installation option. However, if you need to prevent MCP connections due to security policies or other organizational requirements, you can block network access to the MCP domain.

To disable Port MCP access, configure your firewall or network security tools to block outbound connections to the following domains:

EU region:

  • mcp.port.io

US region:

  • mcp.us.port.io

This will prevent users in your organization from establishing connections to the Port MCP server while still allowing access to other Port features.

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.