docs(DATAGO-118857): Adding documentation covering connectors

docs/docs/documentation/enterprise/connectors/connectors.md

@@ -5,92 +5,57 @@ sidebar_position: 10
 
 # Connectors
 
-Connectors link agents to external data sources and services. Each connector type provides access to different systems using configured credentials and connection details. Agents use connectors to retrieve information, execute queries, and interact with external platforms through natural language conversations.
+Connectors allow your agents to access external data sources and services. You configure each connector with credentials and connection details for a specific system. Agents use connectors to retrieve information, execute queries, and interact with external platforms through natural language conversations.
 
-## SQL Connectors
+## Connector Types
 
-SQL connectors enable agents to query and analyze database information using natural language. These connectors convert user questions into SQL queries, execute them against configured databases, and return results in a conversational format. This capability makes database information accessible through agent interactions without requiring users to write SQL code.
+Agent Mesh Enterprise provides multiple connector types. Each type integrates with different external systems.
 
-### Supported Databases
+### OpenAPI Connectors
 
-SQL connectors support three database types:
+OpenAPI connectors allow agents to interact with REST APIs that use OpenAPI specifications. The connectors automatically generate callable tools from API endpoints. Agents use these tools to make authenticated HTTP requests to external services. For detailed information about creating and configuring OpenAPI connectors, see [OpenAPI Connectors](openapi-connectors.md).
 
-- MySQL
-- PostgreSQL
-- MariaDB
+### MCP Connectors
 
-Each database type follows the same configuration process but may have specific connection string requirements or authentication methods.
+Model Context Protocol (MCP) connectors allow agents to communicate with MCP-compliant servers. The connectors provide access to external tools and data sources that implement the MCP standard. For detailed information about creating and configuring MCP connectors, see [MCP Connectors](mcp-connectors.md).
 
-### Creating SQL Connectors
+### SQL Connectors
 
-You create SQL connectors in the Connectors section of the Enterprise web interface. This process must be completed before you can assign connectors to agents.
+SQL connectors allow agents to query relational databases using natural language. The connectors convert user questions into SQL queries and execute them against MySQL, PostgreSQL, or MariaDB databases. For detailed information about creating and configuring SQL connectors, see [SQL Connectors](sql-connectors.md).
 
-Each SQL connector configuration includes the database type selection, connection details (host address, port number, and database name), and authentication credentials (username and password). The connection configuration establishes a persistent connection pool that agents use to execute queries. You should verify that the database server allows connections from the Agent Mesh deployment and that any required firewall rules permit access.
+## Creating Connectors
 
-Once you create a connector, it becomes available for assignment to any agent in your deployment. This reusability means you can connect multiple agents to the same database without duplicating connection configuration. All agents assigned to a connector share the same database connection pool and credentials.
+You create connectors through the Connectors section of the Agent Mesh Enterprise web interface. Navigate to the Connectors page and click the Create Connector button to begin the creation process. The creation process varies depending on the connector type. All connectors require a unique name and connection credentials appropriate for the target system.
 
-### Security Considerations
+Once you create a connector, it becomes available for assignment to any agent in your deployment. This reusability means you can connect multiple agents to the same external system without duplicating connection configuration.
 
-The framework implements a shared credential model that has significant implications for access control when planning your deployment architecture.
+## Shared Credential Model
 
-#### Shared Credential Architecture
+All connector types in Agent Mesh Enterprise implement a shared credential model. When you create a connector, you configure it with specific credentials (database passwords, API keys, service account tokens, etc.). All agents assigned to that connector use the connector's credentials and have identical access permissions to the external system.
 
-The framework does not sandbox database access at the agent level. All agents assigned to a connector share the same database credentials and permissions. This design means that any agent with the connector can access all data the connector's credentials permit. Security boundaries exist at the database level, not between agents.
+This design has important security implications. You cannot restrict one agent to read-only access and another agent to write access if they share the same connector. Security boundaries exist at the external system level (database permissions, API scopes, etc.), not at the connector assignment level within Agent Mesh Enterprise.
 
-#### Implementing Database-Level Security
+If different agents require different levels of access to the same system, you must create multiple connectors with different credentials, each having appropriate permissions configured in the external system.
 
-Database-level access control is your primary security mechanism. You should create database users with minimal necessary privileges, use database views or restricted schemas to limit what agents can access, and audit database queries to monitor what agents are accessing.
+## Assigning Connectors to Agents
 
