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

Check out Port for yourself ➜ 

MCP connectors

MCP Connectors turn Port into a unified MCP gateway, routing requests from developers and AI agents to external MCP servers while applying Port's governance, RBAC, and audit controls. Platform engineers configure which MCP servers are available and which tools are exposed. Developers and AI agents access everything through a single interface.

Why MCP connectors?​

Organizations building AI agents need access to tools beyond Port's native integrations. For example, internal documentation, custom systems, third-party platforms. Without MCP Connectors, teams either run parallel MCP systems (creating confusion) or build their own gateway infrastructure (recreating governance from scratch).

MCP Connectors solve three critical challenges:

  • Unified developer experience: Connect once to Port's MCP gateway instead of managing multiple separate integrations. Developers access Port's native tools and all approved external MCPs through one interface.

  • Governance and control: Platform engineers choose which MCPs are approved, which tools are exposed, and who can access them. Complete audit trails and RBAC enforcement apply to all tool invocations.

  • Holistic data access: Port AI uses the Context Lake for structured organizational data and MCP Connectors for ephemeral or time-series data that doesn't belong in your data model. Refer to the following article to learn more about why agents need both types of data.

Integrations vs. MCP connectors​

MCP connectors complement Port integrations rather than replace them — they serve different purposes and work best together. See Integrations vs. MCP connectors for guidance on when to use each and when to use both.

Setting up MCP connectors​

Admins configure which MCP connectors are available organization-wide and control which tools each connector exposes.

Prerequisites​

  • Admin role in Port.
  • Account credentials for the external tool you want to connect.

Add a connector​

  1. Go to the data sources page of your portal.
  2. Click on the + Data source in the top-right corner.
  3. Select the MCP Servers tab.
  4. Choose from the available MCP servers (like Notion, Linear, Slack, GitLab, etc) or select Custom Server to add your own.
  5. Fill in the connector details:
    • Name (required): A recognizable name for developers and AI agents.
    • Description: When this MCP should be used and for which use cases. This helps AI agents determine when to use this connector.
    • URL (required): The remote MCP server endpoint.
    • Icon: Select an icon to visually identify the connector.
    • Team: Assign ownership to a specific team.
    • Headers: Custom headers to include with requests (e.g., for API key authentication).
  6. Click Connect and complete the authentication flow if required.
  7. Under Allowed Tools, select which tools to expose to your organization using + Add Tool. Only the tools you add will be visible to users. Consider carefully before enabling write or delete capabilities - users and AI agents will be able to perform these actions based on their permissions in the external tool.
  8. Click Publish to make the connector available to users.
Any remote MCP server

You can connect any remote MCP server and not just the ones listed in the UI. Select Custom Server to add tools like Confluence, Kiro, or any other MCP-compatible service that provides a remote endpoint.

Advanced OAuth settings

For MCP servers that require manual OAuth configuration, you can expand the Advanced OAuth Settings section and provide:

  • OAuth Client ID and OAuth Client Secret: From the OAuth application you created in the external service.
  • OAuth Scope: The permissions to request during authentication.

MCP connectors can also be added from the MCP connector catalog page. When adding from the catalog, an additional property is available:

Expose Port Connector: Determines whether this entity is used as an active MCP connector. When enabled, the connector's tools are available to users through the AI assistant and Port MCP server. When disabled, the entity exists in the catalog but is not used as an MCP connector.

In-chat configuration

When a user asks for a tool that maps to an MCP server not yet configured for the organization, the Port AI assistant can offer to configure it inline by opening the same setup wizard. Users with permission to add MCP connectors see a configure option in chat. Users without that permission are told to ask an admin.

Supported server types​

Port supports several types of remote MCP servers. All require Name and URL. Additional configuration depends on the authentication method:

  • Dynamic client registration (e.g., Notion, Slack): Servers that support OAuth 2.0 Dynamic Client Registration. Port automatically registers as an OAuth client - no additional configuration required.

  • Manual client registration (e.g., GitHub, GitLab): Servers that require you to create an OAuth application first. Configure OAuth Client ID, OAuth Client Secret, and optionally OAuth Scope under Advanced OAuth Settings.

  • API-based authentication: Servers that use API keys or tokens. Add authentication credentials via Headers (e.g., Authorization: Bearer <token>).

  • No authentication (e.g., GitMCP): Publicly accessible servers - no additional configuration required.

Advanced MCP server configurations​

Some MCP servers require more detailed configuration than just a URL and authentication headers. For example, servers that use manual OAuth client registration require you to first create an OAuth application in the external service and then paste the credentials into Port.

See GitHub MCP connector for a step-by-step example of this setup.

Reference organization secrets​

When configuring authentication (via headers or Advanced OAuth Settings), you can reference your organization's secrets using the following syntax:

{{ .secrets["YOUR_SECRET_KEY"] }}

In headers:

{ "Authorization": "{{ .secrets[\"YOUR_SECRET_KEY\"] }}" }

In Advanced OAuth Settings inputs:

