Dokumentasi — ngaturbisnis MCP

Mulai Cepat

ngaturbisnis MCP adalah server yang mengimplementasikan Model Context Protocol (MCP) di atas Laravel 11. Server ini mendukung Claude Code (HTTP transport) dan Claude Desktop (SSE transport) untuk terhubung ke sistem manajemen bisnis F&B Anda.

3 Langkah Memulai

1 Daftar & login ke ngaturbisnis.com
2 Hubungkan Claude via OAuth (otomatis) atau buat API Key manual
3 Mulai gunakan — tanya Claude: "Tampilkan ringkasan bisnis saya"

Gambaran Umum

Protokol

MCP 2025-03-26 (HTTP) / 2024-11-05 (SSE)

Transport

HTTP POST (Claude Code) + SSE (Claude Desktop)

Autentikasi

OAuth 2.0 PKCE / Laravel Sanctum Token

Jumlah Tools

12 tools (8 READ + 4 WRITE)

Yang Anda Butuhkan

Akun aktif di ngaturbisnis.com
Claude Desktop / Claude Code / Claude.ai — via OAuth (login otomatis)
atau Cursor / Windsurf / Cline — via API Key manual

Buat API Key

Login ke ngaturbisnis.com → sidebar menu API Key → klik "Buat API Key Baru".

1 Isi label perangkat, contoh: MacBook Kantor atau Claude Code

2 Klik Buat API Key — token muncul sekali saja

3 Salin token dan lanjut ke bagian Konfigurasi Claude

Penting: Token hanya tampil sekali saat dibuat. Jika lupa, revoke token lama dan buat yang baru. Maksimal 5 token aktif per akun.

Konfigurasi Claude

ngaturbisnis MCP mendukung dua cara koneksi sesuai client yang Anda gunakan.

Claude Code (CLI) — HTTP Transport

Jalankan perintah berikut di terminal. Tidak perlu Node.js atau config file.

claude mcp add ngaturbisnis --transport http https://mcp.ngaturbisnis.com/api/mcp \
  --header "Authorization: Bearer TOKEN_ANDA"

# Verifikasi
claude mcp list

Claude Desktop — HTTP Transport (Direkomendasikan)

Edit file claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ngaturbisnis": {
      "type": "http",
      "url": "https://mcp.ngaturbisnis.com/api/mcp",
      "headers": { "Authorization": "Bearer TOKEN_ANDA" }
    }
  }
}

Claude Desktop — SSE Transport (Legacy)

Gunakan jika versi Claude Desktop Anda belum mendukung HTTP transport.

{
  "mcpServers": {
    "ngaturbisnis": {
      "type": "sse",
      "url": "https://mcp.ngaturbisnis.com/api/sse?token=TOKEN_ANDA"
    }
  }
}

Ganti TOKEN_ANDA dengan token dari halaman API Key di dashboard ngaturbisnis.com. Restart Claude Desktop setelah menyimpan config.

Verifikasi koneksi: ketik di Claude: "Tampilkan ringkasan bisnis saya". Claude akan memanggil tool baca_ringkasan_bisnis.

Autentikasi

ngaturbisnis MCP mendukung dua metode autentikasi: OAuth 2.0 PKCE (direkomendasikan) dan API Key manual via Laravel Sanctum.

OAuth 2.0 PKCE (Direkomendasikan)

Claude Desktop, Claude Code, dan Claude.ai web mendukung OAuth — browser terbuka otomatis untuk login, tidak perlu copy-paste token.

1. Client mengirim request tanpa token → server mengembalikan 401

2. Client membuka browser ke /oauth/authorize dengan PKCE challenge

3. User login di ngaturbisnis.com → klik "Izinkan Akses"

4. Server menukar authorization code → access token (otomatis)

OAuth tersedia untuk: Claude Desktop, Claude Code, Claude.ai web. Untuk Cursor, Windsurf, dan Cline gunakan API Key manual.

API Key Manual (HTTP Transport)

Token dikirim via Authorization: Bearer header — untuk Cursor, Windsurf, Cline, atau sebagai alternatif OAuth.

