MCP Servers expose REST APIs as tools on the Higress AI Gateway, or proxy existing MCP servers (SSE/StreamableHTTP). Use setup-mcp-server.sh to create/update from YAML templates, or setup-mcp-proxy.sh to proxy existing MCP servers. Built-in templates are at references/mcp-*.yaml.
Gotchas
- Cloud mode (
HICLAW_RUNTIME=aliyun) does not support script-based MCP management — direct admin to the Alibaba Cloud AI Gateway console instead - Auth plugin takes ~10s to activate after server creation/update — always wait and verify with mcporter before notifying Workers
- Always verify end-to-end before notifying Workers — call at least one tool via mcporter to confirm connectivity. Do not push broken tools
- Never echo credentials in chat messages — credentials are stored only in Higress config, Workers access via gateway proxy
- Consumer authorization is a REPLACE operation — when calling the API manually, include ALL consumers (manager + all workers), not just the new one
- All YAML configs must use
accessToken: ""as the credential key — the setup script substitutes the real value - Only notify relevant Workers — do not broadcast to all Workers, only those whose role/task needs the new tool
- MCP Server SSE endpoint always returns 200 — auth is checked on
POST /mcp/<name>/message, not on SSE connect - mcp-proxy only supports
httpandssetransport —stdioservers cannot be proxied through the gateway
Operation Reference
Read the relevant doc before executing. Do not load all of them.
| Situation | Read |
|---|---|
| Create/update an MCP server or rotate credentials | references/create-update-server.md |
| Generate YAML for a custom API integration | references/custom-yaml-guide.md |
| List, inspect, delete servers, or manage consumer access manually | references/api-commands.md |
| Proxy an existing MCP server (SSE/HTTP) | references/setup-mcp-proxy.md |
| Need the GitHub MCP tool definitions | references/mcp-github.yaml |