Use the same syntax in the OAuth Client ID and OAuth Client Secret fields to reference stored secrets:

{{ .secrets["YOUR_SECRET_KEY"] }}

Authenticate to connectors​

Once your admin has configured MCP connectors, you need to authenticate your personal account to use them.

From the MCP Servers menu​

  1. Open the MCP Servers modal and select the External MCP tab.
  2. You will see the MCP servers your admin has made available.
  3. Click Connect on one and complete the OAuth authentication flow.
  4. The MCP server is now available in all Port AI interfaces.

From Port AI assistant​

  1. Open the Port AI chat interface.
  2. Click the + button to see available MCP servers.
  3. Under Need to Connect, you will see servers that require authentication.
  4. Click on one to initiate authentication.
  5. Complete the OAuth flow.
  6. After authenticating, the server appears under Connectors with the number of enabled tools (e.g., "9 of 10").
The assistant can prompt you

When a task needs an MCP server that is configured for your organization but that you have not connected yet, the Port AI assistant surfaces a Connect card directly in the chat. Click Connect on the relevant server to complete the OAuth flow without leaving the conversation.

Manage your tools​

After authenticating, you can toggle which tools are active for your account:

  1. In the Port AI chat, click the + button.
  2. Under Connectors, click the arrow next to an authenticated server.
  3. Toggle individual tools on or off based on your needs.

You can only toggle tools that your admin has enabled. Tools not added by the admin will not appear.

Using MCP connectors​

After authenticating, you can use natural language to interact with external tools through any Port AI interface.

Example queries:

  • "Search Notion for our API authentication documentation"
  • "Find the deployment runbook in Confluence"
  • "Show me open Jira tickets for the payments service"
  • "What alerts fired in the last hour?"

IDE access​

If you've connected your IDE to Port's MCP server, your authenticated MCP connectors are automatically available alongside Port's native tools.

Connector tools are exposed with a prefixed name: {connector_identifier}_{tool_name}. For example, a Notion connector with identifier notion_pms that exposes notion-create-view appears in your IDE as notion_pms_notion-create-view. You can see the exact tool names for each connector in the MCP Servers modal, under the External MCP tab.

If connector tools appear in Port AI but not in your IDE, work through the troubleshooting steps in the FAQs below.

Security and permissions​

  • Per-user authentication: Each user authenticates with their own account. Data access respects individual permissions in the external tool.
  • RBAC enforcement: Port's role-based access controls apply to all MCP connector access.
  • Audit logging: All tool invocations are logged as part of AI invocations.

For more details, see AI Security and Data Controls.

Limitations​

  • Self-hosted MCP servers: Only remote MCP servers are supported. Self-hosted MCP servers cannot be connected as MCP connectors.
  • AI agents: MCP connectors on AI agent entities work in interactive chat when the user connects to each server. They do not run in automations or AI_AGENT workflow nodes. For automated external MCP, use workflow type: "AI" nodes with mcpServers. See use MCP connectors in workflows, build an AI agent, and external MCP connectors in workflows.
  • Automated workflows: Workflow AI nodes run with an organization automation token. Per-user OAuth connectors are not supported. Use organization-level OAuth or shared header authentication.
  • Remote MCP OAuth flows: OAuth for MCP connectors uses interactive browser consent. You can complete that consent per user (for interactive chat) or once with organization credentials (for automation-token callers). Port stores and refreshes tokens where supported. This aligns with authorization code-style grants, not machine-only OAuth. OAuth 2.0 client credentials from Port to the upstream remote MCP server are not yet supported. You can track progress on this feature via the roadmap.

FAQs​

Who can add MCP connectors?

By default, only admins can add and configure MCP connectors. Organizations can change this by editing the MCP (_mcp_server) blueprint permissions or by creating a self-service action.

Why don't I see any connectors available?

Your organization admin needs to add connectors first. Contact your platform team to request the tools you need.

What happens if my authentication expires?

Port automatically refreshes OAuth tokens where supported. If refresh fails or isn't available, you will be prompted to re-authenticate.

Can AI agents use MCP connectors?

Yes, in interactive chat. You can grant an AI agent access to external MCP servers by selecting MCP servers on the agent and choosing which tools the agent may use in the Allowed MCP tools section. See build an AI agent.

The user must connect to all of the agent's MCP servers before they can send it a message. See authenticate to connectors.

Agent MCP does not run in automations or AI_AGENT workflow nodes. For automated external MCP, use workflow type: "AI" nodes with mcpServers. See use MCP connectors in workflows, external MCP connectors in workflows, and MCP servers in API requests.

If you only need catalog data in automation, ingest it with an Ocean integration or a webhook so the agent can query it through Port's native tools.

A user says MCP connectors aren't visible - what should I check?

