Merge pull request #2690 from port-labs/claude-code-remote-mcp-ci-guide

Adds explantion on using remote mcp in ci with claude code.

Author: hadar-co

docs/ai-agents/port-mcp-server.md

@@ -1,5 +1,5 @@
 {
-  "label": "AI agents & MCP server",
+  "label": "AI interfaces",
   "position": 9,
   "className": "custom-sidebar-item sidebar-menu-ai-agents"
 }

docs/ai-agents/_category_.json renamed to docs/ai-interfaces/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "AI agents",
+  "position": 1
+}

docs/ai-interfaces/ai-agents/_category_.json

@@ -18,7 +18,7 @@ Let's walk through the process of creating an agent that can assist your develop
 
 ## Create a new AI agent
 
-To create a new agent, head to the AI Agents catalog page (this page will be created for you when you [activate the feature](/ai-agents/overview#access-to-the-feature)).
+To create a new agent, head to the AI Agents catalog page (this page will be created for you when you [activate the feature](/ai-interfaces/ai-agents/overview#access-to-the-feature)).
 
 Click on the "New AI Agent" button and fill the form with the agent details.
 <img src='/img/ai-agents/AIAgentsList.png' width='80%' border='1px' />
@@ -27,7 +27,7 @@ Click on the "New AI Agent" button and fill the form with the agent details.
 We recommend following the steps below.
 
 :::info MCP Server Backend Mode
-AI agents can be enhanced with MCP server backend mode for expanded capabilities including intelligent catalog access and Claude model processing. This is controlled when [interacting with the agents](/ai-agents/interact-with-ai-agents) through widgets and API calls, not in the agent configuration itself.
+AI agents can be enhanced with MCP server backend mode for expanded capabilities including intelligent catalog access and Claude model processing. This is controlled when [interacting with the agents](/ai-interfaces/ai-agents/interact-with-ai-agents) through widgets and API calls, not in the agent configuration itself.
 :::
 
 ### Step 1: Define your agent's purpose
@@ -56,7 +56,7 @@ For example:
 Pay attention to relationships between entities to ensure your agent can provide comprehensive answers.
 
 :::tip Enhanced access with MCP server backend
-When using [MCP server backend mode](/ai-agents/interact-with-ai-agents) during interactions, the agent can intelligently access your entire catalog regardless of configured blueprints, providing more comprehensive answers.
+When using [MCP server backend mode](/ai-interfaces/ai-agents/interact-with-ai-agents) during interactions, the agent can intelligently access your entire catalog regardless of configured blueprints, providing more comprehensive answers.
 :::
 
 ### Step 3: Configure actions (optional)
@@ -155,7 +155,7 @@ Choose conversation starters that:
 When you feel your agent is ready:
 
 1. Set its status to "Active".
-2. Start interacting with it through the [available interfaces](/ai-agents/interact-with-ai-agents).
+2. Start interacting with it through the [available interfaces](/ai-interfaces/ai-agents/interact-with-ai-agents).
 
 ## Evaluating your agent performance
 
@@ -166,7 +166,7 @@ Continuous evaluation and improvement are essential for maintaining effective AI
 3. **Analyze execution plans**: Examine how the agent processes requests by reviewing the execution plan and tool calls for specific invocations. This helps identify where improvements are needed.
 4. **Refine the prompt**: Update your agent's prompt based on your findings to address common issues.
 
-For more details on how to view execution plans and analyze agent behavior, see [Interact with AI agents](/ai-agents/interact-with-ai-agents).
+For more details on how to view execution plans and analyze agent behavior, see [Interact with AI agents](/ai-interfaces/ai-agents/interact-with-ai-agents).
 
 ## Examples
 
@@ -194,7 +194,7 @@ Your goal is to help developers initiate and track deployments to various enviro
 ## Formatting the agent response
 To format the agent's response, you can specify the desired format in its prompt. For optimal results when using the UI, it's recommended to request a markdown format response. 
 This allows for better presentation and readability of the information provided by the agent.
-When sending messages through Slack, our [Slack app](/ai-agents/slack-app) convert the markdown format into a Slack compatible formatting.
+When sending messages through Slack, our [Slack app](/ai-interfaces/ai-agents/slack-app) convert the markdown format into a Slack compatible formatting.
 
 ### Example of a Markdown Response
 ```markdown
@@ -208,7 +208,7 @@ From [john-123](https://github.com/john-123)
 <details>
 <summary><b>I don't see an option to add an AI agent (Click to expand)</b></summary>
 
-Make sure you have [access to the AI agents feature](/ai-agents/overview#access-to-the-feature). Note that it's currently in closed beta and requires special access. If you believe you should have access, please contact our support.
+Make sure you have [access to the AI agents feature](/ai-interfaces/ai-agents/overview#access-to-the-feature). Note that it's currently in closed beta and requires special access. If you believe you should have access, please contact our support.
 </details>
 
 <details>
@@ -244,7 +244,7 @@ AI agents in Port can search, group, and index entities in your Port instance. H
   - Sequential automations run as Admin.
 
 :::info Enhanced capabilities with MCP server backend
-When using [MCP server backend mode](/ai-agents/interact-with-ai-agents) during interactions, many of these limitations are reduced as the agent gains access to enhanced tools and broader data access capabilities.
+When using [MCP server backend mode](/ai-interfaces/ai-agents/interact-with-ai-agents) during interactions, many of these limitations are reduced as the agent gains access to enhanced tools and broader data access capabilities.
 :::
 </details>
 
@@ -257,4 +257,4 @@ When configuring your agent's actions, make sure you select the "approval" optio
 ## Security considerations
 
 AI agents in Port are designed with security and privacy as a priority.
-For more information on security and data handling, see our [AI agents overview](/ai-agents/overview#security-and-data-handling). 
+For more information on security and data handling, see our [AI agents overview](/ai-interfaces/ai-agents/overview#security-and-data-handling). 

docs/ai-agents/build-an-ai-agent.md renamed to docs/ai-interfaces/ai-agents/build-an-ai-agent.md

@@ -80,7 +80,7 @@ The Slack integration provides the most natural way to interact with Port's AI a
 
 You can interact with agents in two ways:
 
-1. **Direct messaging** the [Port Slack app](/ai-agents/slack-app). This will use the agent router.
+1. **Direct messaging** the [Port Slack app](/ai-interfaces/ai-agents/slack-app). This will use the agent router.
 2. **Mentioning** the app in any channel it's invited to. This will also use the agent router.
 
 When you send a message, the app will:
@@ -277,7 +277,7 @@ AI agents are standard Port entities belonging to the `_ai_agent` blueprint. Thi
 
 You can discover available AI agents in your Port environment in a couple of ways:
 
-1.  **AI Agents Catalog Page**: Navigate to the AI Agents catalog page in Port. This page lists all the agents that have been created in your organization. For more details on creating agents, refer to the [Build an AI agent guide](/ai-agents/build-an-ai-agent).
+1.  **AI Agents Catalog Page**: Navigate to the AI Agents catalog page in Port. This page lists all the agents that have been created in your organization. For more details on creating agents, refer to the [Build an AI agent guide](/ai-interfaces/ai-agents/build-an-ai-agent).
 2.  **Via API**: Programmatically retrieve a list of all AI agents using the Port API. AI agents are entities of the `_ai_agent` blueprint. You can use the [Get all entities of a blueprint API endpoint](https://docs.port.io/api-reference/get-all-entities-of-a-blueprint) to fetch them, specifying `_ai_agent` as the blueprint identifier.
 
 <details>
@@ -379,7 +379,7 @@ For **MCP Server Backend Mode:**
 
 AI agent interactions in Port are designed with security and privacy as a priority.
 
-For more information on security and data handling, see our [AI agents overview](/ai-agents/overview#security-and-data-handling). 
+For more information on security and data handling, see our [AI agents overview](/ai-interfaces/ai-agents/overview#security-and-data-handling). 
 
 ## Troubleshooting & FAQ
 
@@ -409,7 +409,7 @@ We're working on adding direct interaction through the Port UI in the future.
 
 Each agent has optional conversation starters to help you understand what it can help with. The questions you can ask depend on which agents were built in your organization.
 
-For information on building agents with specific capabilities, see our [Build an AI agent](/ai-agents/build-an-ai-agent) guide.
+For information on building agents with specific capabilities, see our [Build an AI agent](/ai-interfaces/ai-agents/build-an-ai-agent) guide.
 </details>
 
 <details>
@@ -435,7 +435,7 @@ Remember that AI agents are constantly learning and improving, but they're not i
 <summary><b>My agent isn't responding in Slack (Click to expand)</b></summary>
 
 Ensure that:
-- The [Port Slack app](/ai-agents/slack-app) is properly installed in your workspace.
+- The [Port Slack app](/ai-interfaces/ai-agents/slack-app) is properly installed in your workspace.
 - The app has been invited to the channel where you're mentioning it.
 - You're correctly mentioning the app (@Port).
 - You've completed the authentication flow with the app.

docs/ai-agents/interact-with-ai-agents.md renamed to docs/ai-interfaces/ai-agents/interact-with-ai-agents.md

@@ -43,7 +43,7 @@ When using the MCP server backend mode, your AI agents gain:
 - **Broader tool access**: Uses all read-only tools available in the MCP server for comprehensive insights
 - **Smarter action selection**: Still respects your configured allowed actions while providing better context
 
-Your existing agents can immediately benefit from these enhancements by enabling the MCP server backend mode when [interacting with them](/ai-agents/interact-with-ai-agents) through widgets and API calls.
+Your existing agents can immediately benefit from these enhancements by enabling the MCP server backend mode when [interacting with them](/ai-interfaces/ai-agents/interact-with-ai-agents) through widgets and API calls.
 
 ### Example use cases
 
@@ -61,18 +61,18 @@ Your existing agents can immediately benefit from these enhancements by enabling
 To start working with AI agents, follow these steps:
 
 1. **Apply for access** - Submit your application via [this form](https://forms.gle/krhMY7c9JM8MyJJf7).
-2. **Access the feature** - If accepted, you will be able to [activate the AI agents](/ai-agents/overview#access-to-the-feature) in your Port organization.
-3. **Build your agents** - [Create custom agents](/ai-agents/build-an-ai-agent) to meet your developers' needs.
-4. **Interact with your agents** - Engage with your agents by following our [interaction guide](/ai-agents/interact-with-ai-agents).
+2. **Access the feature** - If accepted, you will be able to [activate the AI agents](/ai-interfaces/ai-agents/overview#access-to-the-feature) in your Port organization.
+3. **Build your agents** - [Create custom agents](/ai-interfaces/ai-agents/build-an-ai-agent) to meet your developers' needs.
+4. **Interact with your agents** - Engage with your agents by following our [interaction guide](/ai-interfaces/ai-agents/interact-with-ai-agents).
 
 ## Customization and control
 
-[Build and customize](/ai-agents/build-an-ai-agent) your AI agents:
+[Build and customize](/ai-interfaces/ai-agents/build-an-ai-agent) your AI agents:
 - Define which data sources your agents can access.
 - Determine what actions your agents can assist with.
 - Set permissions for who can use specific agents.
 - Configure how agents integrate with your workflows.
-- Choose between standard and MCP server backend modes when [interacting with agents](/ai-agents/interact-with-ai-agents).
+- Choose between standard and MCP server backend modes when [interacting with agents](/ai-interfaces/ai-agents/interact-with-ai-agents).
 
 ## Security and data handling
 
@@ -101,9 +101,9 @@ Your organization now has the system blueprints required for the feature to work
 ## Data Model
 The data model of AI agents includes two main blueprints:
 
-1. **AI agents** - The agents themselves that you can interact with. You can build new ones and customize them as you wish. Learn more in our [Build an AI agent](/ai-agents/build-an-ai-agent) guide.
+1. **AI agents** - The agents themselves that you can interact with. You can build new ones and customize them as you wish. Learn more in our [Build an AI agent](/ai-interfaces/ai-agents/build-an-ai-agent) guide.
 
-2. **AI invocations** - Each interaction made with an AI agent is recorded as an invocation. This acts as a log of everything going through your AI agents so you can monitor and improve them over time. Learn more in our [Interact with AI agents](/ai-agents/interact-with-ai-agents) guide.
+2. **AI invocations** - Each interaction made with an AI agent is recorded as an invocation. This acts as a log of everything going through your AI agents so you can monitor and improve them over time. Learn more in our [Interact with AI agents](/ai-interfaces/ai-agents/interact-with-ai-agents) guide.
 
 ## Relevant guides
 
@@ -139,7 +139,7 @@ Port AI supports two primary interaction types:
 <details>
 <summary>How do users interact with Port AI? (Click to expand)</summary>
 
-- Primary interface is through our [Slack app](/ai-agents/slack-app).
+- Primary interface is through our [Slack app](/ai-interfaces/ai-agents/slack-app).
 - Full [API availability](/api-reference/port-api/).
 </details>
 

docs/ai-agents/overview.md renamed to docs/ai-interfaces/ai-agents/overview.md

@@ -31,7 +31,7 @@ This can be used to get quick answers to questions about your resources, such as
 - To install the Slack app, you will first need to apply for access to Port's AI program by filling out [this form](https://forms.gle/krhMY7c9JM8MyJJf7).
 
 - To interact with AI agents, you need to have at least one agent deployed in your portal.  
-  See the [Build an AI agent](https://docs.port.dev/ai-agents/build-an-ai-agent) page to learn more.
+  See the [Build an AI agent](https://docs.port.dev/ai-interfaces/ai-agents/build-an-ai-agent) page to learn more.
 
 ## Installation
 

docs/ai-agents/slack-app.md renamed to docs/ai-interfaces/ai-agents/slack-app.md

@@ -0,0 +1,4 @@
+{
+  "label": "MCP server",
+  "position": 2
+}

docs/ai-interfaces/port-mcp-server/_category_.json

@@ -0,0 +1,91 @@
+---
+sidebar_position: 3
+title: Tools
+---
+
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
+# Available tools
+
+The Port MCP Server exposes different sets of tools based on your role and use case. The tools you see will depend on your permissions in Port.
+
+<Tabs groupId="user-role" queryString>
+<TabItem value="developer" label="Developer">
+
+**Developers** are typically users who consume and interact with the developer portal - querying services, running actions, and analyzing data. These tools help you get information and execute approved workflows.
+
+**Query and analysis tools**
+- **[`get_blueprints`](/api-reference/get-all-blueprints)**: Retrieve a list of all blueprints from Port.
+- **[`get_blueprint`](/api-reference/get-a-blueprint)**: Retrieve information about a specific blueprint by its identifier.
+- **[`get_entities`](/api-reference/get-all-entities-of-a-blueprint)**: Retrieve all entities for a given blueprint.
+- **[`get_entity`](/api-reference/get-an-entity)**: Retrieve information about a specific entity.
+- **[`get_scorecards`](/api-reference/get-all-scorecards)**: Retrieve all scorecards from Port.
+- **[`get_scorecard`](/api-reference/get-a-scorecard)**: Retrieve information about a specific scorecard by its identifier.
+- **[`describe_user_details`](/api-reference/get-organization-details)**: Get information about your Port account, organization, and user profile details.
+- **`search_port_docs_sources`**: Search through Port documentation sources for relevant information.
+- **`ask_port_docs`**: Ask questions about Port documentation and get contextual answers.
+
+**Action execution tools**
+- **[`run_<action_identifier>`](/api-reference/execute-a-self-service-action)**: Execute any action you have permission to run in Port.
+
+**AI agent tools**
+- **[`invoke_ai_agent`](/api-reference/invoke-an-agent)**: Invoke a Port AI agent with a specific prompt.
+
+</TabItem>
+<TabItem value="builder" label="Builder">
+
+**Builders** are platform engineers or admins who design and configure the developer portal - creating blueprints, setting up scorecards, and managing the overall structure. These tools help you build and maintain the portal.
+
+**All Developer tools**
+Builders have access to all the tools available to Developers (listed above), plus the additional management tools below.
+
+**Blueprint management tools**
+- **[`create_blueprint`](/api-reference/create-a-blueprint)**
+- **[`update_blueprint`](/api-reference/update-a-blueprint)**
+- **[`delete_blueprint`](/api-reference/delete-a-blueprint)**
+
+**Entity management tools**
+- **[`create_entity`](/api-reference/create-an-entity)**
+- **[`update_entity`](/api-reference/update-an-entity)**
+- **[`delete_entity`](/api-reference/delete-an-entity)**
+
+**Scorecard management tools**
+- **[`create_scorecard`](/api-reference/create-a-scorecard)**
+- **[`update_scorecard`](/api-reference/change-scorecards)**
+- **[`delete_scorecard`](/api-reference/delete-a-scorecard)**
+
+</TabItem>
+</Tabs>
+
+## Select which tools to use
+
+By default, when you open a chat with Port MCP, all available tools (based on your permissions) are loaded and ready to use. However, you can customize which tools are available if you want to focus on specific workflows.
+
+For example, if you only want to query data from Port without building or modifying anything, you can limit the tools to just the read-only ones. This helps reduce complexity and ensures you don't accidentally make changes.
+
+<Tabs groupId="tool-selection" queryString>
+<TabItem value="cursor" label="Cursor">
+
+In Cursor, you can customize which tools are available through the UI after connecting to Port MCP. Once connected, you can select specific tools as shown below.
+
+![Enabling specific tools in Cursor](/img/ai-agents/MCPCursorEnableTools.png)
+
+</TabItem>
+<TabItem value="vscode" label="VSCode">
+
+In VSCode, you can choose the tools through the UI after connecting to Port MCP.
+
+![Enabling specific tools in VSCode](/img/ai-agents/MCPVSCodeEnableTools.png)
+
+</TabItem>
+<TabItem value="claude" label="Claude">
+
+When creating a custom connector in Claude, you can specify exactly which tools to expose instead of enabling everything.
+
+![Enabling specific tools in Claude](/img/ai-agents/MCPClaudeEnableTools.png)
+
+Refer to the [Claude custom connector documentation](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) for detailed instructions.
+
+</TabItem>
+</Tabs>