Kết nối client AI qua MCP

Dureach cung cấp máy chủ MCP đọc và hành động tại https://app.dureach.com/mcp cho các client MCP bên ngoài. Client hoàn tất đồng ý OAuth, gọi tools/list để liệt kê các công cụ được cấp, sau đó gọi tools/call với tên công cụ dureach.* và tham số có kiểu dữ liệu.

Kết quả công cụ được chuyển tới ứng dụng bên ngoài và nhà cung cấp có thể xử lý hoặc lưu giữ dữ liệu. Kiểm tra điều khoản xử lý, lưu giữ và truy cập dữ liệu trước khi kết nối. Chỉ yêu cầu các trường cần thiết; không đưa thông tin liên hệ hoặc hồ sơ khách hàng vào hội thoại chung, ảnh chụp hay nhật ký.

Cần gì trước khi kết nối?

Một workspace Dureach đã bật năng lực nền tảng agent. Nếu không có, cổng vào trả về plan_capability_required.
Một OAuth client có thể hoàn tất quy trình cấp quyền có sự đồng ý qua trình duyệt. MCP chỉ chấp nhận bearer token OAuth; khóa REST API bị từ chối trên /mcp.
Hoàn tất đồng ý trong trình duyệt với tư cách thành viên không gian làm việc. Lưu thông tin xác thực trong kho được bảo vệ của ứng dụng hoặc trình quản lý bí mật phía máy chủ. Không dán mã thông báo vào hội thoại, tài liệu chung, ảnh chụp hoặc phiếu hỗ trợ.
Một MCP client hỗ trợ HTTP dạng stream với phản hồi JSON (ví dụ, Claude Desktop với connector MCP, Cursor, hoặc client Python tùy chỉnh xây dựng trên SDK mcp).

Quy trình đồng ý OAuth cho MCP diễn ra như thế nào?

Đăng ký hoặc mở OAuth client và bắt đầu lượt cấp quyền ủy quyền cho workspace.
Chỉ chọn các scope mà client cần (xem Phê duyệt, chính sách và hạn mức MCP). Client báo cáo có thể chỉ cần companies:read và trade:read; client tiếp cận cần thêm lượt cấp leads:create hoặc emails:send.
Hoàn tất đồng ý trong trình duyệt với tư cách thành viên không gian làm việc. Lưu thông tin xác thực trong kho được bảo vệ của ứng dụng hoặc trình quản lý bí mật phía máy chủ. Không dán mã thông báo vào hội thoại, tài liệu chung, ảnh chụp hoặc phiếu hỗ trợ.
Gửi token dưới dạng Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN trên mọi yêu cầu HTTP MCP. Giữ token ngoài URL, ảnh chụp màn hình, log và ticket hỗ trợ.
Nếu client phải hành động cho một workspace cụ thể, gửi X-Workspace-ID kèm ID workspace của token. Giá trị không khớp trả về workspace_context_required.

Kiểm tra tài liệu metadata tại /.well-known/oauth-protected-resource/mcp khi thư viện client cần các giá trị phát hiện tự động.

Client sử dụng endpoint và giao thức nào?

Dùng đúng https://app.dureach.com/mcp với ứng dụng MCP hỗ trợ streamable HTTP.
Hoàn tất đồng ý OAuth cho không gian làm việc dự định; lưu thông tin xác thực trong kho được bảo vệ của ứng dụng hoặc trình quản lý bí mật phía máy chủ.
Nếu máy chủ hoặc nguồn bị từ chối, kiểm tra URL kết nối và liên hệ hỗ trợ. Không xóa hoặc giả mạo tiêu đề bảo mật để vượt qua việc từ chối.
Giữ request_id trong phản hồi để chẩn đoán; không đưa mã thông báo hay hàng dữ liệu vào nhật ký dùng chung.

Cách liệt kê các công cụ khả dụng?

Sau khi đồng ý OAuth, gọi tools/list. Mỗi công cụ khả dụng có tên và lược đồ tham số. Dùng lược đồ trả về để kiểm tra yêu cầu trước khi gọi công cụ.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Dùng tools/list để xem các công cụ khả dụng cho kết nối. Phạm vi sử dụng phụ thuộc vào quyền đã cấp và quyền truy cập của không gian làm việc. Bắt đầu với quyền đọc; nhờ quản trị viên xem xét quyền còn thiếu thay vì yêu cầu quyền rộng.

Cách gọi một công cụ?

Gửi yêu cầu tools/call với tên đầy đủ có tiền tố dureach. và đối tượng tham số. Tên không xác định hoặc tên thiếu tiền tố trả về Unknown tool (INVALID_PARAMS):

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "dureach.companies.search",
    "arguments": {"query": "industrial valves", "page": 1, "limit": 10}
  }
}

Kết quả thành công trả về một mục văn bản chứa JSON cùng bản sao structuredContent đã phân tích. Lỗi ứng dụng trả về isError: true kèm {"error": {"code": "...", "details": {...}}, "request_id": "..."}. Lưu request_id để gửi hỗ trợ và xử lý thử lại. Giới hạn đầy đủ của tham số được liệt kê trong Tham chiếu công cụ MCP.

Cách cấu hình các client phổ biến?

Claude Desktop hoặc các client dựa trên connector khác

Thêm máy chủ HTTP dạng stream với URL https://app.dureach.com/mcp.
Cấu hình xác thực OAuth bằng client ID từ đăng ký OAuth Dureach và URL metadata tài nguyên MCP.
Hoàn tất đồng ý, sau đó xác minh connector liệt kê các công cụ bắt đầu bằng dureach..
Bắt đầu với dureach.workspace.context và dureach.workspace.capabilities trước khi chạy tìm kiếm dữ liệu.

Client Python tùy chỉnh (SDK `mcp` chính thức)

import os

from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

MCP_URL = "https://app.dureach.com/mcp"
TOKEN = os.environ["DUREACH_OAUTH_ACCESS_TOKEN"]

async def main():
    async with streamable_http_client(
        MCP_URL, headers={"Authorization": f"Bearer {TOKEN}"}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            result = await session.call_tool(
                "dureach.companies.search",
                {"query": "industrial valves", "page": 1, "limit": 10},
            )
            print("Search completed")

Thay token và truy vấn bằng giá trị thực tế. Không lưu token trong kho mã nguồn.

Những kiểm tra nào nên chạy trước khi chia sẻ quyền truy cập?

Gọi dureach.workspace.context và xác nhận ID workspace cùng scope trả về khớp với workspace dự kiến.
Gọi dureach.workspace.capabilities và xác nhận chỉ các hành động dự kiến xuất hiện.
Chạy một lượt đọc giới hạn (ví dụ, companies.search với limit: 5) và xác nhận các trường phân trang.
Đối với các lượt ghi, chạy trước với dry_run: true; xem Phê duyệt, chính sách và hạn mức MCP.
Thu hồi token tại /oauth/revoke hoặc trong Settings → Integrations khi không còn cần quyền truy cập.