MCP 整合

MCP 讓 Anyy 連接外部工具和資源。先確定執行位置，再儲存連線，隨後按需認證並確認實際工具呼叫。設定寫入成功不代表遠端操作已經成功；新增預設儲存啟用的 lazy 定義，不強制 Probe 或工具選擇，--disable 可先停用。

先選執行位置

本機指令

支援 stdio，程式執行在 Anyy 主機，不是瀏覽器或 CLI 用戶端的另一台電腦。必須先準備可執行程式及依賴。下面示例需要該主機已有 Node.js/npm：

anyy mcp add context --transport stdio --command npx \
  --exposure codemode --args -y @upstash/context7-mcp

--args 或 -- 後都是 Server 參數，Anyy 參數放在前面。--cwd DIR 僅用於 stdio；可重複 --env KEY=VALUE。服務只繼承 PATH、HOME、USER、LANG、LC_ALL、TERM、TMPDIR 等有限環境，需要的其他值應顯式設定。Anyy 不打包該服務的執行環境。

HTTP Endpoint

anyy mcp add remote-docs --url https://mcp.example.com
anyy mcp add provider-docs --url https://mcp.example.com --auth '{"provider":"provider-id"}'
anyy mcp add header-docs --url https://mcp.example.com --header Authorization=secret:mcp/header-docs/token

http 是 Streamable HTTP，URL 應為 HTTPS，loopback 可用 HTTP。獨立 sse transport 會被拒絕，HTTP 內部事件流仍受支援。連線 HTTP 不需要本機 Node.js。

儲存在哪裡，怎樣重新載入

Profile 定義在 config.yaml 的 mcp.client.servers。專案檔案位於該 Profile canonical Workspace 的 .anyy/mcp.json，目前即 <ProfileHome>/workspace/.anyy/mcp.json；切換對話或 Session 工作目錄不另選專案檔案。

專案檔案使用 mcpServers：

{
  "mcpServers": {
    "context": {"enabled": false, "exposure": "deferred"},
    "project-docs": {"url": "https://mcp.example.com", "exposure": "codemode"}
  }
}

含 command、url 或 type 的完整專案定義替換同名 Profile 定義，不能設定 Provider auth 引用。不含這三項則是部分覆蓋，必須已有同名 Profile 服務，只能改 enabled、exposure、toolExposure；有序覆蓋整體替換，不合併，其他欄位繼承 Profile。

anyy mcp show context
anyy mcp add project-docs --local --url https://mcp.example.com
anyy mcp remove project-docs --local

--local／-l 只寫專案檔案：新增整體替換同名專案項，無需 --force；刪除不存在項報錯，刪除僅專案項並保留 Profile 定義和授權。啟動或空閒 session.reload 後才採用這些編輯；刪除覆蓋後也在重新讀取時復原 Profile 定義。格式錯誤會進入診斷，不會在未提示的情況下改用其他來源。

anyy mcp reload SERVER_ID 只按目前已載入值重新連線，不重讀檔案。沒有 MCP 檔案監聽；手改 Profile／專案檔案後需重啟或空閒工作階段 session.reload RPC。詳情見設定生效。

變數、Secret 和工作路徑

環境值、Header 值、OAuth clientSecret 支援表示式：$VAR／${VAR} 取 Anyy 程序環境，$$ 和 $! 分別得到字面 $、!；以 ! 起始的值在 Anyy 程序目錄執行 Shell，取去首尾空白的結果，限 10 秒和 1 MiB 輸出。只處理一次，展開出的文字不再次求值。URL 和 OAuth 其他欄位不執行表示式。

一般 CLI／頁面儲存不根據欄位名字猜 Secret。Profile 定義中精確 env:、secret:、file: 字首先走認證資料解析，結果即最終值；完整專案定義將這些字首作為一般文字，部分覆蓋繼續繼承 Profile 解釋。敏感值應明確引用已管理 Secret，不能放進 URL。

指令和參數路徑展開開頭 ~，cwd 還支援相對使用者目錄或 Workspace；路徑不執行 $／!。cwd 不裁剪空白。stdio 工作目錄、對外 Workspace root、!command 的程序目錄彼此不同。

連線和工作目錄規則

初始化結果必須包含字串 protocolVersion、物件 capabilities，以及具有字串 name／version 的 serverInfo；可選 instructions 必須是字串。無效初始化會關閉連線，不標記就緒；缺失、空字串和未裁剪 instructions 保持區別，在使用摘要時才去除空白。

Server 請求 roots/list 時得到常駐 Workspace canonical 目錄這一個 file root，manager 建立後固定，不隨工作階段切換。stdio 預設工作在該目錄，設定 cwd 可改變程序目錄，不改變宣告的 root。它們都不構成檔案權限沙箱，本機程序仍用 Anyy 使用者的 OS 權限。

完成認證

沒有 Authorization Header 或 Provider 引用的 HTTP 服務支援按需 OAuth；匿名服務不強制登入，token 未載入本身也不構成重新認證要求。Provider auth 是 JSON 物件，OAuth 選項是另一個物件，例如 --oauth '{"clientId":"registered-client"}'。舊 oauth／header／none 字串選擇器不接受。

