Skip to main content
Ayrshare MCP Server 讓 AI 代理程式可以驅動 Ayrshare API。本頁說明如何連線以及身分驗證的運作方式。

​
端點與傳輸方式

正式環境的 MCP Server 位址為： https://api.ayrshare.com/mcp 它使用 Streamable HTTP 傳輸方式，並且是 無狀態的（stateless） —— 呼叫之間不需要維持工作階段。

​
支援的用戶端

Action MCP Server 僅 透過靜態的 Authorization: Bearer 請求標頭進行驗證。這一項要求決定了下表中的所有結論：能夠在 Streamable HTTP 連線上設定自訂 HTTP 標頭的用戶端就能通過驗證，做不到的用戶端則無法驗證。開始設定之前，請先在下表找到你的用戶端。

​
為什麼個人連接器無法驗證

Ayrshare 的 Action MCP 需要靜態的 Authorization: Bearer 標頭。在 claude.ai、Claude Desktop 或 Claude mobile 上將它新增為個人自訂連接器並不可行，因為 Ayrshare 沒有發布 OAuth 中繼資料，而請求標頭的替代方案目前是僅限獲核准組織的 Beta 功能。 在個人連接器上，你這一側沒有任何設定可以解決這個問題：沒有可填寫 Authorization 標頭的欄位，也沒有任何 API 金鑰、設定檔或帳戶設定可以啟用該標頭。Ayrshare 不發布 OAuth 中繼資料，因此連接器的 OAuth 流程沒有任何可連線的對象。 請改用上表中的用戶端：Claude Code、Claude Code 外掛，或任何允許你設定自訂 Authorization 標頭的用戶端。如果你是已加入 Anthropic 請求標頭 Beta 計畫之組織的管理員，請參見下方的 Team 與 Enterprise 組織。
如果你的連接器看起來一切正常，但每一次工具呼叫都失敗。 連接器可以順利新增、狀態回報為 正常（healthy），並列出 完整的工具目錄 —— 然而 每一次 工具呼叫都回傳 Ayrshare 403 / code 102，“API Key not valid”。這正是此處所說的限制，而不是金鑰壞了 —— 你的用戶端無法傳送此伺服器所要求的靜態 Authorization: Bearer 標頭。initialize 與 tools/list 在驗證之前即可存取（參見下方的 身分驗證），因此在第一次工具呼叫之前不會出現任何失敗；直到那時才會發現從未傳送過任何憑證。是用戶端能力的問題，還是金鑰真的無效？ 兩者回傳完全相同的錯誤，因此請用特徵來區分。用戶端能力不足的情況是：連接器狀態正常 且 每一次工具呼叫都失敗，而同一把金鑰在其他地方可以正常使用。無效金鑰會產生相同錯誤，但在連接器之外也能重現 —— 用 REST 呼叫同樣會失敗。關於錯誤本身的語意，請參見下方的 驗證錯誤。

​
Team 與 Enterprise 組織

Anthropic 的 static_headers 機制讓自訂連接器可以改以請求標頭傳送固定憑證，而不必使用 OAuth。它目前 以 Beta 形式提供給少數組織的組織管理員，且 不 開放給新增個人連接器的個別使用者。 如果你的組織具有存取權，管理員必須將標頭值輸入為 Bearer 再接上你的 Ayrshare API 金鑰（包含其中的空格）—— Claude 會完全按照輸入的內容傳送該值，不會替你補上這個字首（scheme）。關於目前的開放狀況與設定方式，請參見 Anthropic 的連接器驗證文件。
這把金鑰由整個組織共用。 Anthropic 的請求標頭憑證由管理員輸入一次，供組織內所有成員使用，因此所有成員都會以該金鑰所屬的同一個 Ayrshare 帳戶身分操作 —— 在 Business 金鑰上可以存取其下的每一個 User Profile，而你的 Ayrshare 歷史紀錄與分析中也不會有個別使用者的歸屬資訊。請把它當作共用的服務憑證，而非個人存取權限。

​
身分驗證

