Panduan Self-Hosting Server MCP Didit (ID)

Poin-poin Penting

• Server Model Context Protocol (MCP) Didit adalah sumber terbuka di bawah lisensi MIT. Anda dapat membangunnya dari repositori GitHub publik dan menjalankannya dengan Docker, Node.js, atau transportasi stdio tanpa kepala.
• Self-hosting mengubah tempat proses MCP berjalan, bukan cara ia mencapai Didit. Setiap mode mengautentikasi sebagai pengguna Didit dengan token akses Bearer. Tidak ada mode kunci API aplikasi untuk alat MCP.
• Katalog self-hosted lengkap berisi 121 alat. Titik akhir Open Authorization (OAuth) yang dihosting secara sengaja mengekspos 115. Contoh dalam sumber saat ini termasuk didit_context_get, didit_session_create, dan didit_transaction_screen_wallet.
• Titik masuk HTTP tanpa status dan menerima lalu lintas MCP melalui permintaan POST. Server dan transportasi baru dibuat per permintaan, sehingga penyeimbang beban tidak memerlukan afinitas sesi.
• Gunakan /healthz untuk pemeriksaan kontainer dan penyeimbang beban. Konfigurasikan URI sumber daya publik, asal otorisasi, mode verifikasi token, dan rahasia secara eksplisit sebelum mengekspos layanan.

Titik akhir yang dihosting nyaman, tetapi bukan pilihan operasional yang tepat untuk setiap tim. Sebuah perusahaan mungkin perlu menjaga integrasi di dalam batas jaringan sendiri, mengontrol citra runtime, merutekan lalu lintas melalui lapisan keluar pribadi, atau menerapkan kebijakan observabilitas dan manajemen perubahan sendiri. Repositori Didit MCP mendukung model penyebaran tersebut tanpa membuat permukaan produk terpisah.

Panduan ini hanya berfokus pada pengoperasian server. Untuk katalog dan perilaku alat, gunakan referensi alat Didit MCP. Untuk pengaturan klien terhadap titik akhir yang dikelola, gunakan panduan instalasi Claude. Referensi teknis lengkap ada di gambaran umum MCP dan dokumentasi otentikasi.

Pilih titik masuk HTTP atau stdio

Repositori membangun satu katalog alat bersama dengan dua titik masuk. dist/http.js menjalankan server sumber daya Express melalui HTTP Streamable tanpa status. Ini adalah pilihan yang tepat untuk layanan bersama yang dijangkau oleh beberapa klien MCP, kontainer, atau pengguna. dist/index.js berjalan di atas stdio dan dimaksudkan untuk proses lokal tanpa kepala yang diluncurkan oleh satu klien.

Kedua titik masuk memanggil logika pengiriman yang sama, dan versi 5 hanya mengekspos alat MCP—bukan sumber daya atau prompt MCP. Keduanya mengautentikasi permintaan hilir sebagai pengguna Didit. Perbedaannya adalah bagaimana kredensial pengguna tersebut mencapai proses: titik masuk HTTP menerima dan memvalidasi token Bearer OAuth pemanggil; titik masuk stdio membaca token Bearer pengguna dari DIDIT_ACCESS_TOKEN.

Self-hosted bukan berarti tanpa kredensial: MCP masih bertindak sebagai pengguna Didit, dan Didit menerapkan peran dan izin organisasi pengguna tersebut untuk setiap panggilan alat.

Bangun dan jalankan dengan Docker

Repositori menyertakan Dockerfile multi-tahap berdasarkan Node 20. Tahap pembangunan menginstal dependensi pengembangan, mengkompilasi TypeScript, dan memangkas paket pengembangan. Tahap produksi berjalan sebagai pengguna node non-root dan menyertakan pemeriksaan kesehatan kontainer.

git clone https://github.com/didit-protocol/mcp.git
cd mcp
cp .env.example .env

docker build -t didit-mcp .
docker run -p 3000:3000 --env-file .env didit-mcp

Sebelum memulai kontainer, ganti default yang dihosting yang mengidentifikasi penyebaran Anda. Minimal, atur MCP_RESOURCE_URI ke asal publik di mana klien mencapai server sumber daya ini, lalu berikan kredensial klien OAuth yang diperlukan untuk introspeksi token. Simpan rahasia di manajer rahasia platform kontainer Anda daripada melakukan file .env yang telah diisi.

MCP_PORT=3000
MCP_RESOURCE_URI=https://mcp.example.com
MCP_AUTHORIZATION_SERVER_ORIGIN=https://business.didit.me
MCP_TOKEN_VERIFY_MODE=introspection
MCP_OAUTH_CLIENT_ID=ganti-dengan-client-id
MCP_OAUTH_CLIENT_SECRET=ganti-dengan-client-secret
MCP_SCOPES_SUPPORTED="didit:management didit:verification"

