Alicloud

Alibaba Cloud

Use the unified MCP server for Alibaba Cloud HTTP APIs, Enterprise ACR Registry operations, and guarded NLS HTTPS/WebSocket tasks. The gateway signs general OpenAPI with ACS3, legacy RPC/ROA V2, DataHub, OpenSearch, MaxCompute ODPS V2/V4, Function Compute FC, OSS, SLS, MNS, RocketMQ 4.x MQ HTTP, and Tablestore protocols. For ACR and NLS it derives documented temporary credentials internally from the same RAM AKSK/STS chain. It never executes Alibaba Cloud CLI, Docker, or a credential helper.

Workflow

1. Call cloud_provider_status with provider="alicloud"; treat available as HTTP adapter readiness and credential_status=unverified as pending live authentication.
2. Use alicloud_api_discover for official OpenAPI and product-protocol references, then verify method, endpoint, action, version, query, headers, and body in the product API metadata.
3. Use alicloud_api_read only for actions classified as read-only (Describe*, List*, Get*, Query*, and similar).
4. For other actions, obtain explicit human approval for the account, region, resources, action, and effect; then use alicloud_api_mutate(force=true).
5. Secret-resource operations require the separate sensitive gate. STS role/session credentials, login profiles, AccessKey creation, and other credential issuance/export actions are never exposed by the gateway.
6. Do not pass AccessKeys, security tokens, or authorization data as arguments or headers.

MCP arguments

• auth_scheme: acs3 (default) for current general OpenAPI; rpc|roa for legacy V2 APIs; datahub for DataHub; opensearch for OpenSearch V3 AccessKey APIs; odps4 for current MaxCompute project/data/Tunnel APIs and odps for their legacy V2 signature; fc for classic Function Compute resources and old /2016-08-15/proxy/... triggers, fc3 for current fcapp.run HTTP triggers, and fc-custom for signature-enabled custom domains; oss4 (recommended) or oss (V1) for OSS Header-signed operations; sls|sls4 for SLS; mns for Simple Message Queue; mq for RocketMQ 4.x AKSK HTTP publish/consume sessions; acr-registry for Enterprise ACR Docker/OCI Registry V2 with internal RAM temporary credentials; ots|ots4 for Tablestore; nls-rest|nls-ws for official Intelligent Speech Interaction HTTPS or WebSocket gateways.
• service: product/signing code, such as ecs, rds, vpc, ram, or oss.
• operation: exact action name used by ACS3 headers and read/write classification.
• api_version: required for ACS3, RPC, and ROA, such as 2014-05-26; optional for SLS/MNS/OTS, whose official defaults are 0.6.0, 2015-06-06, and 2015-12-31.
• region: required by ODPS4, OSS4, SLS4, and OTS4 and recommended as operation context.
• method and url: exact official Alibaba Cloud HTTPS request.
• parameters: optional scalar query parameters; use body or body_file for request payloads.
• response_file: new approved-root file for OSS objects, exports, or other large responses. Use the documented Range header above the configured per-call limit; existing files are never overwritten.

Example read: alicloud_api_read(auth_scheme="acs3", service="ecs", operation="DescribeInstances", api_version="2014-05-26", region="cn-hangzhou", method="POST", url="https://ecs.cn-hangzhou.aliyuncs.com/", parameters={"RegionId":"cn-hangzhou","PageSize":20}).

Legacy RPC example: alicloud_api_read(auth_scheme="rpc", service="baas", operation="DescribeFabricOrganization", api_version="2018-12-21", method="GET", url="https://baas.aliyuncs.com/", parameters={"Format":"JSON","OrganizationId":"..."}). The adapter adds Action, Version, timestamp, nonce, AK ID, optional RAM SecurityToken, and signature; optional Format remains caller-selected because documented defaults differ by product. For operations whose metadata puts parameters in formData, pass an application/x-www-form-urlencoded body; those fields are included in the signature without being copied into the URL. RPC accepts only the documented root path and GET or POST, and repeated parameter names are rejected.

