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

# RockAPI MCP: kết nối AI agent với hơn 50 mô hình bằng một khóa API

> RockAPI đã hỗ trợ Model Context Protocol. Tìm hiểu MCP thay đổi gì cho AI agent, cách thêm MCP server RockAPI vào Claude Code, Cursor, Codex, Claude Desktop và cách kiểm tra kết nối.

RockAPI đã hỗ trợ **Model Context Protocol (MCP)**. Bạn không cần viết mã tích hợp riêng cho từng framework agent: chỉ cần thêm một MCP server vào ứng dụng khách, agent có thể gọi RockAPI bằng đúng khóa API bạn đang dùng.

Bài viết này giải thích MCP thực sự thay đổi điều gì, hai lớp cấu hình cần tách biệt, cùng toàn bộ quy trình kết nối và kiểm tra.

![Sơ đồ kiến trúc RockAPI MCP: AI agent kết nối qua MCP client tới MCP server RockAPI rồi tới các mô hình OpenAI, Claude và Gemini](https://mintcdn.com/rockapi/H_B3LeAF53GjlC9D/images/blog/rockapi-mcp-architecture.svg?fit=max\&auto=format\&n=H_B3LeAF53GjlC9D\&q=85\&s=e510582e3dffb537393cef696ce25283)

## MCP thực sự thay đổi điều gì

MCP là một chuẩn để ứng dụng AI phát hiện và gọi các công cụ do server cung cấp. Trước MCP, mỗi framework agent tự định nghĩa định dạng plugin riêng, nên cùng một năng lực phải triển khai lại cho Claude Code, Cursor, Codex và các công cụ khác.

| Không có MCP | Có MCP |
| - | - |
| Mỗi ứng dụng khách và mỗi nhà cung cấp cần một tích hợp riêng | Một định nghĩa server mà mọi MCP client đều nạp được |
| Lược đồ công cụ phải chép thủ công vào prompt | Lược đồ được phát hiện khi chạy qua `tools/list` |
| Logic xác thực lặp lại trong từng tích hợp | Một endpoint, một khóa Bearer |
| Mô hình và công cụ gắn chặt trong cùng cấu hình | Chọn mô hình và quyền công cụ cấu hình riêng |

Kết quả thực tế: agent có một bề mặt năng lực ổn định, và bạn không phải duy trì các tích hợp song song nữa.

## Hai lớp cấu hình cần tách biệt

Đây là điểm dễ nhầm nhất, nên hãy phân biệt trước khi bắt đầu.

| Lớp | Trả lời câu hỏi nào | Cấu hình ở đâu |
| - | - | - |
| Lớp mô hình | LLM nào đảm nhận suy luận và sinh nội dung | Phần cài đặt mô hình hoặc nhà cung cấp trong ứng dụng khách |
| Lớp công cụ | Agent được truy cập công cụ và dữ liệu nào | Mục MCP server trong ứng dụng khách |

Khi thêm RockAPI làm MCP server, đó là lớp công cụ. Khi dùng RockAPI làm nhà cung cấp mô hình qua API tương thích OpenAI, đó là lớp mô hình. Có thể dùng đồng thời, nhưng đây là hai mục cấu hình riêng.

## Chuẩn bị trước khi bắt đầu

1. **Tạo khóa API.** Tạo tại [rockapi.ai/keys](https://rockapi.ai/keys) và lưu trong biến môi trường, không ghi vào tệp được commit.
2. **Sao chép cấu hình MCP.** Trang MCP trong bảng điều khiển hiển thị endpoint và định dạng header cho tài khoản của bạn. Hãy dùng giá trị hiển thị ở đó thay vì gõ lại URL theo trí nhớ.
3. **Xác nhận ứng dụng khách hỗ trợ MCP.** Claude Code, Cursor, Codex, VS Code và Claude Desktop đều hỗ trợ. Nếu lệnh bên dưới bị từ chối, hãy kiểm tra phiên bản.
4. **Chọn mô hình.** Dù dùng ứng dụng khách nào, agent vẫn cần một LLM. Chọn trong cài đặt nhà cung cấp, hoặc định tuyến qua RockAPI.

```bash theme={null}
export ROCKAPI_API_KEY="sk-your-key"
export ROCKAPI_MCP_URL="<endpoint hiển thị trên trang MCP của bảng điều khiển>"
```

## Thêm MCP server

Lệnh khác nhau theo từng ứng dụng khách, nhưng đầu vào giống nhau: một URL, một transport và một header `Authorization: Bearer`.

### Claude Code

```bash theme={null}
claude mcp add --transport http rockapi "$ROCKAPI_MCP_URL" \
  --header "Authorization: Bearer $ROCKAPI_API_KEY"
```

Kiểm tra đã đăng ký:

```bash theme={null}
claude mcp list
```

### Codex

Thêm server vào `~/.codex/config.toml`. Đọc token từ biến môi trường giúp khóa không nằm trong tệp:

```toml theme={null}
[mcp_servers.rockapi]
url = "https://your-mcp-endpoint-from-console"
bearer_token_env_var = "ROCKAPI_API_KEY"
```

### Cursor và VS Code

Cả hai nhận MCP server kiểu HTTP trong cấu hình JSON. Dùng cú pháp nội suy biến môi trường mà ứng dụng khách hỗ trợ để khóa không bị lưu dạng văn bản thuần:

```json theme={null}
{
  "mcpServers": {
    "rockapi": {
      "type": "http",
      "url": "${env:ROCKAPI_MCP_URL}",
      "headers": {
        "Authorization": "Bearer ${env:ROCKAPI_API_KEY}"
      }
    }
  }
}
```

### Claude Desktop

Claude Desktop khởi chạy server dạng dòng lệnh, nên cần cầu nối `mcp-remote`:

```json theme={null}
{
  "mcpServers": {
    "rockapi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-mcp-endpoint-from-console",
        "--header",
        "Authorization: Bearer ${ROCKAPI_API_KEY}"
      ]
    }
  }
}
```

## Kiểm tra kết nối

Trạng thái "đã kết nối" chưa đủ để đưa lên môi trường thật. Hãy xác nhận bốn hành vi sau.

| Hạng mục | Cách kiểm tra | Kết quả bình thường |
| - | - | - |
| Server đã đăng ký | `claude mcp list` hoặc bảng MCP của ứng dụng khách | Hiển thị đã kết nối, không báo lỗi |
| Phát hiện được công cụ | Yêu cầu agent liệt kê công cụ khả dụng | Danh sách không rỗng, không có lỗi 401 |
| Gọi thành công | Yêu cầu agent thực hiện một thao tác chỉ đọc | Trả về kết quả có cấu trúc, không phải timeout |
| Lỗi dễ đọc | Tạm dùng một khóa sai | Lỗi xác thực rõ ràng, không phải câu trả lời rỗng |

Nếu server kết nối được nhưng gọi thất bại, nguyên nhân thường là token chứ không phải transport. Hãy xoay khóa và thử lại trước khi kiểm tra chỗ khác.

## Nguyên tắc vận hành giúp tránh sự cố

* **Giới hạn phạm vi khóa.** Dùng khóa riêng cho tích hợp MCP thay vì khóa production chính, để thu hồi một khóa không làm hỏng khóa kia.
* **Bắt đầu ở chế độ chỉ đọc.** Chỉ cấp năng lực tối thiểu đủ hoàn thành tác vụ, mở rộng khi quy trình thực tế yêu cầu.
* **Theo dõi chi phí riêng.** Agent dùng công cụ phát sinh nhiều lệnh gọi nhỏ. Khóa riêng giúp chi phí từng agent hiển thị rõ trong bảng điều khiển.
* **Giữ bí mật trong biến môi trường.** Dán khóa vào tệp cấu hình được commit là đường rò rỉ phổ biến nhất khi thiết lập agent. Xem [quản lý khóa API an toàn](https://docs.rockapi.ai/vi/blog/buyers/secure-api-key-management.md).
* **Ghi log lệnh gọi công cụ.** Khi agent hành xử bất thường, chuỗi lệnh gọi giải thích nguyên nhân nhanh hơn câu trả lời cuối.

## Câu hỏi thường gặp

### MCP có phải là API tương thích OpenAI không?

Không. API tương thích OpenAI chuẩn hóa cách mã của bạn gọi mô hình. MCP chuẩn hóa cách ứng dụng AI phát hiện và gọi công cụ. RockAPI cung cấp cả hai và chúng được cấu hình ở hai nơi khác nhau.

### Dùng MCP có còn cần khóa API không?

Có. MCP server có thể truy cập được, nhưng khóa mới là thứ xác định tài khoản, áp giới hạn tốc độ và ghi nhận mức dùng vào hóa đơn.

### Một MCP server có phục vụ nhiều agent không?

Có, và đó chính là mục đích. Cùng một mục server dùng được ở nhiều ứng dụng khách: phiên Claude Code và phiên Cursor truy cập cùng bộ năng lực với cùng một khóa.

### MCP có thay đổi cách tính phí mô hình không?

Không. Chi phí vẫn tính theo các lệnh gọi mô hình thực tế. Xem [giá và thanh toán](https://docs.rockapi.ai/vi/pricing-and-billing.md) để biết cách tính.

### Ứng dụng khách chưa hỗ trợ MCP server kiểu HTTP thì sao?

Dùng cầu nối `mcp-remote` như ví dụ Claude Desktop. Nó chuyển endpoint HTTP thành tiến trình stdio cục bộ để mọi ứng dụng khách dạng dòng lệnh có thể khởi chạy.

## Bước tiếp theo

Nếu chưa gửi yêu cầu nào, hãy bắt đầu với [hướng dẫn nhanh](https://docs.rockapi.ai/vi/quickstart.md), sau đó xem [mô hình và nhà cung cấp](https://docs.rockapi.ai/vi/models-and-providers.md) để chọn mô hình đứng sau agent.

> [card] [Tạo khóa API và kết nối agent](https://rockapi.ai/sign-up?utm_source=docs\&utm_medium=referral\&utm_campaign=blog_buyers_mcp_vi)
>
> Tạo khóa, sao chép cấu hình MCP từ bảng điều khiển và kiểm tra kết nối trước khi đưa lên lưu lượng production.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.