Alibaba Cloud SLS MCP Proxy

简体中文 | English

alibabacloud-sls-mcp-proxy connects local Model Context Protocol (MCP) clients to Alibaba Cloud Simple Log Service (SLS). It signs each upstream request with your Alibaba Cloud credentials while keeping the MCP connection on your machine.

The proxy supports:

• stdio transport for desktop MCP clients and IDEs;
• a loopback-only Streamable HTTP transport;
• static AccessKey credentials with an optional STS token;
• credentials from an Alibaba Cloud CLI profile, including refresh of temporary credentials close to expiration.

Requirements

• Python 3.10 or later;
• Alibaba Cloud credentials that are authorized to use the SLS MCP service;
• Alibaba Cloud CLI when using --profile.

uv is recommended for running the proxy without a permanent installation.

Quick start

Use an Alibaba Cloud CLI profile

Configure a profile with Alibaba Cloud CLI, then start the proxy with its name:

uvx alibabacloud-sls-mcp-proxy@latest --profile default

stdio is the default transport. The proxy reads MCP JSON-RPC messages from stdin, writes responses to stdout, and sends logs to stderr.

The following MCP client configuration starts the proxy on demand:

{
  "mcpServers": {
    "alibabacloud-sls": {
      "command": "uvx",
      "args": [
        "alibabacloud-sls-mcp-proxy@latest",
        "--profile",
        "default"
      ]
    }
  }
}

If a desktop application cannot find uvx, replace uvx with its absolute path.

Use credentials from environment variables

Without --profile, provide both of these environment variables in the process that starts the proxy:

• ALIBABA_CLOUD_ACCESS_KEY_ID
• ALIBABA_CLOUD_ACCESS_KEY_SECRET

For temporary credentials, also provide ALIBABA_CLOUD_SECURITY_TOKEN. Then run:

uvx alibabacloud-sls-mcp-proxy@latest

Prefer a secret manager or the MCP client's environment configuration over putting credentials directly on a command line.

Use the local HTTP transport

To expose an MCP endpoint to another local process:

uvx alibabacloud-sls-mcp-proxy@latest \
  --profile default \
  --transport http \
  --port 8080 \
  --endpoint sls.aliyuncs.com

Connect the MCP client to http://127.0.0.1:8080/mcp. The listener always binds to the loopback interface and is not exposed to the network.

Use with Qoder CLI and Codex

Both Qoder CLI and Codex support stdio and Streamable HTTP MCP servers. Use only one transport for a given server entry:

• stdio (recommended): the client starts and stops its own proxy process;
• HTTP: you start one loopback proxy process separately and keep it running while clients use it.

The examples below use the existing Alibaba Cloud CLI profile named default. Make sure uvx and aliyun are available in the PATH inherited by the MCP client.

stdio mode (recommended)

Qoder CLI

Register the proxy for all local projects:

qodercli mcp add \
  --scope user \
  --transport stdio \
  alibabacloud-sls \
  -- uvx alibabacloud-sls-mcp-proxy@latest --profile default

qodercli mcp list

Use --scope local instead to keep the configuration local to the current project. If Qoder CLI is already running, enter /mcp reload in the session after adding or changing the server.

Codex

Register the proxy in the Codex MCP configuration:

codex mcp add alibabacloud-sls \
  -- uvx alibabacloud-sls-mcp-proxy@latest --profile default

codex mcp list

In the Codex TUI, use /mcp to check that the server is active. Start a new Codex session if an existing session does not pick up the new configuration.

Streamable HTTP mode

First, start the proxy in a separate terminal and keep it running:

uvx alibabacloud-sls-mcp-proxy@latest \
  --profile default \
  --transport http \
  --port 8080

Then register its loopback URL with the client.

For Qoder CLI:

qodercli mcp add \
  --scope user \
  --transport http \
  alibabacloud-sls \
  http://127.0.0.1:8080/mcp

qodercli mcp list

For Codex:

codex mcp add alibabacloud-sls \
  --url http://127.0.0.1:8080/mcp

codex mcp list

The HTTP listener is loopback-only, so clients on another machine cannot connect to it. If an entry with the same name already exists, remove it first with qodercli mcp remove alibabacloud-sls or codex mcp remove alibabacloud-sls, or choose a different name.

Credential selection

The proxy selects exactly one credential provider:

