Wangsu Terraform Knowledge Base MCP Server

Wangsu Terraform Provider knowledge base retrieval service, providing tool-calling interfaces to clients such as Claude Code via MCP (Model Context Protocol).

What This Is

This is a pure retrieval-type MCP server: it only retrieves document fragments related to the Wangsu Terraform Provider from a vector database, and does not call any LLM on the server side to generate answers. The party that actually "reads the fragments and synthesizes a response" is the caller's own Claude client, consuming the caller's own account quota.

This design has two benefits:

• The server side does not need to configure ANTHROPIC_API_KEY, so the call costs for the whole team are not concentrated on any single person's account

• Smaller attack surface — the only sensitive information the server needs to protect is a single auth token

Related MCP server: NetApp AIDE MCP Server

Architecture

团队成员的 Claude Code 客户端（用自己的账号做推理）
        │
        │ MCP over HTTP，携带 Bearer Token
        ▼
网宿 CDN（HTTPS，证书由网宿托管）
        │
        │ 回源 HTTPS，源站证书校验已关闭
        ▼
Caddy（反向代理，tls internal 自签证书，监听 443）
        │
        │ 转发到本地 8000 端口
        ▼
FastMCP + uvicorn（mcp_server.py）
        │
        │ 向量检索
        ▼
Chroma 向量数据库（本地持久化）

Core Components

Tools

search_wangsu_terraform(question: str) -> str

Retrieves the Wangsu Terraform knowledge base, returning:

1. A fixed block of answer-rule instructions (ANSWER_GUIDANCE) — used to constrain the caller's Claude behavior, preventing hallucinations on Wangsu-specific parameter names/resource names

2. The most relevant retrieved document fragments (default Top 8), each with the source filename and relevance score

The caller's Claude will synthesize the final answer based on this content, and classify questions into three categories per the rules:

• Category A: Wangsu Provider-specific details → must be based on retrieved content; field names not verbatim retrieved must not be fabricated

• Category B: General Terraform/HCL knowledge → can use its own knowledge when retrieved content does not cover it

• Category C: Questions about other cloud vendors → must not apply Wangsu-specific content to other vendors

How to Connect

After obtaining the MCP_AUTH_TOKEN distributed by the administrator, run the following on your local machine (replace <token> with the actual value):

claude mcp add --transport http wangsu-kb https://<你的加速域名>/mcp \
  --header "Authorization: Bearer <token>" -s user

Windows PowerShell users note: the line-continuation character is a backtick ` not \; it is recommended to write the command as a single line to avoid line-continuation parsing issues that could cause the auth header to be lost.

Verify the connection succeeded:

claude mcp list

It should display wangsu-kb: ... (HTTP) — Connected. After that, simply ask Wangsu Terraform-related questions in the conversation, and Claude will automatically call this tool as needed.

Server Deployment

Full deployment steps are in deploy/DEPLOY.md; here is an overview:

1. Create an EC2 instance (Ubuntu 24.04 LTS, t3.small, 8-20GB gp3), attach an Elastic IP

2. Security group only opens 22 (admin IP) and 443 (Wangsu origin-pull IP ranges)

3. Configure Wangsu CDN: origin points to the Elastic IP, HTTPS origin-pull, disable origin certificate verification (the origin uses a self-signed certificate)

4. Upload project files to /opt/wangsu-kb, create a virtual environment and install dependencies

5. Create a dedicated system user wangsu-mcp to run the service (least privilege, not root)

6. /etc/wangsu-mcp/env stores MCP_AUTH_TOKEN and PORT, permissions 600

7. systemd manages the service lifecycle (auto-start on boot, automatic crash restart)

8. Caddy uses tls internal self-signed certificate for reverse proxy, not Let's Encrypt

Operations

View Service Status / Logs

sudo systemctl status wangsu-mcp
sudo systemctl status caddy
sudo journalctl -u wangsu-mcp -f
sudo journalctl -u caddy -f

Update Knowledge Base Content

After locally editing the source documents in the data/ directory, re-run ingest.py to generate a new chroma_db/, sync it to the server, then restart the service:

rsync -avz --exclude '.git' -e "ssh -i your-key.pem" \
  ./chroma_db/ ubuntu@<Elastic IP>:/tmp/chroma_db_new/

# 登录服务器
sudo systemctl stop wangsu-mcp
sudo rm -rf /opt/wangsu-kb/chroma_db
sudo mv /tmp/chroma_db_new /opt/wangsu-kb/chroma_db
sudo chown -R wangsu-mcp:wangsu-mcp /opt/wangsu-kb/chroma_db
sudo systemctl start wangsu-mcp

Rotate / Revoke Tokens

openssl rand -hex 32                          # 生成新token
sudo nano /etc/wangsu-mcp/env                  # 替换 MCP_AUTH_TOKEN
sudo systemctl restart wangsu-mcp

The new token needs to be redistributed to team members via a password manager or private chat; team members need to re-run claude mcp add (first claude mcp remove wangsu-kb, then re-add with the new token).

Note: the token is the only access gate; do not paste it anywhere that would be committed to git, and try to avoid leaving it in plaintext in command-line history (it is recommended to pass it via environment variables or a password manager).

Elastic IP Changes

If the Elastic IP changes, the following three places need to be updated in sync — all are required:

1. The origin IP in the Wangsu console

2. The IP in /etc/caddy/Caddyfile (if the IP is explicitly written in the Caddyfile)

3. The security group 443 inbound rule (if it has been tightened to a specific IP range)

Known Issue: Slow First Load of the Embedding Model

mcp_server.py loads the BAAI/bge-small-en-v1.5 embedding model at startup. If the local cache (/home/wangsu-mcp/.cache/huggingface) does not exist, the service will first download it from the network (~67MB); on download failure it retries 3 times (3s/9s/27s backoff); if all attempts fail, the process exits and systemd automatically restarts to retry.

If the service repeatedly fails to restart, you can manually simulate the wangsu-mcp user's runtime environment to troubleshoot:

sudo -u wangsu-mcp bash -c '
cd /opt/wangsu-kb
set -a; source /etc/wangsu-mcp/env; set +a
./venv/bin/python -c "
from llama_index.embeddings.fastembed import FastEmbedEmbedding
FastEmbedEmbedding(model_name=\"BAAI/bge-small-en-v1.5\")
print(\"加载成功\")
"'

Common causes: the wangsu-mcp user's home directory does not exist or lacks write permission, insufficient disk space, or network connectivity issues.

Security Design Highlights

• The server side does not hold an Anthropic API Key; inference cost and quota are entirely borne by the caller

• MCP_AUTH_TOKEN is generated with openssl rand -hex 32, permissions 600, readable only by the wangsu-mcp user

• The system account wangsu-mcp running the service is a dedicated account with a non-login shell (/usr/sbin/nologin), following the principle of least privilege

• The origin Caddy uses a tls internal self-signed certificate, trusted only for Wangsu CDN origin-pull, not exposed to public browsers

• The MCP SDK's built-in DNS rebinding protection (TransportSecuritySettings) has been configured with the allowed Host / Origin whitelist

License

"Internal use only"