Legacy ROA example: alicloud_api_read(auth_scheme="roa", service="pds", operation="ListDrives", api_version="v2", method="POST", url="https://<domain-id>.api.aliyunpds.com/v2/drive/list", body={"limit":20}). The adapter signs the exact path/query and body, derives Content-MD5, and internally adds Date, nonce, version, optional RAM x-acs-security-token, and Authorization. Do not provide those controlled headers. ROA supports the documented GET, POST, PUT, and DELETE methods.

DataHub example: alicloud_api_read(auth_scheme="datahub", service="datahub", operation="ListProjects", method="GET", url="https://dh-cn-hangzhou.aliyuncs.com/projects"). The adapter defaults x-datahub-client-version to 1.1 (override with api_version), signs the exact resource path/query, and internally adds Date, optional RAM x-datahub-security-token, and DATAHUB authorization. Project, topic, shard, connector, record, and subscription endpoints use the same scheme.

OpenSearch example: alicloud_api_read(auth_scheme="opensearch", service="opensearch", operation="Search", method="GET", url="https://opensearch-cn-hangzhou.aliyuncs.com/v3/openapi/apps/<app>/search", parameters={"query":"config=start:0&&query=default:'term'"}). The adapter RFC3986-canonicalizes non-empty search parameters, generates the required timestamp-plus-random nonce, and adds ISO-8601 Date, optional X-Opensearch-Security-Token, and OPENSEARCH authorization. Body requests receive the documented lowercase hexadecimal Content-MD5; non-GET request query parameters are not part of the OpenSearch push-resource signature.