1 Client mengirim POST /api/mcp dengan Authorization: Bearer TOKEN
2 Sanctum memvalidasi token, server langsung memproses JSON-RPC dan mengembalikan JSON

                POST /api/mcp HTTP/1.1
Authorization: Bearer TOKEN_ANDA
Content-Type: application/json
            

SSE Transport (Claude Desktop legacy)

EventSource tidak bisa mengirim header, sehingga token dikirim via query parameter ?token= dan di-inject ke Bearer oleh middleware.

1 Client membuka GET /api/sse?token=TOKEN — server mengirim event: endpoint berisi URL /api/messages?connection_id=XYZ lalu heartbeat : ping tiap 15 detik
2 Client mengirim tool call via POST /api/messages dengan Bearer token — server membalas JSON langsung

                // SSE stream yang dikirim server:
event: endpoint
data: https://mcp.ngaturbisnis.com/api/messages?connection_id=abc123

: ping

: ping
            

MCP Protocol

Server mengimplementasikan dua versi transport Model Context Protocol (MCP) secara bersamaan.

Endpoints

POST

/api/mcp

HTTP Transport (MCP 2025-03-26). Auth via Authorization: Bearer. Claude Code & Claude Desktop baru. JSON response langsung.

GET

/api/sse?token=TOKEN

SSE Transport (MCP 2024-11-05). Kirim event: endpoint lalu heartbeat : ping tiap 15 detik.

POST

/api/messages?connection_id=XYZ