身分驗證是由為 REST API 提供支援的同一條 Ayrshare API 處理鏈執行。
  • 必填： Authorization: Bearer YOUR_API_KEY —— 你的帳戶 API 金鑰（涉及設定檔與子設定檔時，需要 Business 方案的金鑰）。
  • 選填： Profile-Key: YOUR_PROFILE_KEY —— 讓此連線上的每一次呼叫都以該子設定檔為目標。
  • 每次呼叫可選： profileKey 工具參數 —— 僅讓本次工具呼叫以某個子設定檔為目標。

​
優先順序：參數優先於標頭

當一次工具呼叫同時包含 profileKey 參數 與 連線上的 Profile-Key 標頭時，本次呼叫的 profileKey 參數優先生效。只有在未提供有效參數時，才會使用該標頭。 一個例外：在 get_platform_history 與 get_social_network_analytics 上，X/Twitter 的 userId / userName 查詢必須僅使用帳戶 API 金鑰;此時若傳入 profileKey 參數或 Profile-Key 標頭，會回傳 400 錯誤。
MCP 的 initialize 與 tools/list 方法可以在 驗證之前 存取 —— 它們只回傳中繼資料，不會執行任何動作。所有工具呼叫都必須經過驗證。

​
驗證錯誤

在工具呼叫中使用未驗證或無效的金鑰，會回傳 Ayrshare error 403 / code 102，錯誤訊息為 “API Key not valid”。依照 MCP 規範，工具執行錯誤會以內含（in-band）方式回傳：工具結果會帶有 isError: true 與該錯誤訊息，而 MCP 傳輸層本身則回傳 HTTP 200。（403 / 102 是 Ayrshare 的應用層錯誤，而非傳輸層狀態。）

​
連線

​
方式 A：Claude Code 外掛

如果你使用 Claude Code，可以安裝 Ayrshare 外掛。該外掛已內建 MCP Server 設定、初始化指令、代理程式、技能以及確認 hook。完整安裝步驟請參見 Claude Code 外掛 頁面。

​
方式 B：任何 MCP 用戶端

對於任何支援 Streamable HTTP 且允許你設定自訂請求標頭 的 MCP 用戶端 —— 請參見上方的 支援的用戶端 —— 可以直接註冊伺服器。在 Claude Code 中：
若要讓每次呼叫都以某個子設定檔為目標，請加上選用的 Profile-Key 標頭：
MCP 連線會在工作階段啟動時初始化。安裝伺服器或變更金鑰後，請 重新啟動你的 MCP 用戶端，讓新的設定生效。

​
X/Twitter 自帶（BYO）憑證

自 2026 年 3 月 31 日起，透過 Ayrshare 進行的 X/Twitter 操作需要使用你自己的 OAuth 1.0a 憑證。當工具呼叫的目標是 X/Twitter 時，請在連線上與 Authorization（以及選用的 Profile-Key）標頭一起附上以下兩個標頭： 這些標頭與 REST API 所使用的相同 —— 每個 Ayrshare 帳戶對應一組 OAuth 1.0a 金鑰對，並在每個以 X 為目標的請求中傳送（同一組金鑰適用於所有子設定檔）。Ayrshare 在此處不使用 OAuth 2.0。關於設定、政策與疑難排解，請參見 API 概觀 與 X BYO Key 設定指南。
若缺少這些標頭，X/Twitter 工具呼叫會回傳錯誤 419（x_credentials_required）。

​
連線時同時設定 BYO 標頭

若要從一開始就設定 X/Twitter BYO 憑證，請在新增伺服器時同時提供兩個 OAuth 1.0a 標頭與 Authorization 標頭（若每次呼叫都要以某個子設定檔為目標，也請一併附上 Profile-Key）：

​
為既有連線補上 BYO 標頭

連線上的標頭在新增伺服器時就已固定，因此若你之前連線時沒有帶上 BYO 標頭，需要先移除伺服器，然後重新新增並提供完整的標頭集合（重新包含你之前已在使用的任何標頭，例如 Profile-Key）：
變更標頭後，請重新啟動 MCP 用戶端讓新設定生效。若你使用的是 Claude Code 外掛而非直接連線，請參見 Claude Code 外掛 → X/Twitter BYO 憑證。

​
後續步驟

工具目錄

按領域分組的 33 個工具，包含適用範圍與用途。

Claude Code 外掛

為 Claude Code 安裝 Ayrshare 外掛。