> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sellfern.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tích hợp MCP Server

> Kết nối các công cụ AI tương thích MCP với Sellfern bằng API V1 công khai và khóa API có phạm vi.

Tích hợp MCP của Sellfern cho phép các công cụ AI tương thích MCP làm việc với Sellfern qua các lệnh gọi API phía server an toàn. Sử dụng trang này như hướng dẫn thiết lập an toàn cho V1 dành cho các agent cần đọc hoặc cập nhật dữ liệu Sellfern.

<Note>
  Tham chiếu API là nguồn tin cậy cho sự sẵn có của endpoint công khai. Nếu một công cụ hoặc quy trình cần một endpoint không được liệt kê ở đó, hãy coi khả năng đó là không khả dụng cho tích hợp công khai cho đến khi Sellfern tài liệu hóa nó.
</Note>

## Yêu cầu trước

* Node.js 18 trở lên trên máy chạy MCP server
* Một khóa API Sellfern có các phạm vi tối thiểu mà các công cụ bạn bật yêu cầu
* Claude Desktop, Cursor, OpenCode, hoặc client tương thích MCP khác

## Cấu hình xác thực

Lưu khóa API Sellfern trong môi trường MCP server và gửi nó tới Sellfern bằng header `x-api-key` từ mã phía server.

```json theme={null}
{
  "mcpServers": {
    "sellfern": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/build/index.js"],
      "env": {
        "SELLFERN_API_URL": "https://api.sellfern.com",
        "SELLFERN_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Không bao giờ đặt khóa API trong JavaScript phía client, prompt chia sẻ, log hoặc tệp trong kho mã nguồn.

## Build và chạy

Từ thư mục dự án MCP server, cài đặt phụ thuộc và build server.

```bash theme={null}
npm install
npm run build
```

Sau đó trỏ client tương thích MCP của bạn đến entry point đã build và khởi động lại client để nó có thể phát hiện các công cụ Sellfern.

## Sự sẵn có của công cụ

Chỉ phơi bày các công cụ MCP được hậu thuẫn bởi các endpoint có trong Tham chiếu API V1. Các khả năng từ ví dụ cũ, triển khai nội bộ hoặc demo trực tiếp có thể bị hoãn cho V1 công khai.

Trước khi bật một công cụ:

1. Xác nhận endpoint cơ sở xuất hiện trong `/api-reference`.
2. Xác nhận khóa API có phạm vi tối thiểu cần thiết.
3. Đối với công cụ ghi, gửi header `Idempotency-Key` và dùng lại cùng khóa khi retry cùng một thao tác logic sau khi hết thời gian chờ hoặc lỗi server không chắc chắn.
4. Trả về lỗi rõ ràng cho agent khi Sellfern phản hồi với `403 missing_scope`, `404 not_found`, hoặc `422 idempotency_conflict`.

## Cô lập tổ chức

Khóa API được giới hạn trong một tổ chức. Nếu một công cụ nhận `404 not_found`, đừng nói với người dùng rằng tài nguyên tồn tại ở một tổ chức khác. Hãy yêu cầu người dùng xác nhận họ đã chọn đúng tổ chức và khóa API.

## Khắc phục sự cố

### Client MCP không tìm thấy server

Xác nhận rằng đường dẫn `args` trỏ đến entry point server đã build và tệp tồn tại trước khi khởi động lại client.

### Sellfern trả về `401 unauthorized`

Kiểm tra rằng khóa API có trong môi trường MCP server và server gửi nó qua header `x-api-key`.

### Sellfern trả về `403 missing_scope`

Yêu cầu khóa API mới chỉ với phạm vi bổ sung tối thiểu cần thiết cho công cụ mà người dùng đang cố chạy.