Xata MCP server

MCP Server

Kết nối Cursor, Claude, VS Code và các MCP client khác với Xata

Xata MCP server cho phép trợ lý AI và agent tương tác với các tổ chức, dự án và nhánh Xata của bạn bằng Model Context Protocol (MCP).

Xata MCP server là gì?

• Một MCP server được lưu trữ, chạy cùng với Xata API — bạn không cần cài đặt hay chạy bất cứ thứ gì trên máy cục bộ.
• Xác thực qua OAuth trong trình duyệt hoặc bằng Xata API key trong môi trường không có giao diện.
• Có thể truy cập từ mọi MCP client hỗ trợ máy chủ từ xa qua Streamable HTTP.

URL máy chủ:

https://api.xata.tech/mcp

Máy chủ sử dụng phương thức truyền tải Streamable HTTP. Không có endpoint SSE và cũng không có phiên bản máy chủ cục bộ (npm).

Xác thực

MCP server hỗ trợ hai phương thức xác thực:

Phương thức	Dùng khi	Yêu cầu đối với client
OAuth	Sử dụng tương tác trong trình soạn thảo/chat	Hỗ trợ MCP OAuth (đăng ký client động)
API key	Tự động hóa, CI, agent không có giao diện	Hỗ trợ HTTP header tùy chỉnh

OAuth

Với các client hỗ trợ OAuth, bạn chỉ cần URL máy chủ. Khi client kết nối lần đầu, client sẽ đăng ký với Xata, mở cửa sổ trình duyệt và yêu cầu bạn đăng nhập vào tài khoản Xata rồi phê duyệt quyền truy cập. Token có thời hạn ngắn và được giới hạn phạm vi cho MCP server.

API key

Các client hỗ trợ header tùy chỉnh có thể xác thực bằng Xata API key thay thế:

Authorization: Bearer YOUR_XATA_API_KEY

[!WARNING]

Hãy tạo API key riêng cho quyền truy cập MCP thay vì dùng lại key hiện có. Lưu key trong biến môi trường hoặc kho lưu trữ bí mật của client — tuyệt đối không commit key vào hệ thống quản lý mã nguồn.

Thiết lập MCP client

Cursor

[!TIP]

Cursor cung cấp liên kết sâu để thiết lập OAuth nhanh chóng:

Thêm vào Cursor

Ngoài ra, bạn có thể thêm thủ công:

1. Mở bảng lệnh và tìm "Cursor Settings".
2. Trong Tools & MCP, nhấp New MCP Server.
3. Thêm Xata server vào tệp cấu hình vừa mở:

{
  "mcpServers": {
    "xata": {
      "url": "https://api.xata.tech/mcp"
    }
  }
}

4. Lưu tệp. Cursor sẽ nhắc bạn xác thực — làm theo các bước trong trình duyệt và phê duyệt quyền truy cập vào tài khoản Xata.

Claude Code

Thêm máy chủ từ terminal:

claude mcp add --transport http xata https://api.xata.tech/mcp

Sau đó khởi động Claude Code và chạy lệnh slash /mcp. Chọn máy chủ xata và làm theo hướng dẫn trong trình duyệt để xác thực.

Để dùng API key thay cho OAuth (ví dụ: trong CI):

claude mcp add --transport http xata https://api.xata.tech/mcp \
  --header "Authorization: Bearer YOUR_XATA_API_KEY"

VS Code

MCP server trong VS Code yêu cầu các extension GitHub Copilot và GitHub Copilot Chat.

1. Mở Command Palette (Cmd+Shift+P / Ctrl+Shift+P).
2. Chạy MCP: Add Server và chọn HTTP.
3. Nhập https://api.xata.tech/mcp làm URL và xata làm tên.

Ngoài ra, hãy thêm thủ công vào cấu hình:

{
  "servers": {
    "xata": {
      "type": "http",
      "url": "https://api.xata.tech/mcp"
    }
  }
}

Khởi động máy chủ từ MCP: List Servers và cho phép máy chủ xác thực khi được nhắc.

Claude (web và desktop)

[!TIP]

Mở hộp thoại connector tùy chỉnh của Claude với thông tin Xata được điền sẵn:

Kết nối Xata với Claude

Xem lại và xác nhận connector trong Claude, sau đó xác thực với Xata.

Ngoài ra, hãy thêm Xata làm connector tùy chỉnh theo cách thủ công:

1. Vào Settings → Connectors.
2. Nhấp Add custom connector.
3. Nhập https://api.xata.tech/mcp làm URL máy chủ rồi nhấp Add.
4. Làm theo hướng dẫn để đăng nhập bằng tài khoản Xata.

[!NOTE]

