MCP dan akses agen

Apa itu token agen

Token agen adalah kredensial untuk program dari luar, misalnya asisten AI, yang bekerja pada satu brand. Awalannya atl_agent_, ATLAS menampilkannya sekali saat dibuat dan hanya menyimpan hash-nya.

Di balik setiap token ada pengguna agen tersembunyi dengan peran editor yang tetap. Pengguna itu tidak pernah muncul di daftar anggota. Karena perannya editor, aturan yang berlaku untuk manusia berlaku juga untuk agen: tipe konten dengan min_role lebih tinggi tidak terlihat olehnya, dan record milik brand lain dijawab 404.

Token agen membawa scope. Anda memilih minimal satu saat membuatnya.

Scope publish dan schedule tidak bisa dibuat. Memintanya dijawab 422.

Agen tidak pernah menerbitkan

Semua yang ditulis agen berupa revisi draf. Seseorang membukanya di dashboard, meninjau, lalu menerbitkannya. Tidak ada route terbitkan, jadwalkan, rollback, atau hapus di pintu agen, dan tidak ada tool seperti itu di endpoint MCP.

Membuat token agen

Admin mengaktifkan akses agen untuk brand terlebih dahulu. Pengaturan brand agent.enabled mati secara default. Selama mati, membuat token agen dijawab 403 agent_disabled.

Ini panggilan dashboard, jadi butuh sesi admin yang sedang masuk dan header X-Brand-Id.

{
  "name": "Content assistant",
  "kind": "agent",
  "scopes": ["read", "draft:write"],
  "expires_in_minutes": 43200
}

expires_in_minutes opsional. Nilainya antara 15 menit dan 129600 menit (90 hari), default 43200 (30 hari). Jawabannya 201 berisi baris token dan nilai token polos. Simpan segera di secret manager.

Mencabut token (DELETE /v1/manage/api-tokens/{token}) langsung menonaktifkan pengguna agen tersembunyi. Token agen yang kedaluwarsa juga dinonaktifkan oleh penyapu per jam.

Pintu agen

Pintu agen ada di https://api.atlascms.id/v1/agent. Token menentukan brand-nya, jadi Anda tidak mengirim X-Brand-Id maupun cookie.

curl -s "https://api.atlascms.id/v1/agent/entries?per_page=10" \
  -H "Authorization: Bearer $ATLAS_AGENT_TOKEN"

Daftar menerima per_page (default 20, maksimum 50). Unggah media, penulisan menu, pembuatan term, terjemahan, dan tinjauan belum ada di pintu ini.

Penulisan butuh idempotency key

Setiap penulisan harus membawa header Idempotency-Key berisi 16 sampai 64 huruf, angka, titik, titik dua, tanda hubung, atau garis bawah. Tanpa itu panggilan dijawab 422 idempotency_key_required.

curl -s -X POST "https://api.atlascms.id/v1/agent/entries" \
  -H "Authorization: Bearer $ATLAS_AGENT_TOKEN" \
  -H "Idempotency-Key: 01JD6N9V0Q8KZC3F5H7M2T4W6Y" \
  -H "Content-Type: application/json" \
  -d '{"type":"page","locale":"en","path":"/about","title":"About","blocks":[]}'

• Mengulang dengan key dan isi yang sama memutar ulang jawaban pertama (header Idempotent-Replay: true) dan tidak menulis apa pun.
• Key yang sama dengan isi berbeda dijawab 422 idempotency_key_reuse. Panggilan saat yang pertama masih berjalan dijawab 409 idempotency_in_progress.
• Key berlaku per token dan disimpan 24 jam.
• Menyimpan draf butuh base_revision_id, yaitu revisi terbaru yang dibaca agen. Jika seseorang sudah menyimpan di sela itu, jawabannya 409 revision_changed dan tidak ada yang ditulis.
• Menyimpan draf dari entri yang sudah terbit tidak pernah mengubah halaman yang tayang.

