操作教學 · Tutorial 2026 夏季號

skills.tenten.co · Tenten Content Index

教學系列 · MCP 整合

Tenten Content Index
MCP Server
跨平台連線設定

把 index.tenten.dev 的內容資料庫接進 Claude Code、Claude Desktop、Codex CLI 與 Hermes Agent。完成後,寫作 agent 可直接呼叫 search_content,從 2,800+ 篇 Tenten 文章取得內部連結候選。

操作步驟

15min

預估時間

Agent 平台

MCP 工具

全貌與目標

MCP Server 架構與連線模式

Tenten Content Index Center 在 https://index.tenten.dev/api/mcp 提供 MCP server,傳輸協定為 Streamable HTTP,驗證方式為 HTTP header 的 Bearer token。資料庫收錄 Tenten 各頻道的已發佈文章,每筆記錄含 url、title、description、keywords 與 locale,由排程自動更新,client 端不需維護資料。

設定分兩層:先把 API Key 存成環境變數 TENTEN_INDEX_API_KEY,再依平台寫入各自的設定檔。四個平台互相獨立;只需完成實際使用的平台,順序不影響結果。

本教學涵蓋連線設定、五個工具的參數與首次查詢驗證;不涵蓋 server 端部署與金鑰簽發。完成後的狀態:在任一已設定的 agent 內呼叫 search_content,取得依分數排序的文章候選。

MCP 連線 · 完整路徑

金鑰保管→ 平台設定→ 連線驗證→ 查詢內容庫→ Link Building

Claude Code can connect to hundreds of external tools and data sources through the Model Context Protocol (MCP), an open source standard for AI-tool integrations.

— Claude Code 官方文件 · code.claude.com/docs/en/mcp

前置需求

金鑰、網路與平台需求

硬需求只有 API Key 與網路可達性。四個平台依實際使用擇一即可;Node.js 只在 Claude Desktop 的 mcp-remote 中轉時需要。

Tenten Content Index API Key — server 的 API_KEY,向 Tenten 系統維運者索取;所有工具共用同一把金鑰。
可連線 index.tenten.dev 的網路 — MCP endpoint 為 https://index.tenten.dev/api/mcp;未帶金鑰的請求回 HTTP 401。
Node.js 與 npx — Claude Desktop 以 npx 執行 mcp-remote 中轉;其他平台不需要。
目標平台 — Claude Code、Claude Desktop、Codex CLI、Hermes Agent;步驟二至五各自獨立,可只做其中一個。

API Key 等同寫入權限。持有金鑰即可呼叫 submit_url 消耗 Google Indexing API 每日配額;金鑰只存環境變數與本機設定檔,不提交進 git。

步驟一 · 金鑰保管

環境變數 TENTEN_INDEX_API_KEY

將金鑰寫進 shell 設定檔,後續各平台一律以環境變數引用。macOS 預設 shell 為 zsh,設定檔為 ~/.zshrc。

# 寫入 shell 設定檔(金鑰值以維運者提供的為準)
echo 'export TENTEN_INDEX_API_KEY="<你的 API Key>"' >> ~/.zshrc
source ~/.zshrc

# 驗證服務在線:未帶金鑰應回 401
curl -s -o /dev/null -w "%{http_code}" https://index.tenten.dev/api/mcp
      

echo $TENTEN_INDEX_API_KEY 輸出金鑰值;curl 回傳 401。401 表示服務在線且 Bearer 驗證生效;帶正確金鑰的請求才會被接受。

步驟二 · Claude Code

claude mcp add 與 .mcp.json

個人使用以 CLI 一行完成,寫入 local scope(僅本人、僅當前專案)。團隊共用改用 --scope project,設定寫進專案根目錄的 .mcp.json;依官方文件,.mcp.json 的 url 與 headers 支援 ${VAR} 環境變數展開,金鑰不會出現在檔案內容中。