Connector tùy chỉnh sử dụng MCP từ xa không khả dụng trên mọi gói Claude và có thể yêu cầu chủ sở hữu tổ chức thêm connector trên các gói nhóm. Xem tài liệu Claude để biết chi tiết.

ChatGPT

Kết nối ChatGPT với Xata bằng connector tùy chỉnh:

1. Trong ChatGPT, vào Settings → Connectors → Advanced settings và bật Developer mode.
2. Trong tab Connectors, tạo connector mới bằng URL máy chủ:

https://api.xata.tech/mcp

3. Chọn OAuth để xác thực và hoàn tất quy trình cấp quyền khi được nhắc.
4. Trong mỗi cuộc trò chuyện muốn dùng Xata, nhấp nút + và bật connector Xata trong Add sources.

Codex CLI

Thêm Xata server:

codex mcp add xata --url https://api.xata.tech/mcp

[!NOTE]

Lệnh add có thể mở trình duyệt và báo lỗi OAuth. Nếu điều đó xảy ra, hãy tiếp tục bằng lệnh đăng nhập bên dưới; mục máy chủ xata đã được lưu.

Xác thực với Xata bằng các phạm vi OAuth được chỉ định rõ:

codex mcp login xata --scopes mcp-client,offline_access

Hoàn tất cấp quyền trong trình duyệt. Phạm vi offline_access cho phép Codex làm mới phiên Xata mà không cần cấp quyền lại trong trình duyệt.

Sau đó khởi động codex, chạy /mcp và xác minh rằng xata đã kết nối và xác thực.

Antigravity CLI

Thêm Xata vào cấu hình MCP toàn cục:

{
  "mcpServers": {
    "xata": {
      "serverUrl": "https://api.xata.tech/mcp"
    }
  }
}

Để chỉ bật Xata cho một dự án, hãy dùng .agents/mcp_config.json trong thư mục gốc của dự án đó.

Khởi động agy và nhập /mcp. Trong MCP Manager, dùng Authenticate cho xata rồi làm theo hướng dẫn để hoàn tất OAuth.

OpenCode

Thêm Xata server vào tệp cấu hình OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "xata": {
      "type": "remote",
      "url": "https://api.xata.tech/mcp"
    }
  }
}

Sau đó xác thực từ terminal:

opencode mcp auth xata

Amp

Thêm máy chủ từ terminal:

amp mcp add xata https://api.xata.tech/mcp

Sau đó khởi động amp — bạn sẽ được nhắc xác thực trong trình duyệt. Chạy /mcp list tools để xác nhận máy chủ đã kết nối.

Windsurf

1. Trong Windsurf, mở bảng Cascade và nhấp biểu tượng MCP (búa), sau đó chọn Configure để mở tệp cấu hình thô (~/.codeium/windsurf/mcp_config.json).
2. Thêm mục máy chủ Xata:

{
  "mcpServers": {
    "xata": {
      "serverUrl": "https://api.xata.tech/mcp"
    }
  }
}

3. Lưu tệp và nhấp Refresh trong thanh bên Cascade. Hoàn tất quy trình OAuth khi cửa sổ trình duyệt mở ra.

Zed

1. Mở Settings → AI → MCP Servers rồi nhấp Add Server → Add Remote Server, hoặc chỉnh sửa trực tiếp tệp cài đặt:

{
  "context_servers": {
    "xata": {
      "url": "https://api.xata.tech/mcp"
    }
  }
}

2. Zed sẽ nhắc bạn xác thực với máy chủ bằng quy trình MCP OAuth tiêu chuẩn.

Cline

1. Mở Cline trong VS Code và nhấp biểu tượng MCP Servers.
2. Trong tab Remote Servers, nhập xata làm tên, https://api.xata.tech/mcp làm URL và chọn Streamable HTTP làm phương thức truyền tải. Hoặc chỉnh sửa trực tiếp JSON cấu hình:

{
  "mcpServers": {
    "xata": {
      "type": "streamableHttp",
      "url": "https://api.xata.tech/mcp"
    }
  }
}

[!NOTE]

Loại phương thức truyền tải phải là streamableHttp (camelCase). Nếu bỏ qua, Cline sẽ chuyển về phương thức truyền tải SSE cũ, không được Xata MCP server hỗ trợ.

Các MCP client khác

Mọi MCP client đều có thể kết nối nếu hỗ trợ:

• MCP server từ xa qua Streamable HTTP (không phải SSE)
• OAuth với đăng ký client động hoặc HTTP header tùy chỉnh để xác thực bằng API key

Tham khảo tài liệu của client để biết cách cấu hình MCP server từ xa và dùng https://api.xata.tech/mcp làm URL.

