Thiết lập MCP

Kết nối một trợ lý hỗ trợ Model Context Protocol tới Proxyma để nó có thể tìm trong các nguồn dữ liệu đã lập chỉ mục của bạn.

MCP

Điểm kết nối MCP là:

https://your-proxyma-host/mcp

Trên bản Enterprise Server, MCP yêu cầu một mã truy cập, và máy khách nhìn thấy đúng những gì tài khoản đó nhìn thấy. Trên bản Desktop không có tài khoản - hãy bỏ tiêu đề Authorization, AUTH_HEADER và --bearer-token-env-var khỏi các cấu hình bên dưới.

Cài đặt > Trợ lý AI trong Proxyma hiển thị từng cấu hình bên dưới, trừ cấu hình của Cursor, với địa chỉ của bạn đã điền sẵn, sẵn sàng để sao chép.

Bản Home Server cũng không có tài khoản, nên MCP không bao giờ đòi token. Khi PROXYMA_ALLOWED_HOSTS mở nó ra ngoài chính chiếc máy đó, nó chỉ trả lời /mcp khi PROXYMA_EXPOSE_MCP=true - và khi đó bất kỳ ai truy cập được nó đều dùng được các công cụ của tác nhân, kể cả những công cụ ghi vào Jira, Confluence và Bitbucket.

Claude Code (CLI và tiện ích mở rộng cho VS Code)

Chạy lệnh này trong cửa sổ dòng lệnh. Lệnh này cũng kết nối luôn tiện ích mở rộng cho VS Code, vốn không tự thêm được máy chủ MCP; về sau hãy quản lý kết nối bằng /mcp trong bảng trò chuyện.

claude mcp add --transport http proxyma https://your-proxyma-host/mcp \
  --header "Authorization: Bearer <your-access-token>"

Hoặc thêm bằng tay vào .mcp.json (theo dự án) hoặc ~/.claude.json (theo người dùng, cho mọi dự án).

{
  "mcpServers": {
    "proxyma": {
      "type": "http",
      "url": "https://your-proxyma-host/mcp",
      "headers": { "Authorization": "Bearer <your-access-token>" }
    }
  }
}

Claude Desktop

Claude Desktop kết nối tới máy chủ HTTP qua cầu nối mcp-remote, cần Node.js 18 trở lên. Trong Claude, mở Settings > Developer > Edit Config, thêm mục dưới đây, rồi thoát hẳn Claude và mở lại. Với địa chỉ http:// như của Desktop, hãy thêm "--allow-http" ngay sau địa chỉ trong args.

{
  "mcpServers": {
    "proxyma": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-proxyma-host/mcp",
               "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer <your-access-token>" }
    }
  }
}

Token được truyền qua env vì Claude Desktop trên Windows không xử lý dấu cách bên trong args.

ChatGPT và Codex

Ứng dụng ChatGPT trên máy tính, Codex CLI và tiện ích Codex cho VS Code dùng chung một thiết lập, nên một lệnh kết nối cả ba. Cài Codex CLI và đăng nhập bằng tài khoản ChatGPT, rồi chạy:

codex mcp add proxyma --url https://your-proxyma-host/mcp --bearer-token-env-var PROXYMA_TOKEN

Đặt biến môi trường PROXYMA_TOKEN là token truy cập của bạn. ChatGPT trên web không kết nối được tới máy chủ trên máy tính của bạn.

Gemini CLI

Đăng nhập bằng tài khoản Google, rồi chạy:

gemini mcp add -s user --transport http --header "Authorization: Bearer <your-access-token>" proxyma https://your-proxyma-host/mcp

Hoặc thêm bằng tay vào ~/.gemini/settings.json. Trường này là httpUrl; url nghĩa là máy chủ SSE và sẽ không kết nối được.

{
  "mcpServers": {
    "proxyma": {
      "httpUrl": "https://your-proxyma-host/mcp",
      "headers": { "Authorization": "Bearer <your-access-token>" }
    }
  }
}

GitHub Copilot (VS Code)

Thêm đoạn này vào .vscode/mcp.json, hoặc chạy MCP: Open User Configuration từ Command Palette để áp dụng cho mọi không gian làm việc. Khóa ở đây là servers chứ không phải mcpServers, và "type": "http" là bắt buộc.

{
  "servers": {
    "proxyma": {
      "type": "http",
      "url": "https://your-proxyma-host/mcp",
      "headers": { "Authorization": "Bearer <your-access-token>" }
    }
  }
}

Cursor

Thêm đoạn này vào ~/.cursor/mcp.json để áp dụng cho mọi dự án, hoặc vào .cursor/mcp.json trong một dự án.

{
  "mcpServers": {
    "proxyma": {
      "url": "https://your-proxyma-host/mcp",
      "headers": { "Authorization": "Bearer <your-access-token>" }
    }
  }
}

Một máy khách chạm tới được những gì

Máy khách MCP và lời gọi API tuân theo cùng quy tắc như giao diện web. Khi xác thực dưới danh nghĩa của bạn, chúng thấy các bộ kết nối của bạn và những bộ được chia sẻ. Trên bản Enterprise Server, MCP từ chối máy khách không có token; khi không có token, tìm kiếm và trò chuyện qua API chỉ thấy các bộ kết nối được chia sẻ, còn các điểm kết nối cho nguồn dữ liệu trả về 401. Không bên nào chạm tới được bộ kết nối riêng tư của người dùng khác.

Khi quyền Ghi đang bật cho một bộ kết nối, một máy khách MCP có thể thay đổi hệ thống đó thông qua các công cụ của tác nhân, và không ai được hỏi để chấp thuận thay đổi đó.