Batas dan kuota

Batas lainnya dijawab 429 dengan header Retry-After.

Endpoint MCP jarak jauh

MCP adalah cara standar bagi klien AI untuk memanggil tool. POST /mcp membuka pintu agen sebagai server MCP jarak jauh, untuk klien yang tidak bisa menjalankan paket lokal.

• Endpoint ini mati secara default. Instalasi menyalakannya dengan ATLAS_MCP_REMOTE=true. Selama mati, path-nya dijawab 404.
• Memakai Streamable HTTP mode stateless: satu permintaan JSON-RPC per POST, satu jawaban JSON. GET /mcp dijawab 405.
• Autentikasi hanya Authorization: Bearer atl_agent_.... Token di query string ditolak.
• Permintaan dengan header Origin harus berasal dari origin yang tercantum di ATLAS_MCP_ALLOWED_ORIGINS (kosong secara default), jika tidak dijawab 403. HTTP polos ditolak di produksi.
• Saklar brand agent.enabled tetap berlaku.

tools/list mengembalikan 13 tool. Sepuluh tool baca butuh scope read: get_brand, list_content_types, get_content_type, list_block_schemas, list_entries, get_entry, list_revisions, list_terms, list_menus, dan get_dashboard. Tiga tool tulis butuh draft:write: create_entry, save_draft, dan sync_entry_terms.

Pemanggilan tool menjalankan route agen yang sesuai di dalam proses, jadi scope, batas, kuota, dan baris audit sama seperti di pintu agen. Tool tulis membawa key-nya di params._meta.idempotencyKey.

{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {
  "name": "create_entry",
  "arguments": {"type": "page", "locale": "en", "path": "/about", "title": "About", "blocks": []},
  "_meta": {"idempotencyKey": "01JD6N9V0Q8KZC3F5H7M2T4W6Y"}
}}

Klien yang menerima header bisa dikonfigurasi seperti ini:

{
  "mcpServers": {
    "atlas": {
      "type": "http",
      "url": "https://api.atlascms.id/mcp",
      "headers": { "Authorization": "Bearer ${ATLAS_AGENT_TOKEN}" }
    }
  }
}

Biarkan klien membaca token dari environment atau secret store. Jangan pernah meng-commit-nya.

Keamanan dan kendali

• Konten adalah data, bukan instruksi. Teks bebas di jawaban berada di bawah content, dan jawaban membawa meta.trust: "untrusted_content". Hasil MCP mengulang peringatan itu. Perlakukan teks halaman sebagai input tak tepercaya di agen Anda.
• String berbentuk token disamarkan. Nilai apa pun yang menyerupai token ATLAS diganti [redacted] di jawaban.
• Saklar pemutus. Matikan agent.enabled untuk menghentikan pembuatan token agen baru. Untuk menghentikan token yang sudah diterbitkan, cabut token itu. Instalasi juga punya saklar platform yang menolak semua baca agen atau semua tulis agen sekaligus.
• Baris audit. Setiap panggilan agen menulis baris audit agent.call berisi tool, scope, hasil, dan status, tidak pernah body atau judul. Baris disimpan 90 hari. Admin bisa membacanya lewat GET /v1/manage/audit-logs?action=agent.call.
• Hak minimum. Buat token dengan umur sesingkat dan scope sesedikit yang dibutuhkan pekerjaan, satu token per agen, dan rotasi dengan membuat token baru sebelum mencabut yang lama.

Token sync bukan token agen

Jenis token sync yang terpisah hanya ada untuk CI proyek sendiri saat menerbitkan dokumentasi dan changelog. Token itu tidak bisa dipakai sebagai token agen, dan Anda tidak membutuhkannya.

Untuk peran, jenis token, dan siapa yang boleh membuatnya, lihat peran dan izin. Untuk daftar lengkap jenis token, lihat token dan keamanan.