1. A non-empty --profile or ALIBABA_CLOUD_PROFILE selects an Alibaba Cloud CLI profile.
2. Profile mode is mutually exclusive with --access-key-id, --access-key-secret, --sts-token, and their environment variables. If both modes are configured, the proxy fails at startup without combining or ignoring credentials.
3. Without a profile, the proxy requires both the AccessKey ID and AccessKey secret from command-line options or environment variables.
4. The proxy does not silently fall back between profile and static credential modes.

When a profile contains an expiration time, the proxy asks Alibaba Cloud CLI to refresh temporary credentials shortly before they expire.

Command-line options

Option	Environment variable	Default	Description
--access-key-id	ALIBABA_CLOUD_ACCESS_KEY_ID	none	AccessKey ID used without a profile.
--access-key-secret	ALIBABA_CLOUD_ACCESS_KEY_SECRET	none	AccessKey secret used without a profile.
--profile	ALIBABA_CLOUD_PROFILE	none	Alibaba Cloud CLI profile. Mutually exclusive with all static credential settings.
--sts-token	ALIBABA_CLOUD_SECURITY_TOKEN	none	Optional STS token for static credential mode.
--endpoint	MCP_UPSTREAM_ENDPOINT	sls.aliyuncs.com	SLS MCP endpoint. A host without a scheme uses HTTPS.
--transport	none	stdio	Local transport: stdio or http.
--port	MCP_PROXY_PORT	8080	Listen port for HTTP transport.
--headers KEY=VALUE	none	none	Extra upstream header; repeat the option to add more than one. Do not use it for credentials.
--timeout	none	120	Total request timeout in seconds.
--connect-timeout	none	10	Connection timeout in seconds.
--read-timeout	none	same as --timeout	Socket read timeout in seconds.
--retries	none	0	Number of retries after an upstream connection failure.
--log-level	none	info	debug, info, warning, or error.
--log-file	none	none	Also write logs to this local file.
--version	none	—	Print the current version and exit.

Run uvx alibabacloud-sls-mcp-proxy@latest --help to see all supported options.

Security notes

• Prefer an Alibaba Cloud CLI profile or environment variables over command-line credential options, which may be visible in shell history or the local process list.
• Remote endpoints must use HTTPS. Plain HTTP is accepted only for loopback addresses used in local testing.
• Redirects are not followed.
• Credentials and signed authorization values are not written to logs.
• The stdio transport reserves stdout for MCP protocol messages; logs are written to stderr.
• If every upstream connection attempt fails, stdio returns a JSON-RPC error for requests. Notifications remain response-free as required by JSON-RPC.
• When the service returns a request ID, Tool errors include a final mcp-request-id: <value> line for troubleshooting. Successful Tool results and JSON-RPC protocol errors are unchanged.

Troubleshooting

--profile requires the aliyun CLI

: Install Alibaba Cloud CLI and make sure the aliyun executable is in the starting process's PATH.

aliyun configure get failed

: Aliyun CLI failed for a reason other than its recognized profile-not-found diagnostic. Run aliyun configure get -p <profile> to diagnose the CLI/configuration failure without copying its credential-bearing output into logs.

aliyun profile not found

: The selected --profile or ALIBABA_CLOUD_PROFILE does not exist. Check the name with aliyun configure list or create the profile before restarting the proxy.

--profile/ALIBABA_CLOUD_PROFILE cannot be combined with static credential

: Remove all static AccessKey and STS token options/environment variables when using a profile, or remove the profile setting when using static credentials.

--access-key-id and --access-key-secret are required

: Supply both static credential environment variables, or select a configured profile with --profile.

Authentication errors from the endpoint

: Check that the credentials are active, an STS token has not expired, and the identity has permission to use the SLS MCP service.

HTTP transport forwards request and response Mcp-* headers, including protocol version, method, name, parameter and session headers. Client request values take precedence over matching --header options, regardless of header-name casing.

The local HTTP endpoint returns 405 Method Not Allowed with Allow: POST for GET /mcp; it does not provide a standalone GET SSE stream. SSE responses to POST requests remain supported, and notification responses keep their 202 status.

For requests carrying params._meta["io.modelcontextprotocol/protocolVersion"], both transports fill missing Mcp-Protocol-Version, Mcp-Method, and applicable Mcp-Name headers. Explicit headers are preserved, including empty or conflicting values; the request body is unchanged. No protocol version is guessed for older requests.