Hentikan Transport Layer Security (TLS) di ingress atau penyeimbang beban Anda, teruskan permintaan MCP POST ke port 3000, dan pertahankan header Authorization. MCP_RESOURCE_URI yang terlihat secara eksternal harus cocok dengan identitas sumber daya yang diiklankan ke klien; jangan tinggalkan URI Didit yang dikelola untuk asal publik yang berbeda.

Bangun dan jalankan langsung dengan Node.js

Jika platform Anda sudah mengelola runtime Node, gunakan titik masuk HTTP yang sama tanpa kontainer. Paket ini bersifat pribadi dan tidak didistribusikan melalui npm, jadi klon repositori daripada mencoba mengeksekusi paket yang diterbitkan.

git clone https://github.com/didit-protocol/mcp.git
cd mcp
npm install
npm run build
node dist/http.js

Proses ini membaca variabel lingkungan yang sama dengan kontainer. Jalankan di bawah pengawas proses Anda, suntikkan rahasia melalui lingkungan penyebaran, dan rutekan hanya titik akhir yang diperlukan. Permintaan MCP masuk ke POST /mcp. Layanan ini sengaja menolak GET dan DELETE pada rute tersebut karena tidak mempertahankan sesi MCP atau aliran yang dimulai server.

Node.js tidak secara otomatis memuat file .env repositori. Ekspor nilai-nilai di shell, suntikkan melalui manajer layanan, atau gunakan dukungan file lingkungan platform Anda sebelum memulai dist/http.js. Perhatikan juga bahwa npm start meluncurkan titik masuk stdio; gunakan node dist/http.js atau npm run start:http untuk HTTP.

Jalankan tanpa kepala melalui stdio

Untuk agen lokal, pembangun runner, atau proses klien tunggal yang terisolasi, gunakan titik masuk stdio. Berikan token akses pengguna melalui lingkungan dan biarkan klien MCP memiliki siklus hidup proses.

DIDIT_ACCESS_TOKEN=<user-access-token> node dist/index.js

Token ini adalah kredensial Bearer pengguna, bukan kredensial aplikasi. Simpan sebagai rahasia, jauhkan dari riwayat shell dan log, dan rotasi sesuai kebijakan akses Anda. Jika satu penyebaran selalu beroperasi dalam satu organisasi atau aplikasi, MCP_DEFAULT_ORG dan MCP_DEFAULT_APP dapat menyediakan cakupan default tersebut. Jika tidak, alat dapat menyelesaikan cakupan dari argumen eksplisit atau konteks permintaan yang diautentikasi.

Masih belum ada mode kunci API aplikasi di stdio. HTTP yang dihosting sendiri dan stdio yang dihosting sendiri keduanya memanggil titik akhir konsol Didit yang dicakup pengguna, sehingga kunci aplikasi tidak dapat menggantikan token Bearer pengguna.

Konfigurasikan permukaan lingkungan lengkap

src/config.ts saat ini mendukung variabel-variabel berikut. Sebagian besar penyebaran harus mempertahankan default API dan otorisasi Didit produksi dan hanya menimpa identitas sumber daya, konfigurasi verifikasi, dan rahasia yang diperlukan untuk topologi mereka.

Variabel bersama dan stdio

• DIDIT_ACCESS_TOKEN: token Bearer pengguna untuk mode stdio tanpa kepala; tidak ada default.
• DIDIT_API_BASE_URL: basis API verifikasi; default ke https://verification.didit.me/v3.
• DIDIT_AUTH_BASE_URL: basis API otentikasi; default ke https://apx.didit.me/auth/v2.
• MCP_DEFAULT_ORG dan MCP_DEFAULT_APP: default organisasi dan aplikasi opsional untuk penyebaran multi-penyewa.

Variabel server sumber daya HTTP

• MCP_PORT: port listen; default ke 3000.
• MCP_RESOURCE_URI: URI server sumber daya publik; default ke https://mcp.didit.me.
• MCP_AUTHORIZATION_SERVER_ORIGIN: asal server otorisasi; default ke https://business.didit.me.
• MCP_TOKEN_VERIFY_MODE: introspection secara default, atau jwks ketika layanan otorisasi mengeluarkan JSON Web Token (JWT) yang cocok untuk verifikasi tanda tangan lokal.
• MCP_OAUTH_CLIENT_ID dan MCP_OAUTH_CLIENT_SECRET: tidak ada default; digunakan sebagai kredensial HTTP Basic untuk introspeksi Request for Comments (RFC) 7662.
• MCP_OAUTH_INTROSPECT_URL: default ke https://apx.didit.me/auth/v2/introspect/.
• MCP_SCOPES_SUPPORTED: cakupan penemuan yang dipisahkan spasi; default ke didit:management didit:verification.