# local scope(預設)
claude mcp add --transport http tenten-index https://index.tenten.dev/api/mcp \
  --header "Authorization: Bearer $TENTEN_INDEX_API_KEY"
      

{
  "mcpServers": {
    "tenten-index": {
      "type": "http",
      "url": "https://index.tenten.dev/api/mcp",
      "headers": { "Authorization": "Bearer ${TENTEN_INDEX_API_KEY}" }
    }
  }
}
      

/mcp 清單出現 tenten-index 且狀態為已連線。工具清單含 search_content、submit_url、check_status、quota_report、list_recent 五項。

步驟三 · Claude Desktop

mcp-remote 中轉設定

依 Claude 官方說明,自訂 connector 僅提供 remote MCP server URL 與 OAuth 欄位,無法填自訂 Bearer header。Claude Desktop 改走本機設定檔,以 mcp-remote 中轉並附上 Authorization header。

在「Settings > Developer」啟用開發者設定,編輯 claude_desktop_config.json(macOS:~/Library/Application Support/Claude/claude_desktop_config.json;Windows:%APPDATA%\Claude\claude_desktop_config.json),存檔後重啟 Claude Desktop。Authorization:${AUTH_HEADER} 冒號前後不留空格;依 mcp-remote 文件,Windows 版 args 內的空格未正確跳脫,含空格的值放進 env 變數。

{
  "mcpServers": {
    "tenten-index": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://index.tenten.dev/api/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer <你的 API Key>" }
    }
  }
}
      

重啟 Claude Desktop 後,要求 Claude 呼叫 quota_report 回傳 JSON。回應含 googleQuota 與當日用量即代表連線與驗證成功。

步驟四 · Codex CLI

config.toml 的 mcp_servers 區段

Codex 讀取 ~/.codex/config.toml。依官方文件,codex mcp add 指令主要支援 STDIO server;remote HTTP server 直接編輯設定檔。bearer_token_env_var 指定環境變數名稱,其值會送進 Authorization header。

# TOML 表名用底線;金鑰從環境變數讀取
[mcp_servers.tenten_index]
url = "https://index.tenten.dev/api/mcp"
bearer_token_env_var = "TENTEN_INDEX_API_KEY"
      

新開 Codex session,要求呼叫 tenten_index 的 quota_report。回傳含配額數字的 JSON 即代表設定生效。

步驟五 · Hermes Agent

config.yaml 的 mcp_servers 區段

依 Hermes Agent 官方文件,MCP 設定位於 ~/.hermes/config.yaml 的 mcp_servers 區段;remote server 填 url 與 headers 即完成。進行中的 session 執行 /reload-mcp 重新載入;hermes mcp 指令提供互動式管理。

mcp_servers:
  tenten_index:
    url: "https://index.tenten.dev/api/mcp"
    headers:
      Authorization: "Bearer <你的 API Key>"
      

/reload-mcp 後工具清單出現 tenten_index 的五個工具。呼叫 list_recent 回傳最近入池的 URL 清單即代表連線成功。

步驟六 · 連線驗證

五個工具與首次查詢

五個工具共用同一把金鑰。search_content 是 link building 的查詢入口:一次查一個關鍵字,以文章本身的語言查詢,並帶 locale 過濾。

工具	參數	用途
`search_content`	query 必填;locale、limit(1–50,預設 10)	關鍵字搜尋。回傳 url、title、description、keywords、locale、score;score 為關鍵字完全命中 100、部分命中 40、標題命中 30、描述命中 10 的加總
`submit_url`	url 必填;priority 1–3(預設 1)	文章發佈後提交進索引池,自動排入 Google 與 IndexNow 提交
`check_status`	url 必填	查詢 URL 是否入池與 Google/IndexNow 提交歷史
`quota_report`	無	當日(太平洋時間)Google Indexing API 配額用量與待提交數
`list_recent`	limit(預設 20)	最近入池的 URL 清單

