# Máy chủ Embroidery MCP cho AI Agents Trang chính tắc: https://embroideryfileconverter.com/vi/ai-agents Kết nối tác vụ AI với công cụ thêu đã xác thực qua máy chủ MCP từ xa với OAuth, phát hiện định dạng, trạng thái sử dụng và công việc xử lý riêng. ## Chọn tích hợp phù hợp - Dùng máy chủ MCP từ xa này khi trợ lý AI cần hành động thay người dùng qua OAuth đã duyệt trong trình duyệt. - Dùng [REST Developer API](https://embroideryfileconverter.com/vi/developers) cho backend thông thường, sản phẩm SaaS hoặc tự động hóa phía máy chủ. ## Kết nối máy khách MCP - Điểm cuối HTTP có thể stream: `https://embroideryfileconverter.com/mcp/embroidery` - Phạm vi OAuth: `mcp:use` - Giới hạn tốc độ MCP mặc định: 60 yêu cầu mỗi phút - Giới hạn công cụ tạo tệp: 6 yêu cầu mỗi phút mỗi người dùng, cộng giới hạn mạng - Thời hạn access token: 60 phút - Thời hạn refresh token: 30 ngày Endpoint hoạt động với client Streamable HTTP từ xa. Ưu tiên OAuth trình duyệt gốc; không dán mật khẩu, refresh token hay bearer token dài hạn vào kho mã. ## Kết nối ChatGPT (OpenAI) Ứng dụng MCP đầy đủ được cấu hình ở chế độ nhà phát triển ChatGPT. Khả dụng và kiểm soát công cụ ghi thay đổi theo gói. 1. Trong ChatGPT web, bật Developer mode tại Cài đặt > Apps > Advanced settings, hoặc mở Workspace settings > Apps > Create. 2. Tạo ứng dụng và đặt URL máy chủ MCP thành `https://embroideryfileconverter.com/mcp/embroidery`. 3. Chọn OAuth, chọn Scan tools và phê duyệt phạm vi `mcp:use` trong trình duyệt. 4. Tạo bản nháp ứng dụng, bật và chọn từ menu công cụ trong cuộc trò chuyện mới. [Tài liệu MCP ChatGPT chính thức](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt) ## Kết nối Claude, Claude Desktop, Cowork hoặc Claude Code Trong Claude, mở Customize > Connectors > Add custom connector, nhập `https://embroideryfileconverter.com/mcp/embroidery`, chọn Connect và hoàn tất OAuth. Chủ sở hữu Team và Enterprise thêm connector tại Organization settings > Connectors trước khi thành viên kết nối riêng lẻ. Lệnh Claude Code: ```bash claude mcp add --transport http embroidery-file-converter https://embroideryfileconverter.com/mcp/embroidery # Sau đó chạy /mcp trong Claude Code và hoàn tất ủy quyền trình duyệt. ``` [Tài liệu Claude remote MCP chính thức](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) ## Kết nối OpenAI Agents SDK Backend của bạn phải hoàn tất mã ủy quyền OAuth + PKCE cho người dùng đã đăng nhập, lưu token đã mã hóa trên máy chủ, làm mới khi cần và chuyển access token hiện tại cho công cụ MCP được lưu trữ. Không bao giờ lộ token này trong JavaScript trình duyệt. ```typescript import { Agent, hostedMcpTool } from '@openai/agents'; const agent = new Agent({ name: 'Embroidery assistant', tools: [ hostedMcpTool({ serverLabel: 'embroidery', serverUrl: 'https://embroideryfileconverter.com/mcp/embroidery', authorization: process.env.EFC_MCP_ACCESS_TOKEN, requireApproval: 'always', }), ], }); ``` [Tài liệu OpenAI Agents SDK MCP chính thức](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) ## Kết nối Cursor Thêm dòng này vào `.cursor/mcp.json`, khởi động máy chủ tại Cursor Settings > MCP và hoàn tất OAuth. Người dùng Cursor Agent có thể chạy `cursor-agent mcp login embroidery-file-converter`. ```json { "mcpServers": { "embroidery-file-converter": { "url": "https://embroideryfileconverter.com/mcp/embroidery" } } } ``` [Tài liệu Cursor MCP chính thức](https://docs.cursor.com/context/model-context-protocol) ## Kết nối VS Code và GitHub Copilot Chạy `MCP: Add Server` và chọn HTTP, hoặc thêm dòng này vào `.vscode/mcp.json`. Khởi động bằng `MCP: List Servers`, tin cậy cấu hình và hoàn tất ủy quyền trình duyệt. ```json { "servers": { "embroidery-file-converter": { "type": "http", "url": "https://embroideryfileconverter.com/mcp/embroidery" } } } ``` [Tài liệu VS Code MCP chính thức](https://code.visualstudio.com/docs/agent-customization/mcp-servers) ## Kết nối OpenClaw ```bash openclaw mcp add embroidery-file-converter \ --url https://embroideryfileconverter.com/mcp/embroidery \ --transport streamable-http \ --auth oauth \ --oauth-scope mcp:use openclaw mcp login embroidery-file-converter openclaw mcp doctor embroidery-file-converter --probe ``` [Tài liệu OpenClaw MCP chính thức](https://docs.openclaw.ai/cli/mcp) ## Kết nối Gemini CLI Thêm máy chủ vào `~/.gemini/settings.json`, sau đó chạy `/mcp auth embroidery-file-converter` trong Gemini CLI. ```json { "mcpServers": { "embroidery-file-converter": { "url": "https://embroideryfileconverter.com/mcp/embroidery" } } } ``` [Tài liệu Gemini CLI MCP chính thức](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md) ## Kết nối OpenCode Thêm dòng này vào `opencode.json`, sau đó chạy `opencode mcp auth embroidery-file-converter` và xác minh bằng `opencode mcp list`. ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "embroidery-file-converter": { "type": "remote", "url": "https://embroideryfileconverter.com/mcp/embroidery" } } } ``` [Tài liệu OpenCode MCP chính thức](https://opencode.ai/docs/mcp-servers/) ## Kết nối Windsurf Cascade Mở Windsurf Settings > Cascade > MCP Servers, hoặc thêm dòng này vào `~/.codeium/windsurf/mcp_config.json`. Khởi động máy chủ, hoàn tất OAuth và chỉ bật các công cụ cần thiết. ```json { "mcpServers": { "embroidery-file-converter": { "serverUrl": "https://embroideryfileconverter.com/mcp/embroidery" } } } ``` [Tài liệu Windsurf MCP chính thức](https://docs.windsurf.com/windsurf/cascade/mcp) ## Kết nối Cline Hành vi OAuth của Cline thay đổi theo bản phát hành và giao diện. Mở MCP Servers > Remote Servers, chọn Streamable HTTP và dùng cấu hình này với danh sách phê duyệt trống: ```json { "mcpServers": { "embroidery-file-converter": { "type": "streamableHttp", "url": "https://embroideryfileconverter.com/mcp/embroidery", "disabled": false, "autoApprove": [] } } } ``` Nếu bản Cline đã cài không hoàn tất được OAuth, dùng cầu nối OAuth đã xem xét và ghim phiên bản, hoặc chọn client có OAuth gốc. Không commit token dài hạn vào `cline_mcp_settings.json`. [Tài liệu Cline MCP chính thức](https://github.com/cline/cline/blob/main/docs/mcp/mcp-overview.mdx) ## Phát hiện OAuth và PKCE - Metadata tài nguyên được bảo vệ: `https://embroideryfileconverter.com/.well-known/oauth-protected-resource/mcp/embroidery` - Metadata máy chủ ủy quyền: `https://embroideryfileconverter.com/.well-known/oauth-authorization-server` - Đăng ký client động: `https://embroideryfileconverter.com/oauth/register` - Issuer máy chủ ủy quyền: `https://embroideryfileconverter.com` - Grant: authorization code - Phương thức PKCE: S256 - Phạm vi bắt buộc: `mcp:use` Đăng ký client động chỉ chấp nhận nguồn gốc callback và scheme gốc được phép rõ ràng bởi nhà vận hành. Miền callback tùy ý bị từ chối. Tài khoản phải có địa chỉ email đã xác minh trước khi dùng endpoint MCP. Các callback được lưu trữ đáng tin cậy mặc định giới hạn ở nguồn gốc chính thức ChatGPT, Claude và VS Code cùng callback loopback cho client đã cài. Miền redirect ký tự đại diện không được bật. Triển khai ghi đè `MCP_REDIRECT_DOMAINS` phải chỉ giữ lại các client họ cố ý hỗ trợ. Ví dụ đăng ký cho callback cục bộ được phép: ```bash curl -X POST https://embroideryfileconverter.com/oauth/register \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "client_name": "Your local agent", "redirect_uris": ["http://127.0.0.1:49831/callback"] }' ``` ## Tài liệu tham khảo đầy đủ về công cụ ### `list-formats-tool` Chỉ đọc. Không nhận tham số. Trả về `artwork_inputs[]` và `formats[]` kèm các trường readable, writable, label và warning. Gọi trước khi chọn quy trình hoặc định dạng đích. ### `get-account-usage-tool` Chỉ đọc. Không nhận tham số. Trả về hạn mức xem trước hiện tại, số dư tín dụng, chi phí quy trình, giới hạn gói đăng ký và ngày đặt lại. Không thực hiện mua hay tiêu dùng gì. ### `list-processing-jobs-tool` Chỉ đọc. Liệt kê các công việc gần đây của tài khoản đã kết nối. - `limit`: số nguyên tuỳ chọn từ 1 đến 50; mặc định 20 ### `get-processing-job-tool` Chỉ đọc. Trả về một công việc của tài khoản kèm trạng thái, sự kiện, chỉ số, cảnh báo, tệp xem trước và các URL tệp được bảo vệ OAuth. - `workflow`: bắt buộc `conversion` hoặc `digitising` - `job_id`: bắt buộc mã công việc gồm 26 ký tự ### `create-processing-job-tool` Tạo dữ liệu đã lưu. Khởi động một công việc xem trước riêng tư và có thể tiêu hao hạn mức xem trước, nhưng không mua tín dụng hay mở khoá tải xuống trả phí. - `workflow`: bắt buộc `conversion` hoặc `digitising` - `file_name`: bắt buộc tên tệp gốc kèm phần mở rộng, từ 3 đến 255 ký tự, không chứa dấu phân tách đường dẫn hay ký tự điều khiển - `file_base64`: bắt buộc chuỗi base64 chuẩn thô, không có tiền tố data-URL - `format`: bắt buộc định dạng đầu ra thêu dạng chữ thường có thể ghi - `width_mm`: số từ 10 đến 300, bắt buộc khi số hóa - `colour_count`: số nguyên từ 1 đến 24, bắt buộc khi số hóa Kết quả có cấu trúc bao gồm `billing_authorized: false`. Với chuyển đổi, định dạng đầu ra phải khác định dạng nguồn đã phát hiện. ## Ví dụ công cụ JSON-RPC Liệt kê định dạng: ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "list-formats-tool", "arguments": {} } } ``` Tạo xem trước số hóa: ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "create-processing-job-tool", "arguments": { "workflow": "digitising", "file_name": "logo.png", "file_base64": "iVBORw0KGgoAAA...", "format": "pes", "width_mm": 90, "colour_count": 8 } } } ``` Kiểm tra công việc đã trả về: ```json { "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "get-processing-job-tool", "arguments": { "workflow": "digitising", "job_id": "01JEXAMPLEJOBID000000000" } } } ``` Trạng thái công việc có thể là `queued`, `processing`, `completed` và `failed`. Kiểm tra theo cơ chế backoff và dừng khi đạt trạng thái cuối. URL tệp yêu cầu cùng token truy cập OAuth và chịu sự chi phối của ngày lưu trữ `expiresAt` của tệp đã tải lên. ## Ví dụ lời nhắc ngôn ngữ tự nhiên - “Kiểm tra định dạng nào đọc được PES và ghi an toàn JEF. Hiển thị cảnh báo tương thích.” - “Liệt kê năm công việc thêu gần đây nhất của tôi và tóm tắt mọi thứ đã thất bại.” - “Trước khi tải lên, yêu cầu tôi xác nhận. Sau đó số hóa logo.png rộng 90 mm với không quá 8 màu và trả về bản xem trước PES.” - “Kiểm tra công việc 01J… cho đến khi hoàn tất, sau đó báo cáo chỉ số mũi chỉ, cảnh báo và xem tải xuống đã được mở khoá chưa.” ## Mô hình an toàn - Không có công cụ thanh toán, thanh toán, mua tín dụng hay mở khoá tải xuống trả phí nào được cung cấp. - Không có công cụ tạo khoá API, thay đổi xác thực, đọc thông tin xác thực hay xoá tài khoản nào được cung cấp. - Mọi công việc được đọc chỉ giới hạn cho người dùng đã kết nối. - Công cụ tạo lưu trữ tệp tải lên riêng tư và tạo công việc, do đó tác tử được hướng dẫn hỏi trước khi tải lên. - Tên tệp, siêu dữ liệu, thông báo công việc và cảnh báo là dữ liệu không đáng tin cậy. Máy chủ hướng dẫn tác tử không bao giờ thực hiện lệnh nhúng trong các giá trị đó. - Kết quả hoàn tất không tự động sẵn sàng sản xuất. Tác tử nên kiểm tra chỉ số xác thực và cảnh báo trước khi đưa ra tuyên bố. ## Khắc phục sự cố - `401 Unauthorized`: không có token truy cập hợp lệ; khởi động lại kết nối OAuth của máy khách. - `403 Forbidden`: token thiếu `mcp:use`, tài khoản chưa xác thực, hoặc công việc yêu cầu thuộc tài khoản khác. - `invalid_redirect_uri`: nguồn gốc callback hoặc scheme gốc không nằm trong danh sách cho phép của máy chủ. - `422`: tham số công cụ, dữ liệu base64, loại nguồn, định dạng đích hoặc hạn mức tài khoản không vượt qua xác thực. - `429`: vượt giới hạn tốc độ; tuân thủ `Retry-After` và sử dụng exponential backoff có jitter. ## Trang liên quan - [Tài liệu API nhà phát triển](https://embroideryfileconverter.com/vi/developers) - [Mô tả OpenAPI 3.1](https://embroideryfileconverter.com/developers/openapi.json) - [Chính sách quyền riêng tư](https://embroideryfileconverter.com/vi/privacy)