SSE Transport companion. Method: initialize, tools/list, tools/call, notifications/*.

Format JSON-RPC

                // Request tool call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "baca_ringkasan_bisnis",
    "arguments": {}
  }
}

// Response sukses
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "DAFTAR TOKO\n..." }],
    "isError": false
  }
}
            

baca_ringkasan_bisnis READ

Mengambil seluruh data performa bisnis (omzet, pengeluaran, laba, margin, sesi kasir, insight) untuk dianalisis. Hanya READ — tidak mengubah data.

Parameter

Nama	Tipe	Status	Keterangan
`start_date`	string	Opsional	Tanggal awal YYYY-MM-DD (default: awal bulan ini)
`end_date`	string	Opsional	Tanggal akhir YYYY-MM-DD (default: hari ini)
`store_id`	string	Opsional	UUID toko untuk filter satu toko tertentu

Contoh Request

                {
  "name": "baca_ringkasan_bisnis",
  "arguments": {
    "start_date": "2025-07-01",
    "end_date": "2025-07-31"
  }
}
            

Contoh Response

                📊 RINGKASAN BISNIS — Warung Barokah
📅 Periode: 1 Jul 2025 s/d 31 Jul 2025
──────────────────────────────────────────────────
🟢 Toko Utama (ID: abc-123)
   💰 Omzet       : Rp 12.500.000
   📤 Pengeluaran : Rp 8.200.000
   📈 Laba/Rugi   : +Rp 4.300.000
   📊 Margin      : 34.4%
   🔢 Sesi Kasir  : 28 sesi

💡 INSIGHT:
   • Margin 34.4% tergolong sehat. Pertahankan!
            

tambah_toko WRITE

Membuat profil toko atau cabang baru di bawah akun ngaturbisnis.com Anda.

Parameter

Nama	Tipe	Status	Keterangan
`name`	string	Wajib	Nama toko / cabang
`address`	string	Opsional	Alamat lengkap toko
`phone`	string	Opsional	Nomor telepon toko

Contoh Request

                {
  "name": "tambah_toko",
  "arguments": {
    "name": "Cabang Sudirman",
    "address": "Jl. Sudirman No. 45, Jakarta Pusat",
    "phone": "021-5551234"
  }
}
            

Contoh Response

                ✅ Toko berhasil dibuat!
📍 Nama    : Cabang Sudirman
🆔 ID      : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
📮 Alamat  : Jl. Sudirman No. 45, Jakarta Pusat
            

catat_pengeluaran WRITE

Mencatat pengeluaran keuangan baru ke toko tertentu. Cocok digunakan setelah Claude membaca foto nota / struk belanja.

Parameter

Nama	Tipe	Status	Keterangan
`amount`	integer	Wajib	Jumlah dalam Rupiah (tanpa titik/koma)
`date`	string	Wajib	Tanggal YYYY-MM-DD
`description`	string	Wajib	Nama / keterangan pengeluaran
`store_id`	string	Opsional	UUID toko (auto-resolve ke toko aktif pertama jika kosong)
`category`	string	Opsional	Enum: Bahan Baku, Operasional, Gaji, Utilitas, Transportasi, Pemasaran, Peralatan, Lainnya

Contoh Request

                {
  "name": "catat_pengeluaran",
  "arguments": {
    "amount": 250000,
    "date": "2025-07-15",
    "description": "Beli cabai rawit 5kg",
    "category": "Bahan Baku"
  }
}
            

Contoh Response

                ✅ Pengeluaran berhasil dicatat!
📋 Deskripsi : Beli cabai rawit 5kg
💰 Jumlah    : Rp 250.000
📅 Tanggal   : 15 Juli 2025
🏷️  Kategori  : Bahan Baku
🏪 Toko      : Toko Utama
🆔 ID        : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
            

catat_pemasukan WRITE

Mencatat pemasukan manual atau pendapatan di luar sistem kasir ke toko tertentu. Tercatat sebagai sesi penjualan selesai menggunakan kasir aktif pertama toko.

Parameter

Nama	Tipe	Status	Keterangan
`amount`	integer	Wajib	Jumlah dalam Rupiah
`date`	string	Wajib	Tanggal YYYY-MM-DD
`description`	string	Wajib	Keterangan / sumber pendapatan
`store_id`	string	Opsional	UUID toko (auto-resolve jika hanya ada satu toko)

Catatan: Toko harus memiliki setidaknya satu kasir aktif. Jika belum ada kasir, tambahkan kasir terlebih dahulu via menu Master → Kasir di dashboard ngaturbisnis.com.

Contoh Request

                {
  "name": "catat_pemasukan",
  "arguments": {
    "amount": 500000,
    "date": "2025-07-15",
    "description": "Pendapatan catering acara pernikahan"
  }
}
            

Contoh Response

                ✅ Pemasukan berhasil dicatat!
📋 Keterangan   : Pendapatan catering acara pernikahan
💰 Jumlah       : Rp 500.000
📅 Tanggal      : 15 Juli 2025
🏪 Toko         : Toko Utama
👤 Via Kasir    : Budi
🆔 ID Sesi      : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
            

buat_transaksi_kasir WRITE

Membuat invoice penjualan atau transaksi kasir baru dengan daftar item produk, harga satuan, dan metode pembayaran.

Parameter

Nama	Tipe	Status	Keterangan
`items`	array	Wajib	Daftar item — setiap item wajib: product_name (string), quantity (integer), price (integer). product_id (UUID) opsional.
`payment_method`	string	Wajib	Enum: cash, transfer, qris
`store_id`	string	Opsional	UUID toko
`date`	string	Opsional	Tanggal YYYY-MM-DD (default: hari ini)
`note`	string	Opsional	Catatan tambahan

Catatan: Membutuhkan kasir aktif di toko. QRIS diperlakukan sama dengan transfer.

Contoh Request

                {
  "name": "buat_transaksi_kasir",
  "arguments": {
    "items": [
      { "product_name": "Nasi Goreng Spesial", "quantity": 2, "price": 18000 },
      { "product_name": "Es Teh Manis", "quantity": 3, "price": 5000 }
    ],
    "payment_method": "cash"
  }
}
            

Contoh Response

                ✅ Transaksi kasir berhasil dibuat!
🏪 Toko           : Toko Utama
👤 Kasir          : Budi
📅 Tanggal        : 15 Juli 2025
💳 Pembayaran     : Cash

📦 Item Terjual:
   • Nasi Goreng Spesial × 2 @ Rp 18.000 = Rp 36.000
   • Es Teh Manis × 3 @ Rp 5.000 = Rp 15.000

💰 Total          : Rp 51.000
🆔 ID Transaksi   : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
            

tren_perkembangan_bisnis READ

Membandingkan performa bisnis antara dua periode untuk melihat perkembangan (naik/turun) omzet, pengeluaran, dan laba. Cocok untuk pertanyaan seperti "bagaimana perkembangan bisnis saya?" atau "bulan ini vs bulan lalu".

Parameter

Nama	Tipe	Status	Keterangan
`period`	string	Opsional	Enum: this_week_vs_last_week, this_month_vs_last_month (default), this_year_vs_last_year, custom
`current_start`	string	Opsional	Awal periode saat ini YYYY-MM-DD (hanya jika period=custom)
`current_end`	string	Opsional	Akhir periode saat ini YYYY-MM-DD (hanya jika period=custom)
`prev_start`	string	Opsional	Awal periode pembanding YYYY-MM-DD (hanya jika period=custom)
`prev_end`	string	Opsional	Akhir periode pembanding YYYY-MM-DD (hanya jika period=custom)
`store_id`	string	Opsional	Filter ke satu toko tertentu

Contoh Request

                {
  "name": "tren_perkembangan_bisnis",
  "arguments": {
    "period": "this_month_vs_last_month"
  }
}
            

Contoh Response

                📊 PERKEMBANGAN BISNIS — Toko Utama
────────────────────────────────────────────────────────
                           Juli 2025              Juni 2025
────────────────────────────────────────────────────────
💰 Omzet                  📈 +23.5%              Rp 8.500.000 → Rp 10.500.000
📤 Pengeluaran            📉 -5.2%               Rp 3.800.000 → Rp 3.600.000
📈 Laba/Rugi              📈 +46.8%              Rp 4.700.000 → Rp 6.900.000
🔢 Sesi Kasir             📈 +15.0%              40 sesi → 46 sesi
📊 Margin                 📈 +10.8%              55.3% → 65.7%

💬 ANALISIS:
   • Omzet naik Rp 2.000.000 (+23.5%) — pertumbuhan positif.
   • Laba meningkat Rp 2.200.000 — efisiensi biaya terjaga.
   • Margin meningkat signifikan — profitabilitas membaik.
            

prediksi_dan_rekomendasi READ

Menganalisis tren historis beberapa bulan terakhir untuk memprediksi performa bulan depan dan memberikan rekomendasi konkret: apa yang harus ditambah (produk/pemasukan) dan dikurangi (beban/pengeluaran).

Parameter

Nama	Tipe	Status	Keterangan
`months`	integer	Opsional	Jumlah bulan historis yang dianalisis (default: 3, max: 6)
`store_id`	string	Opsional	Filter ke satu toko tertentu

Contoh Request

                {
  "name": "prediksi_dan_rekomendasi",
  "arguments": {
    "months": 3
  }
}
            

Contoh Response

                🔮 PREDIKSI & REKOMENDASI — Toko Utama
Berdasarkan data 3 bulan terakhir (Mei – Jul 2025)

📊 TREN HISTORIS:
   Mei 2025  : Omzet Rp 7.200.000 | Biaya Rp 3.500.000 | Laba Rp 3.700.000
   Jun 2025  : Omzet Rp 8.500.000 | Biaya Rp 3.800.000 | Laba Rp 4.700.000
   Jul 2025  : Omzet Rp 10.500.000 | Biaya Rp 3.600.000 | Laba Rp 6.900.000

🎯 PREDIKSI BULAN DEPAN (Agustus 2025):
   💰 Omzet       : ~Rp 12.150.000 (📈 +15.7%)
   📤 Pengeluaran : ~Rp 3.650.000
   📈 Laba        : ~Rp 8.500.000

✅ REKOMENDASI TAMBAH:
   • Produk best-seller perlu stok lebih banyak
   • Pertimbangkan tambah varian menu

⚠️ REKOMENDASI KURANGI:
   • Evaluasi item menu yang kurang laku
   • Optimasi biaya operasional yang naik
            

daftar_toko READ

Menampilkan semua toko milik Anda beserta statistik bulanan (omzet, pengeluaran, laba) dan jumlah kasir.

Parameter

Nama	Tipe	Status	Keterangan
`include_stats`	boolean	Opsional	Sertakan statistik bulanan (default: true)

Contoh Request

                {
  "name": "daftar_toko",
  "arguments": {
    "include_stats": true
  }
}
            

Contoh Response

                🏪 DAFTAR TOKO (2 toko)
──────────────────────────────────────
1. Warung Barokah Pusat
   📍 Jl. Merdeka No. 10
   👥 Kasir: 3 aktif / 4 total
   💰 Omzet bulan ini: Rp 12.500.000
   📤 Pengeluaran: Rp 8.200.000
   📈 Laba: Rp 4.300.000

2. Cabang Sudirman
   📍 Jl. Sudirman No. 45
   👥 Kasir: 2 aktif / 2 total
   💰 Omzet bulan ini: Rp 8.100.000
            

daftar_kasir READ

Menampilkan semua kasir dengan informasi toko, status, target, dan performa bulanan.

Parameter

Nama	Tipe	Status	Keterangan
`store_id`	string	Opsional	Filter kasir berdasarkan toko tertentu

Contoh Request

                {
  "name": "daftar_kasir",
  "arguments": {}
}
            

daftar_barang READ

Menampilkan master barang dan top 15 produk terlaris dalam 30 hari terakhir berdasarkan omzet.

Parameter

Nama	Tipe	Status	Keterangan
`store_id`	string	Opsional	Filter berdasarkan toko tertentu
`include_sales`	boolean	Opsional	Sertakan data penjualan 30 hari (default: true)

Contoh Request

                {
  "name": "daftar_barang",
  "arguments": {
    "include_sales": true
  }
}
            

daftar_menu READ

Menampilkan menu toko yang dikelompokkan berdasarkan kategori, beserta harga dan status ketersediaan.

Parameter

Nama	Tipe	Status	Keterangan
`store_id`	string	Opsional	ID toko (wajib jika punya lebih dari 1 toko)

Contoh Request

                {
  "name": "daftar_menu",
  "arguments": {
    "store_id": "abc-123-def"
  }
}
            

riwayat_transaksi READ

Menampilkan detail riwayat transaksi kasir dengan line items, payment breakdown, dan filter tanggal. Maksimal 50 transaksi per request.

Parameter

Nama	Tipe	Status	Keterangan
`store_id`	string	Opsional	Filter berdasarkan toko
`start_date`	string	Opsional	Tanggal awal YYYY-MM-DD (default: 7 hari lalu)
`end_date`	string	Opsional	Tanggal akhir YYYY-MM-DD (default: hari ini)
`limit`	integer	Opsional	Jumlah transaksi (default: 20, max: 50)

Contoh Request

                {
  "name": "riwayat_transaksi",
  "arguments": {
    "start_date": "2025-07-01",
    "end_date": "2025-07-15",
    "limit": 10
  }
}
            

Troubleshooting

Masalah umum yang mungkin ditemui beserta solusinya.

Masalah	Kemungkinan Penyebab	Solusi
`401 Unauthorized`	Token tidak valid, salah copy, atau sudah di-revoke	Buat token baru di halaman API Key dan update config Claude
`MCP server tidak muncul di Claude`	Config belum disimpan atau Claude belum di-restart	Simpan file config → tutup Claude sepenuhnya → buka kembali
`Claude Code: server not found`	Perintah `claude mcp add` belum dijalankan atau token salah	Jalankan `claude mcp list` untuk verifikasi, lalu `claude mcp remove ngaturbisnis` dan tambah ulang
`Toko tidak ditemukan`	Belum ada toko aktif, atau store_id salah	Minta Claude: "Buat toko baru bernama X" atau cek UUID toko via `baca_ringkasan_bisnis`
`Belum ada kasir aktif`	Tool `catat_pemasukan` / `buat_transaksi_kasir` butuh kasir	Tambahkan kasir di dashboard ngaturbisnis.com → Master → Kasir
`Kategori tidak valid`	Nilai kategori pengeluaran di luar daftar yang tersedia	Gunakan: Bahan Baku, Operasional, Gaji, Utilitas, Transportasi, Pemasaran, Peralatan, atau Lainnya