Penimpaan metadata otorisasi

• DIDIT_AUTH_ISSUER: default ke MCP_AUTHORIZATION_SERVER_ORIGIN.
• DIDIT_OIDC_DISCOVERY_URL: dokumen penemuan OpenID Connect (OIDC); default ke asal otorisasi ditambah /.well-known/oauth-authorization-server.
• DIDIT_JWKS_URL: titik akhir JSON Web Key Set (JWKS); default ke https://apx.didit.me/auth/config/jwks/.
• DIDIT_OIDC_AUTHORIZE_URL: default ke asal otorisasi ditambah /authorize.
• DIDIT_OIDC_TOKEN_URL: default ke asal otorisasi ditambah /api/auth/oauth-token.
• DIDIT_OIDC_REGISTRATION_URL: default ke asal otorisasi ditambah /api/auth/oauth-register.

Gunakan introspection untuk token akses buram. Server mengirimkannya ke titik akhir introspeksi yang dikonfigurasi menggunakan MCP_OAUTH_CLIENT_ID dan MCP_OAUTH_CLIENT_SECRET. Gunakan jwks hanya ketika layanan otorisasi Anda dikonfigurasi untuk mengeluarkan token akses JWT yang ditandatangani untuk klien ini; server kemudian memvalidasi tanda tangan terhadap DIDIT_JWKS_URL. Mengubah mode verifikasi tidak menciptakan model identitas yang berbeda: prinsip yang divalidasi tetap menjadi pengguna Didit.

Klien MCP dapat menggunakan Dynamic Client Registration (DCR) dengan Didit Business Console selama alur otorisasi mereka. Pendaftaran klien tersebut terpisah dari MCP_OAUTH_CLIENT_ID dan MCP_OAUTH_CLIENT_SECRET server sumber daya, yang mengautentikasi permintaan introspeksi. Sediakan kredensial sisi server tersebut melalui saluran penyebaran Didit yang sesuai daripada berasumsi pendaftaran klien dapat menggantikannya.

Pemeriksaan kesehatan dan penskalaan tanpa status

Proses HTTP mengekspos GET /healthz dan mengembalikan JSON yang berisi status, service, dan version. Gambar Docker sudah memeriksanya setiap 30 detik setelah periode startup 15 detik. Anda dapat menggunakan titik akhir yang sama untuk kesiapan Kubernetes, grup target Application Load Balancer, atau probe waktu aktif eksternal.

curl -fsS http://localhost:3000/healthz

Rute MCP dirancang tanpa status. Untuk setiap POST yang diautentikasi, proses ini membuat server baru dan transportasi HTTP Streamable dengan pembuatan sesi dinonaktifkan, meneruskan kredensial pemanggil yang divalidasi melalui konteks per permintaan, menyelesaikan pengiriman, dan menutup transportasi. Tidak ada sesi di memori yang harus ditemukan oleh permintaan selanjutnya pada replika yang sama.

Di sini, tanpa status menggambarkan transportasi MCP dan siklus hidup permintaan. Sesi verifikasi, alur kerja, kasus, dan catatan bisnis lainnya masih tetap ada di layanan hulu Didit.

Akibatnya, replika horizontal tidak memerlukan sesi lengket. Instans yang sehat dapat menangani POST berikutnya, dan penyebaran bergulir tidak memerlukan pengurasan sesi di luar penanganan permintaan yang sedang berlangsung. Perencanaan kapasitas harus berfokus pada konkurensi permintaan, latensi API Didit hilir, dan kebijakan batas waktu dan coba lagi normal Anda.

Validasi sebelum mengekspos layanan

• Konfirmasi /healthz berhasil dari jalur jaringan yang sama dengan penyeimbang beban.
• Konfirmasi permintaan MCP yang tidak diautentikasi menerima tantangan otorisasi daripada keluaran alat.
• Selesaikan alur OAuth 2.1 dengan Proof Key for Code Exchange (PKCE), lalu panggil didit_context_get untuk memverifikasi organisasi dan aplikasi yang diharapkan terlihat.
• Tinjau dokumentasi MCP lanjutan sebelum mengubah titik akhir penemuan atau verifikasi token.
• Gunakan halaman pengembang Didit MCP untuk permukaan terkelola yang didukung dan tautan saat ini.

Jika self-hosting tidak lagi menjadi persyaratan, titik akhir yang dikelola menghilangkan operasi server sumber daya runtime dan OAuth yang dijelaskan di atas. Pengguna Claude dapat menambahkannya dengan tautan langsung konektor Didit. Apakah Anda menjalankan proses atau Didit yang melakukannya, aturan intinya sama: operasi MCP mengautentikasi sebagai pengguna Didit, tidak pernah sebagai kunci API aplikasi.