Service Channels

Once a Knowledge Retrieval or Q&A service is published, you can integrate it into your application through several channels. The Service Channels page in the console shows the integration details and sample code for each one.

Channel comparison

Channel	Protocol	Best for	Notes
Dash API	REST / SSE	Backend services you own	DashScope HTTP endpoints.
MCP Server	MCP	AI Agent frameworks	Works with Qoder, Claude Code, Codex, and others.
Python SDK	Python	Python apps	Wraps auth, retries, and stream parsing.
Java SDK	Java	Java apps	Pulled in as a Maven dependency.
CLI	Command line	Local debugging, scripts, CI	`kscli` — 34 commands covering Knowledge Base management, retrieval, and chat.
Agent Skill	Skill package	Qoder / Claude Code	Integrate the Knowledge Base as a skill package.
Bailian Agent	Web	Quick validation	Alibaba Cloud Bailian Agent platform.

Dash API

All retrieval and Q&A capabilities are exposed through the DashScope API at https://{workspaceId}.cn-beijing.maas.aliyuncs.com. Authentication:

Authorization: Bearer <API-Key>

Create an API Key in the Console API Key page. The system routes requests to the correct workspace based on the API Key. Main endpoints:

Endpoint	Method	Path
Retrieve	POST	`/api/v1/indices/rag/index/retrieve`
Q&A	POST	`/api/v2/apps/knowledge/chat`
Knowledge search	POST	`/api/v1/indices/knowledge/search`

See the API Reference for the full list.

MCP Server

MCP (Model Context Protocol) is an open protocol that lets AI coding assistants and Agent frameworks call external tools directly. After connecting to the RAG MCP Server, your AI assistant can retrieve from your Knowledge Bases mid-conversation.

Prerequisites

At least one Knowledge Base containing successfully parsed documents.
An API Key.
An MCP-compatible client (Qoder, Claude Code, Codex, etc.).

Setup

Get an API Key

Create an API Key in the Console API Key page. Store it as an environment variable:

export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxx"

Add the MCP Server in your client

Pick the configuration that matches your client:

Qoder / QoderWork
Claude Code
Codex

Open the MCP config file and add:

{
  "mcpServers": {
    "rag_mcp": {
      "type": "streamableHttp",
      "url": "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/mcp",
      "headers": {
        "Authorization": "Bearer ${DASHSCOPE_API_KEY}"
      }
    }
  }
}

Run in your terminal:

claude mcp add --transport http rag-mcp-server \
  https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/mcp \
  --header "Authorization: Bearer ${DASHSCOPE_API_KEY}"

Add to your Codex config:

[mcp_servers.rag_mcp_server]
url = "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/mcp"
http_headers = {
    "Authorization" = "Bearer ${DASHSCOPE_API_KEY}"
}

Codex 0.120.0 and later.

Verify the connection

From your client, try invoking the Knowledge Base. For example, in Claude Code:

Search the knowledge base for "how to create a knowledge base"

If the assistant successfully calls the Retrieve tool and returns matches, the integration is working.

Connection details

Item	Value
Endpoint	`https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/mcp`
Protocol version	MCP 2024-11-05
Transport	Streamable HTTP (POST + GET SSE)
Auth	`Authorization: Bearer <API-Key>`

Tools

Name	Function	Description
`ListIndices`	List Knowledge Bases	Paginated list of Knowledge Bases in the current workspace, filterable by name prefix.
`Retrieve`	Retrieve from a Knowledge Base	Retrieve relevant Chunks with hybrid search and Rerank.

Parameters for Retrieve:

Parameter	Type	Required	Default	Description
`IndexId`	string	Yes	—	Knowledge Base index ID.
`Query`	string	Yes	—	Query text; cannot be empty.
`DenseSimilarityTopK`	integer	No	100	Semantic retrieval recall count, range 0–100.
`SparseSimilarityTopK`	integer	No	100	Keyword retrieval recall count, range 0–100.
`EnableReranking`	boolean	No	true	Whether to apply reranking.
`Rerank.ModelName`	string	No	qwen3-rerank	Rerank model; either `qwen3-rerank` or `qwen3-rerank-hybrid`.

DenseSimilarityTopK + SparseSimilarityTopK must be no less than RerankTopN (default 5). Otherwise the call returns Index.InvalidParameter with the message dense_similarity_top_k + sparse_similarity_top_k >= rerank_top_n. For example, with the default RerankTopN, Dense=1 and Sparse=0 fails, while Dense=3 and Sparse=2 succeeds.

RerankMode, RerankMinScore, RerankTopN, and RerankInstruct on the Rerank object are not available in this version and will return an error if passed. Use EnableReranking and Rerank.ModelName to control reranking.

Parameters for ListIndices:

Parameter	Type	Required	Default	Description
`pageNumber`	integer	No	1	Page number, starting from 1.
`pageSize`	integer	No	10	Items per page.
`indexName`	string	No	—	Filter by Knowledge Base name prefix.

Supported clients:

Qoder / QoderWork
Claude Code
Codex (0.120.0+)
Alibaba Cloud Model Studio MCP custom integration (Agent)
Any other MCP-compatible client

CLI

kscli (Knowledge Studio CLI) is the command-line tool for Knowledge Bases. Its 34 commands span Knowledge Base setup, content maintenance, retrieval service management, and retrieval/chat. No code required — it fits local debugging, scripting, and CI/CD pipelines. The console Service Channels page provides the install command and usage examples.

Prerequisites

Node.js 20 or later.
At least one Knowledge Base containing successfully parsed documents.
An API Key.

Quickstart

Install the CLI

npm install -g knowledge-studio-cli

Run kscli --version to verify the installation.

Configure the API Key and workspace

Once written to the config file, later commands no longer need these flags:

kscli config set --key api_key --value sk-xxxxxxxxxxxxxxxx
kscli config set --key workspace_id --value ws-xxxxxxxx

Run your first retrieval

List the retrieval services in the workspace, then retrieve with a service ID:

kscli service list --scene search
kscli search --query "your question" --agent-id aid-xxxxxxxx

The command prints the matched Chunks along with their relevance scores.

Common commands

Command	Purpose
`kscli kb list`	List Knowledge Bases
`kscli doc upload --file <path> --index-id <id>`	Upload files and import them into a Knowledge Base
`kscli service list --scene search`	List retrieval services and their IDs
`kscli search --query <text> --agent-id <id>`	Run a semantic retrieval
`kscli chat --message <text> --agent-id <id>`	Run a RAG conversation

kscli retrieve --index-id is the earlier direct-retrieval command and is now deprecated — it prints a deprecation warning when used. Use search instead: retrieval scope and strategy come from the service config behind --agent-id, which supports multiple Knowledge Bases, routing, and reranking.

For all 34 commands, parameter constraints, and output formats, see the CLI reference.

Agent Skill

In Qoder, Claude Code, and other AI coding tools, you can plug the Knowledge Base in as a skill package:

Download the Skill config file from Service Channels → Agent Skill in the console.
Drop it into your project's .skill/ directory.
The AI coding tool detects it and loads the Knowledge Base retrieval capability.

If your application is built on Dify, Coze, or another third-party platform, see Third-Party Integration for setup guides.

​Channel comparison

​Dash API

​MCP Server

​Prerequisites

​Setup

​Connection details

​Tools

​CLI

​Prerequisites

​Quickstart

​Common commands

​Agent Skill

Channel comparison

Dash API

MCP Server

Prerequisites

Setup

Connection details

Tools

CLI

Prerequisites

Quickstart

Common commands

Agent Skill