Metadata-Version: 2.4
Name: alibabacloud-sls-mcp-proxy
Version: 0.1.0a3
Summary: Local MCP proxy for Alibaba Cloud Simple Log Service
Keywords: alibabacloud,mcp,model-context-protocol,sls
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: Proxy Servers
Requires-Python: >=3.10
Requires-Dist: aiohttp<4,>=3.9
Description-Content-Type: text/markdown

# Alibaba Cloud SLS MCP Proxy

[简体中文](README.zh-CN.md) | 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](https://www.alibabacloud.com/help/en/cli/) when using
  `--profile`.

[`uv`](https://docs.astral.sh/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:

```sh
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:

```json
{
  "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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

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

Then register its loopback URL with the client.

For Qoder CLI:

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

qodercli mcp list
```

For Codex:

```sh
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.

## 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`

: Check that the selected profile exists and contains usable credentials.

`--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.
