Tài liệu API: MCP

Máy chủ MCP cho phép trợ lý AI tương tác với ProcessMind qua Model Context Protocol. Máy chủ sử dụng JSON-RPC 2.0 qua Streamable HTTP: gửi initialize, sau đó gửi tools/list để xem danh mục công cụ. Các công cụ chỉ đọc như list_processes chỉ xuất hiện khi API key có phạm vi read; công cụ ghi cần phạm vi write. Dùng tools/call để gọi công cụ cùng các đối số. Bạn có thể lưu thông tin dùng chung giữa các phiên bằng công cụ bộ nhớ (remember, recall, forget). Các tác vụ AI chạy lâu được theo dõi theo từng lần gọi công cụ: đính kèm mã tham chiếu tác vụ trong _meta["io.modelcontextprotocol/related-task"], ProcessMind sẽ trả về trạng thái tác vụ cùng kết quả gọi. Các phương thức mở rộng tasks/list, tasks/get và tasks/cancel không được hỗ trợ.

Điểm cuối máy chủ Model Context Protocol (JSON-RPC qua Streamable HTTP)

JSON-RPC 2.0 qua Streamable HTTP: initialize, tools/list, tools/call, resources/list, resources/read, prompts/list. Công cụ chỉ đọc cần phạm vi read của key, công cụ ghi cần phạm vi write. Hướng dẫn MCP mô tả danh mục công cụ. Xác thực bằng x-api-key hoặc Authorization: Bearer <token> (token lấy từ điểm cuối OAuth token).

Điểm cuối: POST /v1/mcp/{tenantId}

Xác thực: API key giới hạn theo tenant · phạm vi read · giới hạn tốc độ 20 yêu cầu/giây (tối đa 40 yêu cầu)

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid

Nội dung yêu cầu:

Yêu cầu MCP JSON-RPC

{}

Phản hồi (200):

Phản hồi MCP JSON-RPC

{
	"message": "string"
}

Trường	Kiểu	Bắt buộc	Mô tả
message	string	Có

Lỗi:

• 401 Thiếu, không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn API key
• 403 API key không có phạm vi cần thiết hoặc quyền truy cập tổ chức; tenant không hoạt động hoặc gói dịch vụ không hỗ trợ loại tệp này

Điểm cuối ủy quyền OAuth 2.1 (PKCE), chuyển hướng 302 về redirect_uri kèm ?code=…

Điểm cuối: GET /v1/mcp/{tenantId}/oauth/authorize

Xác thực: Công khai, không cần API key · giới hạn tốc độ 10 yêu cầu/giây (tối đa 20 yêu cầu)

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid
client_id	string	query	Có
redirect_uri	string	query	Có	Định dạng: uri
code_challenge	string	query	Có
code_challenge_method	S256	query	Không	Giá trị được phép: S256
state	string	query	Không

Lỗi:

• 302 Chuyển hướng đến redirect_uri kèm code + state
• 400 Yêu cầu không hợp lệ, chẳng hạn biểu thức bộ lọc không hợp lệ, quy trình chưa có mô hình, loại tệp tải lên không được hỗ trợ hoặc thiếu trường bắt buộc
• 401 Thiếu, không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn API key

Điểm cuối token OAuth 2.0 (client_credentials hoặc authorization_code + PKCE)

Điểm cuối: POST /v1/mcp/{tenantId}/oauth/token

Xác thực: Công khai, không cần API key · giới hạn tốc độ 5 yêu cầu/giây (tối đa 10 yêu cầu)

Tham số:

Tên	Kiểu	Vị trí	Bắt buộc	Mô tả
tenantId	string	path	Có	Định dạng: uuid

Phản hồi (200):

Access token

{
	"access_token": "string",
	"token_type": "Bearer",
	"expires_in": 0
}

Trường	Kiểu	Bắt buộc	Mô tả
access_token	string	Có	JWT Bearer có thời hạn ngắn cho POST /v1/mcp/{tenantId}
token_type	Bearer	Có	Giá trị được phép: Bearer
expires_in	number	Có

Lỗi:

• 400 Yêu cầu không hợp lệ, chẳng hạn biểu thức bộ lọc không hợp lệ, quy trình chưa có mô hình, loại tệp tải lên không được hỗ trợ hoặc thiếu trường bắt buộc
• 401 Thiếu, không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn API key
• 403 API key không có phạm vi cần thiết hoặc quyền truy cập tổ chức; tenant không hoạt động hoặc gói dịch vụ không hỗ trợ loại tệp này