IMA Multi-User MCP Server

Multi-user MCP proxy for Tencent IMA OpenAPI (Notes + Knowledge Base).

• Request-header credential passthrough: Each request carries the user's own Client ID + API Key; the server stores nothing.

• Stateless Streamable HTTP: Multi-user concurrency is naturally isolated, restarts are seamless, and horizontal scaling is supported.

• client_id allowlist admission: Only registered Client IDs are usable; file changes take effect immediately without restart.

• 17 tools: 6 notes + 9 knowledge base + raw_call fallback + connectivity check

Design Origins

This project was not designed in a vacuum; it is a "multi-user refactor" of existing community solutions. The design lineage is as follows:

Problem to solve: Tencent IMA's notes/knowledge base capabilities were originally single-user, single-instance. The goal is to turn it into a server that serves multiple users simultaneously—each user connects with their own Tencent account credentials, the server doesn't hold keys for anyone, and there's zero ops overhead for device or user changes.

Three approaches investigated (mainstream patterns for multi-user MCP Servers):

Three key references:

1. amberpepper/ima-mcp (TypeScript)—the direct blueprint for this project's 15 IMA OpenAPI endpoint paths, request body structures, and upstream request header names (ima-openapi-clientid / ima-openapi-apikey / ima-openapi-ctx), all verified one by one. This project replicates its tool design but replaces its "single-user stdio + environment variable credentials" architecture with "multi-user Streamable HTTP + request header credentials." Its file upload tool, which depends on server-local paths, was removed because it is meaningless for remote users.

2. LRGEX/notion-mcp—the source of the stateless multi-user pattern where "every tool first retrieves credentials from the request header, and a new client is created per request and discarded after use."

3. github/github-mcp-server—reference for containerization, tool grouping, and engineering structure of an official MCP Server; its OAuth-dependent multi-user approach was deliberately set aside in favor of the minimal "bring your own key, zero storage" model.

Two iterations of the authentication design:

• The initial draft used two-layer authentication (admin admission token + user IMA credentials), later simplified to credentials as identity—the user's IMA credentials are themselves the sole identity credential, with Tencent's API response (401) serving as verification; no separate admission token is issued.

• Further evolved into a client_id allowlist: the local side determines "eligibility" (whether allowed), while Tencent determines "authenticity" (whether the key is valid)—each gate does its own job. client_id was chosen for the allowlist over api_key because IMA API Keys expire/can be reset, whereas client_id is a stable identity identifier.

Protocol foundation: MCP Streamable HTTP transport + stateless mode (stateless_http=True); each request is independent with no session table, natively supporting concurrency and horizontal scaling.

Related MCP server: Productboard MCP — Curve & Flex

Quick Deployment (Docker Compose)

cd ~/ima-mcp-server
cp -n .env.example .env
# 编辑 config/allowed_clients.txt，把允许的 client_id 写进去（每行一个）
docker compose build
docker compose up -d
docker compose logs -f --tail=50   # 看到 "就绪" 与白名单条数即成功

The service listens on 127.0.0.1:8044 (only accessible to the same-host reverse proxy/public ingress layer). To expose it directly, change the ports in docker-compose.yml to "0.0.0.0:8044:8044" (and ensure TLS on the link).

Allowlist Management

• Edit config/allowed_clients.txt: one client_id per line; text after # is a comment

• Changes take effect immediately (hot-reloaded by file modification time) without restarting the container

• File exists but has no valid entries → all requests rejected (fail-closed)

• File deleted and IMA_ALLOWED_CLIENTS is empty → open mode

Smoke Test

bash tests/smoke.sh <你的client_id> <你的api_key>

Expected: 1) initialize succeeds; 2) tools/list returns 17 tools; 3) calls without credentials return a missing-credential error; 4) real credentials return status ok.

Client Configuration (Chatbox Example)

• Type: Remote MCP / Streamable HTTP

• URL: http://<server-ip>:8044/mcp (use https if the upstream has TLS)

• Request headers:

  • X-Ima-ClientId: the user's own client_id

  • X-Ima-ApiKey: the user's own api_key

Note: IMA API Keys may expire; when invalid, reset at https://ima.qq.com/agent-interface and update the client request headers.

Upgrade

docker compose build && docker compose up -d

FAQ

License

MIT