diff --git a/docs/ai-agents/build-an-ai-agent.md b/docs/ai-agents/build-an-ai-agent.md index d975b14bbe..094375bfe3 100644 --- a/docs/ai-agents/build-an-ai-agent.md +++ b/docs/ai-agents/build-an-ai-agent.md @@ -26,6 +26,10 @@ 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. +::: + ### Step 1: Define your agent's purpose The first step in building an AI agent is deciding on its purpose. @@ -51,6 +55,10 @@ 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. +::: + ### Step 3: Configure actions (optional) If your agent needs to run actions, you will need to: @@ -234,6 +242,10 @@ AI agents in Port can search, group, and index entities in your Port instance. H - **Permission model**: - Interaction with the AI agent is based on your user permissions. - 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. +:::
diff --git a/docs/ai-agents/interact-with-ai-agents.md b/docs/ai-agents/interact-with-ai-agents.md index a793b666c1..137da0ce12 100644 --- a/docs/ai-agents/interact-with-ai-agents.md +++ b/docs/ai-agents/interact-with-ai-agents.md @@ -15,6 +15,17 @@ import TabItem from "@theme/TabItem" Once you've built your AI agents, it's time to interact with them. Port provides several ways to communicate with your AI agents. +## Backend mode selection + +When interacting with AI agents, you can choose between two backend modes that determine the agent's capabilities: + +- **Standard backend**: Uses the agent's configured blueprint access and OpenAI GPT models +- **MCP server backend**: Provides enhanced capabilities with intelligent catalog access and Claude models + +:::tip Backend mode is interaction-level +The backend mode is controlled when you interact with agents (through widgets, API calls, etc.), not in the agent configuration itself. This means any agent can benefit from MCP server backend capabilities when you choose to use them. +::: + ## Interaction options You have two main approaches when interacting with AI agents in Port: @@ -50,6 +61,18 @@ Follow these steps to add an AI agent widget: The widget provides a chat interface where you can ask questions and receive responses from the **specific agent you configured** without leaving your dashboard. +### MCP server backend mode in widgets + +When adding an AI agent widget to your dashboard, you can configure whether to use the MCP server backend mode. During widget configuration, you'll see a "Use MCP" toggle option: + + + +When MCP server backend mode is enabled, the widget interface provides enhanced capabilities and visual indicators showing which tools are being used: + + + +This gives you transparency into the enhanced processing and shows you exactly which MCP server tools the agent is leveraging to answer your questions. + @@ -75,6 +98,10 @@ When you send a message, the app will: - Limit threads to five consecutive messages for optimal performance. - For best results, start new threads for new topics or questions. +:::info MCP server backend mode in Slack +Currently, Slack interactions use the agent's default backend mode configuration. The ability to choose or override the backend mode per interaction is not yet available in Slack, but will be added in future updates. +::: + @@ -116,6 +143,24 @@ curl 'https://api.port.io/v1/agent//invoke?stream=true' \\ --data-raw '{"prompt":"What is my next task?"}' ``` +**Using MCP Server Backend Mode via API:** + +You can override the agent's default backend mode by adding the `use_mcp` parameter: + +```bash +# Force MCP server backend mode +curl 'https://api.port.io/v1/agent//invoke?stream=true&use_mcp=true' \\ + -H 'Authorization: Bearer ' \\ + -H 'Content-Type: application/json' \\ + --data-raw '{"prompt":"What is my next task?"}' + +# Force standard backend mode +curl 'https://api.port.io/v1/agent//invoke?stream=true&use_mcp=false' \\ + -H 'Authorization: Bearer ' \\ + -H 'Content-Type: application/json' \\ + --data-raw '{"prompt":"What is my next task?"}' +``` + **Streaming Response Details (Server-Sent Events):** The API will respond with `Content-Type: text/event-stream; charset=utf-8`. @@ -259,7 +304,18 @@ The plan shows how the agent decided to tackle your request and the steps it int ### Tools used -This section displays the actual steps the agent took and the APIs it used to complete your request. It can be particularly helpful for debugging when answers don't meet expectations, such as when an agent: +This section displays the actual steps the agent took and the APIs it used to complete your request. The tools shown depend on the backend mode used: + +**Standard Backend Mode:** +- Shows traditional agent tools based on configured blueprint access +- Limited to predefined search and query capabilities + +**MCP Server Backend Mode:** +- Shows enhanced MCP server tools for comprehensive data access +- Includes all read-only tools available in the MCP server +- Provides more detailed tool execution information + +This information can be particularly helpful for debugging when answers don't meet expectations, such as when an agent: - Used an incorrect field name. - Chose an inappropriate property. @@ -308,7 +364,15 @@ Here are some common errors you might encounter when working with AI agents and This error occurs when an AI agent tries to execute a self-service action that requires selecting entities from specific blueprints, but the agent doesn't have access to those blueprints. **How to fix:** -Add the missing blueprints listed in the error message to the agent's configuration. + +For **Standard Backend Mode:** +- Add the missing blueprints listed in the error message to the agent's configuration. + +For **MCP Server Backend Mode:** +- This error is less common since MCP mode has broader data access +- If you encounter this error, it likely relates to action execution requirements +- Ensure the action's entity selection fields are properly configured +- Consider switching to MCP server backend mode for enhanced blueprint access
## Security considerations diff --git a/docs/ai-agents/overview.md b/docs/ai-agents/overview.md index 31aa3e4697..7db895db38 100644 --- a/docs/ai-agents/overview.md +++ b/docs/ai-agents/overview.md @@ -30,6 +30,21 @@ AI agents serve two primary functions: 2. **Assist with actions** by helping developers complete common tasks faster. Agents can suggest and pre-fill forms, guide developers through workflows, and provide relevant context for decision-making. You can decide whether they can run an action or require human approval. +## Enhanced capabilities with MCP server backend + +:::tip New capability +Port AI agents now support an enhanced **MCP server backend mode** that provides significantly expanded capabilities. This is a new feature that enhances your existing agents - you can enable it for any agent to unlock these advanced capabilities. +::: + +When using the MCP server backend mode, your AI agents gain: + +- **Expanded data access**: Intelligently queries your entire catalog without blueprint restrictions +- **Enhanced reasoning**: Powered by Claude models for improved analysis and decision-making +- **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. + ### Example use cases **Questions your agents can answer:** @@ -57,6 +72,7 @@ To start working with AI agents, follow these steps: - 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). ## Security and data handling @@ -151,7 +167,12 @@ We limit this data storage strictly to these purposes. You can contact us to opt
Which LLM models are you using? (Click to expand) -We aim to use the best models that will yield the best results while keeping your data safe; at the moment, we work with Open AI's GPT models, but this could change in the future. +We use different models depending on the backend mode: + +- **Standard backend**: OpenAI's GPT models for reliable performance and broad compatibility +- **MCP server backend**: Claude models for enhanced reasoning and analysis capabilities + +We aim to use the best models that will yield the best results while keeping your data safe. Model selection may evolve as we continue to optimize agent performance.
diff --git a/docs/ai-agents/temp_readme b/docs/ai-agents/temp_readme deleted file mode 100644 index 9591832aa8..0000000000 --- a/docs/ai-agents/temp_readme +++ /dev/null @@ -1,422 +0,0 @@ -# Port MCP Server - -The [Port IO](https://www.getport.io/) MCP server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server, enabling advanced automations and natual language interactions for developers and AI applications. - -## What You Can Do With Port MCP - -### Find Information Quickly -- **Get entity details** - "Who is the owner of service X?" -- **Check on-call status** - "Who is on call right now?" -- **Get catalog insights** - "How many services do we have in production?" - -### Analyze Scorecards -- **Identify weak points** - "Which services are failing for the gold level and why?" -- **Get compliance status** - "Show me all services that don't meet our security requirements" -- **Improve quality** - "What do I need to fix to reach the next scorecard level?" - -### Create Resources -- **Build scorecards** - "Create a new scorecard called 'Security Posture' with levels Basic, Silver, and Gold" -- **Define rules** - "Add a rule that requires services to have a team owner to reach the Silver level" -- **Setup quality gates** - "Create a rule that checks if services have proper documentation" - -We're continuously expanding Port MCP's capabilities. Have a suggestion? We'd love to hear your feedback on our [roadmap](https://roadmap.getport.io/ideas)! - - -# Installation - -## Prerequisites -Before you begin, you'll need: - -1. Create a Port Account (if you don't have one): - - Visit [Port.io](https://app.port.io/) - - Sign up for an account - -2. Obtain Port Credentials: - - Navigate to your Port dashboard - - Go to Settings > Credentials - - Save both the Client ID and Client Secret - -3. Installation Requirements: - - Either [Docker](https://www.docker.com/get-started/) installed on your system - - OR [uvx](https://pypi.org/project/uvx/) package manager installed - ->[!NOTE] ->You will also need to provide your Port region, which is either EU or US. If not provided, the default is EU. - -## Installation methods -Port MCP Server can be installed using two methods: - -### Package Installation (uvx) -Use our official [Port MCP server](https://pypi.org/project/mcp-server-port/) package. - -### Docker Installation -Use our official Docker image: -```bash -docker pull ghcr.io/port-labs/port-mcp-server:0.2.8 -``` - -### Additional configurations -You can pass these additional arguments for more advanced configuration: - -| Configuration Parameter | UVX Flag | Docker Environment Variable | Description | Default Value | -|------------------------|----------|---------------------------|-------------|---------------| -| Log Level | `log-level` | `PORT_LOG_LEVEL` | Controls the level of log output | `ERROR` | -| API Validation | `api-validation-enabled` | `PORT_API_VALIDATION_ENABLED` | Controls if API schema should be validated and fail if it's not valid | `False` | - -## Usage with Claude Desktop -1. Go to Settings > Developer and click on "Edit config". -2. Edit the `claude_desktop_config.json` file and add the below configuration based on the installation method. -3. Save the file and restart Claude. -4. In a new chat, check the Tools section and you'll see Port available tools. - -![Claude MCP Tools](/assets/claude_mcp_tools.png) - -### Docker - ->[!TIP] ->Consider using the full path to Docker (e.g., `/usr/local/bin/docker`) instead of just `docker`. You can find this path by running `which docker` in your terminal. Using the full path helps avoid PATH resolution issues and ensures consistent behavior across different shell environments. - -```json -{ - "mcpServers": { - "port": { - "command": "docker", - "args": [ - "run", - "-i", - "--rm", - "-e", - "PORT_CLIENT_ID", - "-e", - "PORT_CLIENT_SECRET", - "-e", - "PORT_REGION", - "-e", - "PORT_LOG_LEVEL", - "ghcr.io/port-labs/port-mcp-server:0.2.2" - ], - "env": { - "PORT_CLIENT_ID": "", - "PORT_CLIENT_SECRET": "", - "PORT_REGION": "", - "PORT_LOG_LEVEL": "" - } - } - } -} -``` - -### uvx - ->[!NOTE] ->If you want to run the command from a virtual Python environment, add a `PYTHONPATH` variable to the `env` object with its path, e.g., `/path/to/your/venv/bin/python`. - -```json -{ - "mcpServers": { - "Port": { - "command": "uvx", - "args": [ - "mcp-server-port@0.2.8", - "--client-id", - "", - "--client-secret", - "", - "--region", - "" - ], - "env": { - "PORT_CLIENT_ID": "", - "PORT_CLIENT_SECRET": "", - "PORT_REGION": "", - "PYTHONPATH": "/Users/matangrady/.venv-port-mcp/bin/python" - } - } - } -} -``` - -## Usage with Cursor - -1. Go to Cursor > Settings > Cursor Settings. -2. Click on the MCP tab, and "Add new global MCP server". -2. Edit the `mcp.json` file and add the below configuration based on the installation method. -3. Save the file and return to Cursor Settings. -4. You will see the new Port server and its available tools. - -![Cursor MCP Screenshot](/assets/cursor_mcp_screenshot.png) - -### Docker - ->[!TIP] ->Consider using the full path to Docker (e.g., `/usr/local/bin/docker`) instead of just `docker`. You can find this path by running `which docker` in your terminal. Using the full path helps avoid PATH resolution issues and ensures consistent behavior across different shell environments. - -```json -{ - "mcpServers": { - "port": { - "command": "docker", - "args": [ - "run", - "-i", - "--rm", - "-e", - "PORT_CLIENT_ID", - "-e", - "PORT_CLIENT_SECRET", - "-e", - "PORT_REGION", - "-e", - "PORT_LOG_LEVEL", - "ghcr.io/port-labs/port-mcp-server:0.2.2" - ], - "env": { - "PORT_CLIENT_ID": "", - "PORT_CLIENT_SECRET": "", - "PORT_REGION": "", - "PORT_LOG_LEVEL": "" - } - } - } -} -``` - - - -### uvx ->[!NOTE] ->If you want to run the command from a virtual Python environment, add a `PYTHONPATH` variable to the `env` object with its path, e.g., `/path/to/your/venv/bin/python`. - -```json -{ - "mcpServers": { - "Port": { - "command": "uvx", - "args": [ - "mcp-server-port@0.2.8", - "--client-id", - "", - "--client-secret", - "", - "--region", - "" - ], - "env": { - "PORT_CLIENT_ID": "", - "PORT_CLIENT_SECRET": "", - "PORT_REGION": "", - "PYTHONPATH": "/Users/matangrady/.venv-port-mcp/bin/python" - } - } - } -} -``` - -### Usage with VS Code - ->[!TIP] ->VS Code can automatically discover MCP servers already installed in Cursor and Claude. - ->[!NOTE] ->For quick installation, use the one-click install buttons and select where to add the MCP configuration. Make sure to replace the placeholders with your Port credentials. - -[Docker quick installation](https://insiders.vscode.dev/redirect/mcp/install?name=port&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22PORT_CLIENT_ID%22%2C%22-e%22%2C%22PORT_CLIENT_SECRET%22%2C%22-e%22%2C%22PORT_REGION%22%2C%22ghcr.io%2Fport-labs%2Fport-mcp-server%3A0.2.2%22%5D%2C%22env%22%3A%7B%22PORT_CLIENT_ID%22%3A%22%3CPORT_CLIENT_ID%3E%22%2C%22PORT_CLIENT_SECRET%22%3A%22%3CPORT_CLIENT_SECRET%3E%22%2C%22PORT_REGION%22%3A%22%3CPORT_REGION%3E%22%7D%7D) -[uvx quick installation](https://insiders.vscode.dev/redirect/mcp/install?name=port&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-port%400.2.8%22%2C%22--client-id%22%2C%22%3CPORT_CLIENT_ID%3E%22%2C%22--client-secret%22%2C%22%3CPORT_CLIENT_SECRET%3E%22%2C%22--region%22%2C%22%3CPORT_REGION%3E%22%5D%2C%22env%22%3A%7B%22PORT_CLIENT_ID%22%3A%22%3CPORT_CLIENT_ID%3E%22%2C%22PORT_CLIENT_SECRET%22%3A%22%3CPORT_CLIENT_SECRET%3E%22%2C%22PORT_REGION%22%3A%22%3CPORT_REGION%3E%22%7D%7D) - -For manual installation follow these steps: -1. Go to the Command Palette by pressing `Cmd + Shift + P` / `Ctrl + Shift + P`. -2. Type `Preferences: Open User Settings (JSON)` and press enter. -2. Edit the `settings.json` file and add the below configuration under the `mcp`>`servers`. -3. Use Copilot in Agent mode, make sure the server is running and see its available Port tools. - -![VS Code MCP Tools](/assets/vs_code_mcp_tools.png) - -### Docker ->[!TIP] ->Consider using the full path to Docker (e.g., `/usr/local/bin/docker`) instead of just `docker`. You can find this path by running `which docker` in your terminal. Using the full path helps avoid PATH resolution issues and ensures consistent behavior across different shell environments. - -```json - "Port": { - "type": "stdio", - "command": "docker", - "args": [ - "run", - "-i", - "--rm", - "-e", - "PORT_CLIENT_ID", - "-e", - "PORT_CLIENT_SECRET", - "-e", - "PORT_REGION", - "ghcr.io/port-labs/port-mcp-server:0.2.2" - ], - "env": { - "PORT_CLIENT_ID": "", - "PORT_CLIENT_SECRET": "", - "PORT_REGION": "" - } - } -``` - -### uvx - ->[!NOTE] ->If you want to run the command from a virtual Python environment, add a `PYTHONPATH` variable to the `env` object with its path, e.g., `/path/to/your/venv/bin/python`. - -```json - "Port": { - "type": "stdio", - "command": "uvx", - "args": [ - "mcp-server-port@0.2.8", - "--client-id", - "", - "--client-secret", - "", - "--region", - "" - ], - "env": { - "PORT_CLIENT_ID": "", - "PORT_CLIENT_SECRET": "", - "PORT_REGION": "" - } - } -``` - -# Available Tools - -## Blueprint Tools - -1. `get_blueprints` - - Retrieve a list of all blueprints from Port - - Optional inputs: - - `detailed` (boolean, default: false): Return complete schema details for each blueprint - - Returns: Formatted text representation of all available blueprints - -2. `get_blueprint` - - Retrieve information about a specific blueprint by its identifier - - Required inputs: - - `blueprint_identifier` (string): The unique identifier of the blueprint to retrieve - - Optional inputs: - - `detailed` (boolean, default: true): Return complete schema details - -3. `create_blueprint` - - Create a new blueprint in Port - - Required inputs: - - Various fields including identifier, title, properties, etc. - - Returns: The created blueprint object - -4. `update_blueprint` - - Update an existing blueprint - - Required inputs: - - `identifier` (string): The unique identifier of the blueprint to update - - Various fields to update - - Returns: The updated blueprint object - -5. `delete_blueprint` - - Delete a blueprint from Port - - Required inputs: - - `blueprint_identifier` (string): The unique identifier of the blueprint to delete - - Returns: Success status - -## Entity Tools - -1. `get_entities` - - Retrieve all entities for a given blueprint - - Required inputs: - - `blueprint_identifier` (string): The identifier of the blueprint to get entities for - - Optional inputs: - - `detailed` (boolean, default: false): Return complete entity details including properties - -2. `get_entity` - - Retrieve information about a specific entity - - Required inputs: - - `blueprint_identifier` (string): The identifier of the blueprint the entity belongs to - - `entity_identifier` (string): The unique identifier of the entity to retrieve - - Optional inputs: - - `detailed` (boolean, default: true): Return complete entity details - -3. `create_entity` - - Create a new entity for a specific blueprint - - Required inputs: - - `blueprint_identifier` (string): The identifier of the blueprint to create the entity for - - `entity` (object): The entity data following the blueprint schema - -4. `update_entity` - - Update an existing entity - - Required inputs: - - `blueprint_identifier` (string): The identifier of the blueprint the entity belongs to - - `entity_identifier` (string): The unique identifier of the entity to update - - `entity` (object): The updated entity data - -5. `delete_entity` - - Delete an entity - - Required inputs: - - `blueprint_identifier` (string): The identifier of the blueprint the entity belongs to - - `entity_identifier` (string): The unique identifier of the entity to delete - - Optional inputs: - - `delete_dependents` (boolean, default: false): If true, also deletes all dependencies - -## Scorecard Tools - -1. `get_scorecards` - - Retrieve all scorecards from Port - - Optional inputs: - - `detailed` (boolean, default: false): Return complete scorecard details - -2. `get_scorecard` - - Retrieve information about a specific scorecard by its identifier - - Required inputs: - - `scorecard_id` (string): The unique identifier of the scorecard to retrieve - - `blueprint_id` (string, optional): The identifier of the blueprint the scorecard belongs to - -3. `create_scorecard` - - Create a new scorecard for a specific blueprint - - Required inputs: - - `blueprint_id` (string): The identifier of the blueprint to create the scorecard for - - `identifier` (string): The unique identifier for the new scorecard - - `title` (string): The display title of the scorecard - - `levels` (list): List of levels for the scorecard - - Optional inputs: - - `rules` (list): List of rules for the scorecard - - `description` (string): Description for the scorecard - -4. `update_scorecard` - - Update an existing scorecard - - Required inputs: - - `blueprint_identifier` (string): The identifier of the blueprint the scorecard belongs to - - `scorecard_identifier` (string): The unique identifier of the scorecard to update - - Various fields to update (title, levels, rules, etc.) - - Returns: The updated scorecard object - -5. `delete_scorecard` - - Delete a scorecard from Port - - Required inputs: - - `blueprint_identifier` (string): The identifier of the blueprint the scorecard belongs to - - `scorecard_identifier` (string): The unique identifier of the scorecard to delete - - Returns: Success status - -## AI Agents Tool - -1. `invoke_ai_agent` - - Invoke a Port AI agent with a specific prompt - - Required inputs: - - `prompt` (string): The prompt to send to the AI agent - - Returns: Invocation status and message from the AI agent - -# Feedback and Roadmap - -We're continuously improving Port MCP and would love to hear from you! Please share your feedback and feature requests on our [roadmap page](https://roadmap.getport.io/ideas). - -# Troubleshooting - -If you encounter authentication errors, verify that: -1. Your Port credentials are correctly set in the arguments. -2. You have the necessary permissions. -3. The credentials are properly copied to your configuration. - -# License - -This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the [MIT License](https://github.com/port-labs/port-mcp-server/blob/main/LICENSE). \ No newline at end of file diff --git a/static/img/ai-agents/AIAgentsMCPWidgetConfig.png b/static/img/ai-agents/AIAgentsMCPWidgetConfig.png new file mode 100644 index 0000000000..4507c6a6a4 Binary files /dev/null and b/static/img/ai-agents/AIAgentsMCPWidgetConfig.png differ diff --git a/static/img/ai-agents/AIAgentsMCPWidgetUI.png b/static/img/ai-agents/AIAgentsMCPWidgetUI.png new file mode 100644 index 0000000000..72b4a35310 Binary files /dev/null and b/static/img/ai-agents/AIAgentsMCPWidgetUI.png differ