MaxCompute example: alicloud_api_read(auth_scheme="odps4", service="maxcompute", operation="ListProjects", region="cn-hangzhou", method="GET", url="https://service.cn-hangzhou.maxcompute.aliyun.com/api/projects"). Use the exact public, VPC, or interconnected endpoint documented for the project region; Tunnel calls use the matching dt.<region>.maxcompute.aliyun.com endpoint. The adapter signs the canonical ODPS resource (the service endpoint's /api base is not part of that resource), derives the current V4 key from date/region/service, and internally adds Date, optional RAM Authorization-Sts-Token, and ODPS authorization. Use auth_scheme="odps" only for an official endpoint that still requires the legacy V2 HMAC-SHA1 signature. Do not auto-retry a mutation with the other scheme.

Classic Function Compute example: alicloud_api_read(auth_scheme="fc", service="fc", operation="ListServices", method="GET", url="https://<account-id>.cn-hangzhou.fc.aliyuncs.com/2016-08-15/services"). The adapter derives a lowercase hexadecimal body MD5 when a body exists, adds RFC 1123 Date and optional RAM X-Fc-Security-Token, canonicalizes all caller-supplied non-credential x-fc-* operation headers, and generates FC HMAC-SHA256 Authorization. Classic resource requests sign the decoded path and discard query from the signature; old /2016-08-15/proxy/... calls sign the decoded path plus all decoded key=value pairs sorted on separate lines.

Current HTTP Trigger example: alicloud_api_read(auth_scheme="fc3", service="fc", operation="InvokeHTTPTrigger", method="POST", url="https://<trigger-id>.<region>.fcapp.run/hello", parameters={"foo":"bar"}, body="hello world"). This is the current official ACS3-HMAC-SHA256 Trigger protocol: the adapter signs the method, escaped path, single-valued query, Content-Type, X-Acs-Date, and optional X-Acs-Security-Token with the official empty payload field; it does not add OpenAPI Action/Version headers. Repeated query names are rejected because the official signing SDK represents each name with one value.

Signature-enabled Function Compute custom domains use auth_scheme="fc-custom", the custom HTTPS URL, and the documented acs HMAC-SHA1 canonical request. The operator must first add that exact hostname to CLOUD_SKILLS_ALIBABA_ALLOWED_ENDPOINT_HOSTS; MCP arguments cannot expand the allowlist. fc-custom signs Accept, optional Content-MD5, Content-Type, Date, RAM STS token, escaped path, and sorted single-valued query. Caller-supplied presign and credential parameters remain forbidden for all three schemes.

OSS example: alicloud_api_read(auth_scheme="oss4", service="oss", operation="GetObject", region="cn-hangzhou", method="GET", url="https://<bucket>.oss-cn-hangzhou.aliyuncs.com/<object>", response_file="<approved-root>/object"). Use auth_scheme="oss" only when an active integration still requires V1 HMAC-SHA1 Header authentication. V1 derives the bucket from the official virtual-hosted endpoint (or the first path component on an official path-style endpoint), signs only the documented case-sensitive subresource/query names, and injects Date plus optional RAM X-Oss-Security-Token; repeated signed query names are rejected. V4 requires region. POST policy signatures and presigned URLs deliberately remain outside the MCP surface because they create transferable authorization artifacts; use normal Header-signed PutObject/multipart operations through the approval gate instead.

SLS example: alicloud_api_read(auth_scheme="sls4", service="sls", operation="ListLogstores", region="cn-hangzhou", method="GET", url="https://<project>.cn-hangzhou.log.aliyuncs.com/logstores"). For protobuf log ingestion, pass the encoded body through body_file and its documented non-auth headers such as Content-Type and x-log-bodyrawsize; signing headers are server-controlled.

MNS example: alicloud_api_read(auth_scheme="mns", service="mns", operation="ListQueues", method="GET", url="https://<account-id>.mns.cn-hangzhou.aliyuncs.com/queues"). MNS request bodies are XML; when a body is present and no content type is supplied, the adapter uses application/xml.

RocketMQ 4.x HTTP example: alicloud_api_mutate(auth_scheme="mq", service="rocketmq", operation="ConsumeMessages", method="GET", url="https://<account-id>.mqrest.<region>.aliyuncs.com/topics/<topic>/messages", parameters={"consumer":"<group>","ns":"<instance>","numOfMessages":16,"waitseconds":30}, body={"settlement":"acknowledge"}, response_file="<approved-root>/rocketmq.ndjson", force=true). All four MQ operations are mutation-only. PublishMessage builds official XML from a bounded body plan; ConsumeMessages|ConsumeOrderly|ConsumeHalfMessages keep every ReceiptHandle internal and perform acknowledge, commit, or rollback in the same invocation before atomically publishing sanitized NDJSON. release intentionally leaves a normal/order message for broker redelivery. Standalone handle operations, caller headers, HTTP, and body files are rejected. RocketMQ 5.x control-plane resources remain reachable through ACS3, but its public data plane uses instance username/password/ACL users rather than the permitted RAM AKSK/IAM chain, so it is not a public MCP credential mode.

ACR Enterprise Registry example: alicloud_api_read(auth_scheme="acr-registry", service="acr", operation="ListTags", region="cn-hangzhou", registry_instance_id="cri-xxxxxxxx", method="GET", url="https://<instance-name>-registry.cn-hangzhou.cr.aliyuncs.com/v2/team/app/tags/list", parameters={"n":20}). Use the exact default public or -registry-vpc Enterprise endpoint; first operator-pin an official custom domain in CLOUD_SKILLS_ALIBABA_ALLOWED_ENDPOINT_HOSTS. The server signs the fixed cr/2018-12-01 GetAuthorizationToken RPC, keeps its temporary username/password internal, validates the exact region-bound dockerauth, dockerauth-ee, VPC variant, Zhangjiakou special form, or same-Registry takeover Bearer realm/service, requests exact target and optional source repository scopes, and sends only the internal Bearer token to the data request. Manifest/blob upload, delete, or mount uses alicloud_api_mutate(force=true). Blob reads may follow only bounded same-region OSS 307 redirects with Authorization removed. Do not pass Authorization, /v2/token, a signed OSS URL, login password, or challenge parameters. Personal Edition cannot use GetAuthorizationToken and therefore is outside this AKSK/IAM-only entrypoint.

Tablestore data management is protobuf over direct HTTP, not ACS3. Encode the exact operation request with Alibaba's published .proto definitions, pass it through body_file, and call the operation path with POST, for example alicloud_api_read(auth_scheme="ots4", service="ots", operation="ListTable", region="cn-hangzhou", method="POST", url="https://<instance>.cn-hangzhou.ots.aliyuncs.com/ListTable", body_file="<approved-root>/ListTableRequest.pb", response_file="<approved-root>/ListTableResponse.pb"). The adapter derives the instance from the first official endpoint label and internally sets the body MD5, OTS headers, V4 derived key, AK ID, signature, and STS token. Decode the response with the matching official response message definition.

NLS WebSocket recognition uses service="nls", method="GET", an official public wss://nls-gateway[-<region>].aliyuncs.com/ws/v1 endpoint, parameters={"appkey":"<project-appkey>"}, and auth_scheme="nls-ws". AppKey identifies the NLS project and is not an authentication secret. Use operation SpeechTranscriber for long real-time recognition or SpeechRecognizer for a short sentence, put the official start payload in body, the finite audio in body_file, and NDJSON events in response_file. Example: alicloud_api_read(auth_scheme="nls-ws", service="nls", operation="SpeechTranscriber", method="GET", url="wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1", parameters={"appkey":"<project-appkey>"}, body={"format":"pcm","sample_rate":16000,"enable_intermediate_result":true}, body_file="<approved-root>/audio.pcm", response_file="<approved-root>/transcript.ndjson"). The adapter creates all 32-character task/message IDs, waits for TranscriptionStarted, paces audio, sends StopTranscription, and publishes only after TranscriptionCompleted.

For streaming text synthesis use operation FlowingSpeechSynthesizer and body={"start":{...},"texts":[...]}. For single or long-text synthesis use SpeechSynthesizer or SpeechLongSynthesizer and put the documented start payload, including text, directly in body. Binary audio is atomically written to response_file; the MCP result also contains bounded provider events. Example: alicloud_api_read(auth_scheme="nls-ws", service="nls", operation="FlowingSpeechSynthesizer", method="GET", url="wss://nls-gateway-cn-beijing.aliyuncs.com/ws/v1", parameters={"appkey":"<project-appkey>"}, body={"start":{"voice":"xiaoyun","format":"mp3","sample_rate":16000},"texts":["第一段。","第二段。"]}, response_file="<approved-root>/speech.mp3"). Never pass token, X-NLS-Token, AKSK, or caller-generated protocol headers; public CreateToken remains blocked even though the NLS adapter calls it internally.

NLS REST short recognition uses auth_scheme="nls-rest", operation ShortSentenceRecognition, exact HTTPS POST /stream/v1/asr, documented scalar parameters including appkey, and audio-only body_file; its bounded JSON result must report status 20000000. REST speech synthesis uses operation SpeechSynthesisREST, exact HTTPS /stream/v1/tts, mandatory response_file, and at most 300 UTF-8 characters: GET places appkey, text, and options in parameters; POST puts those fields in a JSON body. Example: alicloud_api_read(auth_scheme="nls-rest", service="nls", operation="SpeechSynthesisREST", method="POST", url="https://nls-gateway-ap-southeast-1.aliyuncs.com/stream/v1/tts", body={"appkey":"<project-appkey>","text":"欢迎使用。","format":"mp3","sample_rate":16000}, response_file="<approved-root>/speech.mp3"). The adapter injects the internal token only as X-NLS-Token; caller headers and token fields are rejected.

Credentials

Use the official credentials-go chain: RAM/OIDC/ECS role, STS, or ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET. Temporary credentials also use ALIBABA_CLOUD_SECURITY_TOKEN. The adapter derives ACR temporary login/Bearer credentials and NLS temporary tokens from that chain and never returns them. Never put credentials in MCP arguments.

Read references/official-docs.md when profile type, parameter shape, or action name needs verification.