Xác minh kết nối

Sau khi kết nối, hãy yêu cầu trợ lý:

Dùng Xata MCP server để tìm thao tác REST API dùng để liệt kê các nhánh.

Trợ lý sẽ gọi search_operations với {"query":"list branches"} và trả về thao tác listBranches, có thể được gọi thông qua call_read_operation. Nếu đúng như vậy, kết nối đang hoạt động.

Các công cụ hiện có

Xata MCP server cung cấp các công cụ sau:

Công cụ	Mô tả
search_operations	Tìm thao tác Xata REST API theo mục đích (ví dụ: "liệt kê nhánh" hoặc "mời thành viên").
describe_operation	Trả về các tham số và schema yêu cầu/phản hồi cho một thao tác cụ thể.
call_read_operation	Gọi một thao tác Xata REST API chỉ đọc.
call_write_operation	Gọi một thao tác Xata REST API tạo hoặc cập nhật dữ liệu.
call_destructive_operation	Gọi một thao tác Xata REST API xóa dữ liệu hoặc thu hồi quyền truy cập. Yêu cầu confirm=true.
run_sql	Chạy SQL trên một nhánh. Mặc định chỉ đọc; các câu lệnh thay đổi dữ liệu cần cả write=true và confirm=true.
describe_schema	Liệt kê các bảng và cột của một nhánh.
list_skills	Liệt kê các kỹ năng Xata hiện có — quy trình có hướng dẫn cho những tác vụ phổ biến gồm nhiều bước.
get_skill	Đọc hướng dẫn cho một kỹ năng cụ thể.
search_xata	Tìm kiếm tài liệu Xata.
query_docs_filesystem_xata	Đọc các trang tài liệu Xata theo đường dẫn.

Bảo mật

• Ưu tiên OAuth cho các client tương tác; token có thời hạn ngắn và có thể bị thu hồi bằng cách ngắt kết nối máy chủ trong client.
• Với tác vụ tự động hóa, hãy dùng API key riêng và thường xuyên thay key.
• Một số công cụ có thể sửa đổi dữ liệu: call_write_operation và call_destructive_operation có thể thay đổi hoặc xóa tài nguyên (công cụ sau yêu cầu confirm=true), còn run_sql có thể thay đổi dữ liệu khi được gọi cùng cả write=true và confirm=true. Hãy xem xét các thao tác mà trợ lý đề xuất trước khi phê duyệt và luôn có người giám sát mọi thao tác ghi hoặc xóa.

Khắc phục sự cố

Xác thực liên tục thất bại hoặc lặp lại. Xóa Xata server khỏi client, khởi động lại client rồi thêm lại máy chủ để bắt đầu quy trình OAuth mới.

Trình duyệt báo "Client not found" khi xác thực. MCP client của bạn có thể đã lưu thông tin đăng ký OAuth không còn khả dụng trên máy chủ xác thực của Xata. Tùy client, việc xóa rồi thêm lại MCP server có thể không xóa thông tin đăng ký này. Hãy xóa thông tin đăng ký OAuth đã lưu cho Xata trong client, sau đó khởi động lại Xata MCP server và xác thực lại để tạo đăng ký mới.

Ví dụ, trong VS Code:

1. Mở Command Palette (Cmd+Shift+P / Ctrl+Shift+P).
2. Chạy Authentication: Remove Dynamic Authentication Providers.
3. Chọn nhà cung cấp liên kết với Xata, không thay đổi các nhà cung cấp khác.
4. Khởi động lại Xata MCP server và hoàn tất xác thực lại.

Máy chủ kết nối nhưng không hiển thị công cụ nào. Hãy đảm bảo bạn đã hoàn tất bước xác thực — hầu hết công cụ cần có phiên hợp lệ mới xuất hiện. Chạy lại quy trình xác thực của client rồi làm mới danh sách công cụ. Xem Các công cụ hiện có để biết danh sách đầy đủ.

Client hoàn toàn không thể kết nối. Xác nhận URL chính xác là https://api.xata.tech/mcp và client hỗ trợ Streamable HTTP. Các client chỉ hỗ trợ SSE không được hỗ trợ.

Máy chủ không xuất hiện trong client. Kiểm tra cú pháp tệp cấu hình MCP của client — cấu trúc JSON khác nhau giữa các client (mcpServers so với servers so với context_servers, url so với serverUrl) — và kiểm tra nhật ký của client. Hầu hết client cần được khởi động lại hoàn toàn sau khi thay đổi cấu hình.

Tài liệu này được xây dựng và lưu trữ trên Mintlify, một nền tảng tài liệu dành cho nhà phát triển.