先儲存 Server，再開始：

anyy mcp login remote-docs --timeout 300

CLI 先查連線，已經 ready 就回傳 Already signed in；一般連線錯誤不會轉成登入。顯式登入可以為已儲存的停用 Server 認證，但不會啟用工具。預設 300 秒只限授權，不包含前置檢查和登入後重連。

在瀏覽器授權；不能回呼 Anyy 主機時，貼上完整重新導向 URL 到本次輸入。非互動 CLI 只等瀏覽器回呼，不讀貼上。Dashboard 已儲存 Server 的登入、TUI setup 的 Tools & MCP 提供同一入口；TUI Ctrl+Y 複製連結、Esc 取消，Dashboard 離開或取消結束待完成登入。完成後臨時連結和輸入會清除。

遠端要求互動授權或更多 Scope 時，失敗呼叫報告需登入，應顯式登入，不會自動重放該工具呼叫。取消結束本次登入，不在背景繼續。服務拒絕儲存的 client credentials 時可清理被拒狀態並復原一次，可能要求重新登入；缺少 code-exchange verifier 會終止嘗試。

另一個程序為同 Profile／Server 儲存認證資料後，等待認證的連線在模型回合開始時檢查。已準備請求保留原宣告，新目錄在後續請求準備時出現。不輪詢認證資料；此路徑不會因認證資料變更而重新啟動一般失敗／關閉連線，也不代替手改設定重新載入。

登出

anyy mcp logout remote-docs

必須給精確 Server ID。登出會刪除目前本機認證資料、關閉連線，保留設定及工具／資源／instructions 快取；沒有條目也是成功。它不撤銷遠端 token，偵測到舊 fallback 時可能需要再次登出。優先使用常駐 Profile；逾時或錯誤不授權繞過它離線改檔案。

HTTP 流、token 與重試

初始化後預設另開 GET 流接收 Server 請求與通知。Provider 認證在每次實際 HTTP dispatch（包括 GET）獲取目前 token，不另外儲存 MCP Provider token 副本。已設定 Header 保留，不為 loopback 自動新增 Origin；顯式 Origin 不被覆蓋，遠端仍可自行校驗。

有 cursor 時，事件流中斷可帶 last event ID 發 GET 復原，不重發工具呼叫。沒有 cursor 且流在回答前結束，該請求失敗。關閉連線結束復原。同 Profile／Server 多程序協調 token 重新整理，重新整理前重讀儲存值，但不保證任意崩潰／lease 丟失都能復原。

connect_timeout_ms 已退休；call_timeout_ms 分別限制初始化、發現和工具請求，沒有額外 opening 總時限。符合條件的初始 HTTP 失敗最多重試兩次。一般網路失敗不自動重放工具呼叫；expired-session 復原另有協定路徑，不能據此假定外部寫入可安全重試。

工具怎樣進入模型

Exposure	路徑
codemode	預設，由腳本發現和呼叫
deferred	模型工具搜尋
direct	直接宣告
hidden	模型和腳本均不可見

anyy mcp configure context --exposure deferred
anyy mcp set context description '文档检索服务'
anyy mcp set context toolExposure '{"get-*":"deferred","*":"hidden"}'

toolExposure 先匹配精確原始名，否則採用有序物件首個匹配萬用字元。啟用／Exposure 儲存到有效定義或既有專案覆蓋；Exposure 不重連，enable/disable 只影響該服務。連線錯誤不撤銷已儲存設定。

Profile 尚無覆蓋時，enable／disable SERVER_ID --project 只將 enabled 寫入專案；不用於完整專案定義或已覆蓋服務。configure --description／--tool-exposure 與 set/unset 修改原始 Profile 定義，不與 configure --exposure／--enable 混用；修改專案覆蓋應編輯其專案項。

MCP 不產生 mcp-* 個人組。Role、個人工具組和父名稱限制各有職責。舊全域 mcp.client.enabled、tools.include/exclude/trusted、--include、--exclude、--activate-toolset 及選擇提示均已移除，設定會拒絕它們。RPC tool_exposure 使用 JSON 字串保留順序，存為單一有序 toolExposure。

摘要不是連線成功的回條

一回合開始時產生有界 mcp_servers，列出已啟用且設定 Codemode／deferred 的服務，仍在連線的也可出現；direct-only、hidden-only、disabled 不列。混合路由優先 Codemode 標籤。摘要按名稱排序，優先設定描述，否則用可用 instructions 首行，截短並統計未展示項，不應包含認證資料。

此回合後續工具回合沿用摘要；描述或設定變化在下一提示詞反映。沒有服務符合條件時移除該段。

檢查目錄，再呼叫

anyy mcp show context
anyy mcp probe context
anyy mcp test context
anyy mcp list
anyy mcp status --json
anyy mcp logs context

Probe 單一 tools 清單給出 name、visible_name、description、exposure、offered。若目前服務確實提供 search 且 Schema 要求 query，呼叫才可寫成：

anyy mcp call docs.search --args '{"query":"Anyy"}'