Work through this checklist in order:

  1. Admin published the connector - Go to Data Sources - MCP Servers and confirm the connector's status is Published (not Draft).
  2. Tools are enabled - Open the connector and confirm at least one tool has been added under Allowed Tools. A connector with no tools enabled is invisible to users.
  3. User has authenticated - Each user must authenticate individually. They can do this from the MCP Servers modal's External MCP tab, or by clicking the + button inside the Port AI chat under Need to Connect.
  4. User toggled the tools on - After authenticating, tools default to enabled, but users can toggle individual tools off. Ask the user to click + in AI chat and verify the connector shows the expected number of active tools (e.g., "9 of 10").
Connector tools work in Port AI but not in my IDE - what should I check?

This usually means the connector is configured correctly in Port, but your MCP client has a stale tool list or is connected to a different organization. Work through this checklist in order:

  1. Confirm the Port organization - Your IDE connects to the Port org you were logged into when you approved OAuth. Ask your assistant, "What Port org am I in?" or "Give me the Port org ID you're connected to," and compare the result with the org where the connector was configured. If they don't match, reconnect the Port MCP server while logged into the correct org. See connect the server to multiple organizations.
  2. Authenticate to the connector in Port - Even when using only the Port MCP server in your IDE, you must still authenticate to each external connector in Port. Go to the MCP Servers modal's External MCP tab and confirm the connector shows as connected.
  3. Remove duplicate MCP connections - If you previously connected the same external service directly in your IDE (for example, a standalone Notion MCP), disconnect it. Access external tools only through the Port MCP server to avoid conflicts and stale tool lists.
  4. Refresh the tools list in your MCP client - MCP clients cache the tool list from the Port MCP server. After an admin publishes a new connector or you authenticate to one, refresh the list:
    • Claude: Open Connectors, select Port IO, click the ⋮ menu, and choose Refresh tools list.
    • Other clients: Disconnect and reconnect the Port MCP server, or restart the client.
  5. Verify with a fresh tool check - Ask your assistant whether a specific tool is available, using the prefixed name shown under your connector in the MCP Servers modal's External MCP tab. For example: "Do you have a tool called notion_pms_notion-create-view?" Ask for a fresh check rather than relying on an earlier conversation.
How do I confirm which Port organization my MCP client is using?

Your MCP client connects to the Port organization you were logged into in your browser when you approved the OAuth prompt. It does not automatically follow org switches in the Port UI.

To verify the connected org, ask your assistant:

  • "What Port org am I in?"
  • "Give me the Port org ID you're connected to."

The response includes the organization id (for example, org_e2HTBfJlDPO8o0rn) and name. Compare this with the org shown in your Port portal URL or in Settings.

If the org is wrong, reconnect the Port MCP server while logged into the correct organization. See connect the server to multiple organizations.

How are MCP connector tool names formatted?

When you access connector tools through the Port MCP server, each tool name is prefixed with the connector's identifier in Port, followed by an underscore and the original tool name from the external MCP server.

Examples:

  • A GitHub connector with identifier git_hub exposes get_file_contents as git_hub_get_file_contents.
  • A Notion connector with identifier notion_pms exposes notion-create-view as notion_pms_notion-create-view.

The identifier is set when the admin creates the connector. To see the exact names available to you, open the MCP Servers modal, go to the External MCP tab, and review the tools listed for each connector. Admins can also review Allowed Tools on the Data sources → MCP Servers tab.

When configuring tool selection for agents or API requests, patterns must start with the connector identifier followed by an underscore (for example, notion_pms_.*).

Which authentication method should I use for MCP connectors?

Choose based on who calls the connector and whether upstream actions should be attributed to individual users:

  • Per-user OAuth: Each user authenticates with their own account. Actions are attributed to the individual user, and their personal permissions in the external tool are enforced. Use this for interactive Port AI chat when individual attribution matters (for example Jira, GitHub, or Slack).
  • Organization-level OAuth: An admin completes one OAuth consent with organization credentials. Upstream actions are attributed to the admin account that consented, not to each workflow triggerer. Workflow type: "AI" nodes and other automation-token callers can use the connector. See use MCP connectors in workflows.
  • Shared headers (API key in the Headers field): All callers share the same credentials. Actions in the external tool are attributed to whichever account owns the API key. Appropriate for read-only or system-level integrations, including automated workflows when the connector supports API keys.

To use a stored secret instead of hardcoding an API key in the Headers field:

{ "Authorization": "Bearer {{ .secrets[\"MY_API_KEY\"] }}" }

See Port secrets to manage your organization's secrets.

Do I need to provide a token endpoint when connecting to servers like AWS AgentCore?

No. Port auto-discovers the token endpoint using the standard MCP OAuth discovery flow, so you only need to provide the OAuth Client ID and OAuth Client Secret in Advanced OAuth Settings.

Here is what happens under the hood:

  1. Port sends an initial request to the MCP server.
  2. The server responds with a 401 and a pointer to its /.well-known/oauth-protected-resource metadata.
  3. Port reads that metadata to find the authorization server and token endpoint automatically.

This means servers like AWS AgentCore that issue a Cognito token endpoint work out of the box - no manual token endpoint configuration required.