content-pipeline · claude code · tenten-index

You › 用 tenten-index 查「購物車」相關的中文文章,最多 3 筆

[search_content(query: "購物車", locale: "zh", limit: 3)]

Claude › 3 筆候選,score 均為 80: tenten.co/d2c/reduce-shopify-shopping-cart-abandonment/ · Shopify 必學!降低購物車遺棄,大幅提升轉換率的方法 tenten.co/d2c/reduce-ecommerce-cart-abandon-rate/ · 消除顧客疑慮,7 招助您降低購物車放棄率 tenten.co/d2c/why-abandoning-checkout/ · 購物車放棄解密:Shopify 店家必學的結帳優化術

search_content → 3 results · locale zh

search_content 回傳非空 JSON 陣列,每筆含 url、title、keywords、score。查無結果時換同義詞重查;內容庫的用詞以文章本身語彙為準。

常見錯誤與邊界

常見錯誤與政策邊界

HTTP 401 Unauthorized。header 格式必須是 Authorization: Bearer <金鑰>;金鑰錯誤或缺 Bearer 前綴都回 401。先跑步驟一的 curl 確認服務在線,再檢查金鑰值。
.mcp.json 的 http 條目缺 "type" 欄位。依 Claude Code 官方文件,有 url 沒 type 的條目會被判定為設定錯誤而跳過;http server 必須寫 "type": "http"。
Claude Desktop 自訂 connector 填不了金鑰。connector 介面只支援 URL 與 OAuth 欄位;Bearer token 驗證一律走步驟三的 mcp-remote 設定檔路徑。
Codex 用 codex mcp add 加不了 remote server。該指令主要支援 STDIO;remote HTTP server 直接編輯 ~/.codex/config.toml。
Hermes 改完設定沒生效。進行中的 session 不會自動載入 config.yaml 變更;執行 /reload-mcp 重新載入工具清單。
search_content 回空陣列。換同義詞重查(例:「棄購」查無結果,「購物車」命中 3 筆);一次查一個關鍵字,不要整句丟入。
submit_url 拒絕非 Tenten 網域。索引池只收註冊頻道 host 的 URL;其他網域回錯誤屬預期行為。提交成功的 priority 1 URL 會立即消耗 Google 每日 200 筆配額,測試時避免重複提交。

完成檢查與下一步

六個步驟完成後,已設定的平台以同一把金鑰連上 index.tenten.dev。內容庫由 server 端排程自動更新;client 端不需維護任何資料檔。

TENTEN_INDEX_API_KEY 環境變數 — 步驟一。
Claude Code 連線(local 或 project scope) — 步驟二。
Claude Desktop 的 mcp-remote 中轉 — 步驟三。
Codex CLI 的 config.toml 區段 — 步驟四。
Hermes Agent 的 config.yaml 區段 — 步驟五。
search_content 首次查詢 — 步驟六。

下一步

1. 安裝 tenten-link-building skill。skill 定義插鏈政策:每篇 3–5 個內部連結、只連同語言頁面、不連結文章自身 URL、同一目標每篇最多一次。
2. 接入內容 pipeline。寫作流程改為:草稿完成後以 search_content 查候選、依政策插鏈、發佈後以 submit_url 回填新 URL。
3. 以 dashboard 監控。https://index.tenten.dev 顯示索引池、配額與提交狀態(Clerk 登入)。

最該讀的延伸文件

① Claude Code — Connect to tools via MCP——scope 機制、.mcp.json 格式與環境變數展開的完整參考。
② Codex — MCP 設定文件——config.toml 鍵名(bearer_token_env_var、http_headers)與驗證選項。
③ Hermes Agent — MCP Integration——mcp_servers 設定鍵與 hermes mcp 指令。

Custom connectors using remote MCP are available on Claude, Cowork, and Claude Desktop for users on Free, Pro, Max, Team, and Enterprise plans.

— Claude Help Center · support.claude.com