CLI 用原始 Server 工具名。模型側名稱加 namespace、規範化字元並處理衝突，Codemode 要使用探索結果回傳的 JS 識別名稱，請勿手動拼出名稱。參見 Codemode和工具搜尋。

新直接呼叫按目前 JSON Schema 校驗；替換前已準備的呼叫保留當時宣告與已驗證參數，執行環境再解析目前服務和 offering。替換會關閉舊進行中的連線，不在新連線重放。模型工具和 CLI 均直接執行遠端寫入，仍受認證、Profile 所有權、認證資料保護和名稱範圍約束，舊核准／執行策略鍵不會復原。

資源、模板與 Prompt

共享工具	參數	程式結果
list_mcp_resources	可選 server、cursor	resources，可能帶 server、nextCursor、errors
list_mcp_resource_templates	同上	resourceTemplates 及同類分頁欄位
read_mcp_resource	必需 server、uri	server、uri、contents

給 server 讀取一頁，再傳 nextCursor；cursor 必須配 server。不指定服務則彙總符合條件服務的全部頁，保留成功項並在 errors 指出失敗服務；指定服務失敗則拒絕呼叫。

已啟用、報告資源能力且基礎 Exposure 非 hidden 的服務參與，共享暴露從 direct、codemode、deferred 依次選最寬。能力已知後出現，撤回則隱藏，資源清單在呼叫時讀取而非啟動抓取。MCP App UI 資源被過濾。

read 保留完整程式 JSON，模型側按文字、圖片、儲存檔案呈現，長文字遵守 20 KiB 首尾投影。交付失敗不重複已經成功的資源讀取。舊逐 Server resource/prompt 工具與 tools.resources／tools.prompts 設定均拒絕，值為 false/null 也不接受。狀態保留 advertised/capabilities，不再有舊 enabled/posture/count。Prompt 的 List/Get 仍是協定 API，不產生 Agent 工具。

把 Anyy 接到另一個 MCP 用戶端

anyy mcp serve 用 stdio 提供 conversations_list、conversation_get、messages_read、events_poll、events_wait、messages_send，操作走現有 Gateway RPC。

mcp.server.scopes 僅允許 conversations、messaging；不寫預設兩者都有，空陣列不暴露工具。舊 approvals、未實現佔位 scope 和 expose_approvals/expose_tools 均拒絕。

取得某一次輸入的結果

messages_send 只收 session_id 與 text：

{"session_id":"ses_example","text":"整理本周任务"}

先 session.submit，再以原 submission_id 等待 execution.await。結果 JSON text 包含 submission（原接受操作回條）、execution（本輸入實際呼叫狀態）、messages（按記錄引用讀出的有序結果）、timed_out。後來的提示詞不會替換這一份結果，messages_read 只是歷史查詢，不用來備援拼答案。

成功完成或實際 clarification suspension 的 MCP isError=false；suspended 保留澄清控制代碼並表示需要輸入，不是最終回答。失敗、中斷、清空、逾時或未結束狀態為 true；idle 僅 outcome=succeeded 才成功。

直接 RPC 用戶端要儲存兩個 ID：

{"execution_id":"exec_example","submission_id":"sub_example","timeout_ms":30000}

等待跟隨原預留／選中執行及其復原鏈，包括選中前準備失敗。被清空的未選輸入回傳 interrupted/input_cleared 且無訊息。等待不啟用佇列。逾時 messages 為空；逾時或取消觀察不取消已接受工作，單獨 execution_id 也無法識別某次輸入的結果。重發前先檢查狀態。

結果與停用

MCP structuredContent 保留接受的 JSON，包括 null、false、數字、字串和陣列。檢視模型文字時要區分：content 含區塊時，模型使用這些區塊的轉換結果，不再另外追加 structuredContent；content 陣列為空、但 structuredContent 存在時，會將該 JSON 格式化為模型文字區塊。這個補充文字同樣先保護認證資料，再按 20 KiB 規則處理輸出。輸出 Schema 宣告程式回傳值，不另加本機遠端結果驗證門檻。模型內容保留文字／圖片順序；音訊和未知區塊用文字佔位，嵌入資源變文字、圖片或儲存的二進位。超過 20 KiB 文字保留全輸出並投影首尾。

遠端 isError 保持失敗，transport／JSON-RPC exception 拒絕呼叫。圖片與儲存檔案走既有 Session Artifact 交付，不因交付失敗再調服務；文字儲存前保護。所有區塊先開始儲存再等轉換，因此一個無效區塊可使轉換失敗，而已開始儲存仍完成。

anyy mcp disable context
anyy mcp remove context

停用保留設定。從 Profile 設定中刪除 MCP 伺服器定義，會移除該定義及其 Anyy 管理認證資料，專案 remove --local 保留授權。對 Profile 中的 MCP 伺服器定義執行操作時，--force 用於腳本確認替換／刪除，不繞過所有權。外部服務決定實際認證、計費、傳輸要求；本機服務先查指令／環境，HTTP 先查認證／連線，再查 Exposure 和 offering。頁面流程見 Dashboard MCP。