-For example, if you have agents that should only read customer data and other agents that need full database access, you must create separate connectors with different database users. Each database user has appropriate permissions configured at the database level. You cannot restrict access by assigning the same connector to different agents because all agents sharing a connector have identical database permissions.
+You assign connectors to agents through Agent Builder. When creating or editing an agent, you select connectors from the available connectors list. You can assign multiple connectors to a single agent if it needs to access multiple external systems.
 
-#### Natural Language Query Risks
+Changes to connector assignments take effect when you deploy or update the agent. If you remove a connector assignment from a deployed agent, that agent loses access to the connector's capabilities immediately after you deploy the update.
 
-The natural language to SQL conversion capability makes databases accessible through conversation, but this also means users can potentially request any data the connector can access. You should plan your database permissions accordingly and consider what information should be available through agent interactions.
+## Managing Connectors
 
-Users might phrase questions in ways that expose data you intended to restrict, or they might discover table and column names through exploratory questions. Database views that present only approved data columns, user accounts with read-only permissions on specific tables, and query result size limits all help mitigate these risks.
+### Editing Connectors
 
-#### Best Practices
+You can modify connector configurations at any time through the Connectors interface. The connector applies changes to connection details or credentials when you deploy a new agent. Existing agents continue to use the previous configuration until you redeploy them.
 
-Create separate connectors for different security boundaries. If agents require different levels of database access, configure multiple connectors with appropriately scoped database users rather than sharing a single connector across all agents.
+If agents are actively using a connector when you modify it, temporary failures may occur during the transition period. You should plan connector updates during maintenance windows or coordinate with agent users to minimize disruptions.
 
-Use read-only database accounts whenever possible. Many agent use cases only require reading data, and read-only permissions prevent accidental or malicious data modification.
+### Deleting Connectors
 
-Implement database views to present filtered data. Views can hide sensitive columns, join tables to present aggregated information, or implement row-level security logic at the database level.
+You can delete a connector only if no agents are assigned to it. The system enforces this restriction to prevent breaking deployed agents. If agents have the connector assigned, you must first undeploy those agents, remove the connector assignment from the agent configuration, and then delete the connector.
 
-Enable query logging and monitoring to track what agents access. Database audit logs help you detect suspicious query patterns or unauthorized data access attempts.
-
-### Assigning Connectors to Agents
-
-You assign connectors to agents through Agent Builder. When creating or editing an agent, you select connectors from a list during agent configuration. You can assign connectors before or after deployment, and changes to connector assignments take effect when you deploy or update the agent.
-
-### Managing Connectors
-
-Connector management operations require specific RBAC capabilities and follow particular patterns to prevent service disruptions.
-
-#### Editing Connectors
-
-You can modify connector configurations at any time. Changes to connection details or credentials take effect immediately for new database connections. Existing connections in the pool may continue using previous credentials until they expire and reconnect.
-
-If agents are actively using a connector when you modify it, query failures may occur during the transition period. You should plan connector updates during maintenance windows or coordinate with agent users to minimize disruptions.
-
-#### Testing Connections
-
-The Connectors interface provides connection testing functionality that validates credentials and connectivity before you save the connector configuration. This testing helps identify configuration errors before agents attempt to use the connector.
-
-#### Deleting Connectors
-
-You can delete connectors, but the system enforces restrictions to prevent breaking deployed agents. If any agents are assigned to a connector, you must first remove the connector from those agents or undeploy them before deletion succeeds.
-
-The deletion process removes the connector configuration but does not affect the database itself. Database users and permissions remain in place, requiring separate cleanup if you no longer need them.
-
-### Troubleshooting
-
-When connecting SAM to a PostgreSQL databases hosted on Supabase, you may encounter network errors like:
-
-`{ "detail": "Invalid token", "error_type": "invalid_token" }`
-
-This is because Supabase's direct connection endpoint uses IPv6, however most Kubernetes clusters are IPv4 by default.
-The solution is to use the Session Pooler endpoint as it is IPv4 compatible.
+The deletion process removes the connector configuration from Agent Mesh Enterprise but does not affect the external system. Database users, API keys, and other external credentials remain in place, requiring separate cleanup if you no longer need them.
 
 ## Access Control
 
@@ -103,4 +68,4 @@ Connector operations require specific RBAC capabilities. The table below shows t
 | `sam:connectors:update` | Modify connector configurations and credentials             |
 | `sam:connectors:delete` | Remove connectors from the system                           |
 
-For detailed information about configuring role-based access control, see [Setting Up RBAC](../rbac-setup-guide.md).
+For detailed information about configuring role-based access control and assigning capabilities to users, see [Setting Up RBAC](../rbac-setup-guide.md).