Connector management
Data is scattered across multiple engines and self-managed systems. Granting access to each system individually and exporting data for analysis is costly. Connectors provide unified access to data sources and external tools. Once registered, a connector can be reused over the long term, and agents invoke it on demand without moving data in advance. Connector management centralizes registration, verification, health checks, and decommissioning.
How it works
ADA provides two types of connectors. Choose based on whether the target system is a cloud engine directly supported by ADA.
-
Big data engine connectors: Directly connect to engine instances that already exist under your account. After registration, the database and table structures in the instance can be browsed in Data Catalog.
-
MCP service connectors: Connect to tool-providing servers through the Model Context Protocol (MCP), covering self-managed business systems, third-party capabilities, and official MCP servers.
Connector availability is determined by several independent layers. A failure at any layer causes invocation to fail, but symptoms differ. The management plane (probe) shows whether the probe handshake succeeded and the number of discovered tools. The authentication status shows the credential expiration time and remaining validity period.
When the connection is healthy but authentication has expired, the tool list still shows tools as discovered, yet invocations are rejected. This is the purpose of the layered display: first identify which layer is abnormal, then decide whether to re-probe, re-authenticate, or update the configuration.
Data Catalog allows you to browse metadata of connected instances in a hierarchy from connector to column. Being able to see a table in Data Catalog and being able to query its data are two independent things: the latter also requires passing row-level and column-level rules defined by data access control policies.
Usage notes
Instances connected through big data engine connectors must already exist under the current Alibaba Cloud account and be visible in the selected region. ADA does not create engine instances. Currently supported engines include MaxCompute, Hologres, Serverless StarRocks, ClickHouse, SelectDB, and RDS MySQL. Other data sources must be connected as MCP services.
The remote address of an MCP service must use HTTPS, and the address cannot contain a username or password. Services using the stdio transport run in a network-isolated sandbox and can only use libraries and commands available in the runtime environment. The startup process cannot install dependencies over the network.
The ownership of a connector is determined at registration. You can choose to make it visible only to yourself or to all members within the tenant. This setting cannot be changed after saving. Ownership determines which members can mount the connector in a session, but it does not relax data access control policy constraints. The list provides two tabs: Connector Templates and My Connectors. Editing and disabling are limited to maintainers. Official connectors are read-only.
Available operations vary by connector type. Only MCP services with remote transport support probe and authentication operations.
|
Connector type |
Available operations |
|
MCP services with remote transport |
Re-probe, authenticate, disconnect, force reconnect, edit configuration |
|
MCP services with stdio transport |
Edit configuration |
|
Big data engines |
Edit configuration |
Register a connector
Register a big data engine connector
-
Initiate registration. On the Connectors page, click Register Connector. Set Service Type to Big Data Engine, and then select the Engine Type. For character and length limits of the name, see Quotas and limits. The name cannot be changed after creation.
-
Confirm the region. The region defaults to the region of the current console. The instance drop-down list loads only instances in that region. If the list is empty, verify that the instance has been created and that the current account has view permissions.
-
Select an instance and specify the data location. For MaxCompute, enter the project name and endpoint. The endpoint is automatically populated based on the selected region. For other engines, enter the database name.
-
Specify the access identity. Hologres provides two Access Mode options: Visitor Identity uses the temporary credentials of the current logged-in user and does not require password maintenance, which is suitable when members already have permissions on the engine side; Specified Identity requires a username and password to access the engine with a fixed service account. For other engines, enter a username and password.
-
Enter a description and save. The description should include data ownership, business scope, and typical use cases. For example, "E-commerce operations team Hologres instance for querying real-time order and inventory data." A missing or overly generic description may cause the agent to select the wrong connector from multiple options. Click Add to submit.
Access credentials should use a read-only account with permissions limited to the databases and tables required for analysis. For scenarios that require write access, register a separate connector and manage it independently from read-only connectors to prevent analysis sessions from accidentally triggering write operations.
Register an MCP service connector
Configuration differences are focused on the transport protocol: for remote services, provide the address; for local scripts, specify the startup method.
-
Select the service type and transport protocol. Set Service Type to MCP Service, and then select the Transport Protocol. Use streamable_http or sse for remote services. Use stdio for services that run locally in a sandbox as scripts or commands.
-
Enter the remote address. For remote protocols, enter the address in the URL field. You can add fixed headers in Custom Request Headers as needed.
-
Configure the local startup method. For the stdio protocol, select script mode or custom command mode in Startup Method. In script mode, you write the script directly in the form. In custom command mode, you specify the executable program and command parameters.
-
Confirm the authentication method. Keep the default settings. The system automatically discovers the authentication service from the MCP address, and authentication credentials are managed by the server. Enable "Manual OAuth Configuration" only when you need to override the auto-discovery results.
-
Probe the tool list. For remote protocols, click Re-probe on the details page after saving. If the status indicates that authentication is required, click Authenticate to complete authorization. The stdio protocol does not support probe or authentication operations. After saving, verify by performing an actual invocation in a conversation.
Wrap a self-managed system as an MCP service
Self-managed databases and unsupported engines cannot be connected directly. The target system must first expose an MCP service. The additional effort involves implementing or deploying an MCP server. The benefit is that the capabilities of your own systems can be invoked by agents on demand, without engine type restrictions.
Whether an agent can correctly use a tool depends on how clearly the tool is described. When implementing a server according to the MCP specification, declare the name, description, input parameters, and output structure for each tool individually. A tool should be scoped to a single-step operation. Bundling multiple steps into one tool makes failure diagnosis difficult.
The server validates the caller's identity on its own, and the credentials passed by ADA are configured with least-privilege access. Errors are returned as structured information that describes the failure reason and suggested action.
Write-operation tools should declare their impact scope, and ADA should keep per-invocation confirmation enabled rather than setting them to always allow. For more information, see approval and manual confirmation.
Verify and inspect connection status
Probing and real invocation verify different layers. After onboarding, both steps must be completed before the connector can be used by scheduled tasks. During routine inspections, check the status from top to bottom by layer.
-
Check the list status. "Active" indicates that the configuration is complete and the connection is healthy. For any other status, go to the details page to identify the specific layer that has an issue.
-
Check the layered status. Go to the details page to view the details. The displayed content varies by connector type.
-
Remote-transport MCP services: Display the connection status, management-plane probe results, and authentication status.
-
stdio-transport MCP services: Display the startup method and configuration. Probe and authentication statuses are not shown.
-
Big data engines: Display the service type, region, activation status, and connection configuration.
-
-
Re-probe. If the probe result is abnormal, click Re-probe to re-fetch the tool list and refresh the tool count and probe time. This is useful for syncing after the server updates tool definitions.
-
Re-authorize. If the authentication is about to expire, click Authenticate to renew it before expiration and avoid task interruptions.
-
Force reconnect. Use this when the connection is abnormal and probing does not respond. This rebuilds the connection to the target service.
-
Verify with a real invocation. For an engine connector, initiate a scoped data retrieval. For an MCP service, call a read-operation tool and verify that the returned result matches the expected output.
Steps 3 through 5 apply only to remote-transport MCP services. If the network is unreachable, first check whether public network access is enabled for the instance and verify the allowlist settings.
Maintain and decommission connectors
Update connection configuration
After instance migration, password rotation, or endpoint changes, you must update the configuration accordingly. Otherwise, scheduled tasks that depend on the connection will fail consecutively, and the failures will not surface until the scheduled execution time. On the details page, click Edit Configuration to update the relevant fields.
Leaving a credential field empty means retaining its current value. You do not need to re-enter all credentials when updating only one of them. After saving, re-probe to confirm that the new configuration takes effect, and then perform a real invocation in a conversation.
Configuration changes take effect immediately for all sessions and tasks that use the connector. In production environments, schedule updates outside of task execution windows.
Disable and disconnect
Disable connectors that are no longer needed instead of deleting them directly, so that historical execution records remain traceable. Before disabling a connector, make sure that no running scheduled tasks depend on it, because tasks discover that a connection is unavailable only at execution time.
For MCP service connectors, you can disconnect them. After disconnection, the configuration is retained but no invocation requests are processed. To restore, reconnect and re-probe.
Apply to production environments
Organize connectors by business domain instead of sharing a single high-privilege connection. Grant credentials only read access to the databases and tables required by the specific business domain. Register write operations separately and restrict the mountable scope so that a credential leak affects only a single business domain.
Include credential expiration in your routine maintenance plan. The remaining validity period of an authentication entry is visible. Proactively handling expiration before it occurs is far less costly than recovering after task failures. When a connector is associated with multiple agents, a credential change affects all associated parties.
Configure health checks and alerts for MCP services in production environments. When a connection is abnormal, the task logs provide the failure reason, but the time of discovery depends on when the task is triggered.
Complete data access control policy configuration before onboarding connectors at scale. If the order is reversed, a window exists where data is visible before the policy is tightened. For more information, see security and compliance.
Quotas and limits
|
Limit |
Description |
|
Ownership |
Determined during registration and cannot be modified after saving. You can set the visibility to yourself only or to all members within the tenant. |
|
Connector name |
Lowercase letters, digits, underscores, or hyphens. Must start with a letter. Maximum of 64 characters. Cannot be modified after creation. |
|
stdio services |
The command, parameters, script content, and environment variables each have a maximum length. If any limit is exceeded, the save operation is rejected and the form displays the specific limit. |
|
Data Catalog |
Only metadata browsing is provided. Previewing data rows in tables and global table search across connectors are not supported. |
|
Cross-region instances |
The instance list is loaded based on the selected region. To view instances in a different region, switch the region. |
|
Edit permissions |
Only connector maintainers can edit or disable connectors. Official connectors are read-only. |
FAQ
-
Q: What do I do if the instance drop-down list is empty?
A: Check the following three items in order: whether the selected region matches the region where the instance resides, whether the instance has been created and is in the running state, and whether the current logon identity has the view permission on the instance. The list is also empty if the RAM user does not have the read-only permission on the corresponding engine.
-
Q: The connectivity test passes but invocations fail. How do I troubleshoot this issue?
A: The connectivity test only verifies the management-plane handshake and does not cover authorization or parameters. First, check whether a data access policy blocks the current identity — this is the most common cause. Then, check whether the query object exists and its name is spelled correctly. Finally, check whether the connector is disabled or the authentication has expired.
-
Q: The connectivity test shows that authentication is required, but authentication still fails after I click Authenticate. What do I do?
A: Check whether the authorization server address of the MCP Server is accessible from the Internet and whether the callback configuration matches the actual domain name. If automatic discovery fails, enable manual OAuth configuration. Make sure that the Scope matches the permission scope declared on the server.
-
Q: Will tasks automatically retry after authentication expires?
A: No. After authentication expires, invocations are rejected and the task is recorded as failed in the execution history. After you complete authentication again, the task resumes normally at the next trigger. The current failure is not automatically rerun.
-
Q: If I modify the connection configuration, will ongoing sessions be affected?
A: Yes. Configuration changes take effect immediately. Ongoing sessions use the new configuration at the next tool invocation. If an invocation fails in the current session after you change the credentials, start a new conversation.