Menghubungkan klien AI melalui MCP

Dureach menyediakan server MCP untuk pembacaan dan tindakan di https://app.dureach.com/mcp untuk klien MCP eksternal. Klien menyelesaikan persetujuan OAuth, memanggil tools/list untuk menemukan tool yang diberikan, lalu memanggil tools/call dengan nama tool dureach.* dan argumen bertipe.

Hasil alat dikirim ke klien eksternal dan dapat diproses atau disimpan oleh penyedianya. Tinjau ketentuan penanganan, penyimpanan, dan akses data sebelum menghubungkan. Minta hanya kolom yang diperlukan; jangan masukkan detail kontak atau catatan pelanggan ke percakapan bersama, tangkapan layar, atau log.

Apa yang diperlukan sebelum menghubungkan?

Ruang kerja Dureach dengan kapabilitas platform agen yang diaktifkan. Tanpa kapabilitas tersebut, admisi mengembalikan plan_capability_required.
Klien OAuth yang dapat menyelesaikan pemberian persetujuan melalui peramban. MCP hanya menerima token bearer OAuth; kunci API REST ditolak pada /mcp.
Selesaikan persetujuan di browser sebagai anggota ruang kerja. Simpan kredensial di penyimpanan terlindungi milik klien atau pengelola rahasia sisi server. Jangan tempelkan token ke percakapan, dokumen bersama, tangkapan layar, atau tiket.
Klien MCP yang mendukung HTTP streamable dengan respons JSON (misalnya, Claude Desktop dengan konektor MCP, Cursor, atau klien Python kustom yang dibangun dengan SDK mcp).

Bagaimana cara kerja persetujuan OAuth untuk MCP?

Daftarkan atau buka klien OAuth Anda dan mulai hibah otorisasi untuk ruang kerja.
Pilih hanya cakupan yang dibutuhkan klien (lihat Persetujuan, kebijakan, dan kuota MCP). Klien pelaporan mungkin hanya memerlukan companies:read dan trade:read; klien penjangkauan memerlukan pemberian tambahan leads:create atau emails:send.
Selesaikan persetujuan di browser sebagai anggota ruang kerja. Simpan kredensial di penyimpanan terlindungi milik klien atau pengelola rahasia sisi server. Jangan tempelkan token ke percakapan, dokumen bersama, tangkapan layar, atau tiket.
Kirim token sebagai Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN pada setiap permintaan HTTP MCP. Jauhkan token dari URL, tangkapan layar, log, dan tiket.
Jika klien harus bertindak untuk ruang kerja tertentu, kirim X-Workspace-ID dengan ID ruang kerja token. Nilai yang tidak sesuai mengembalikan workspace_context_required.

Periksa dokumen metadata di /.well-known/oauth-protected-resource/mcp ketika pustaka klien Anda memerlukan nilai discovery.

Endpoint dan protokol apa yang digunakan klien?

Gunakan https://app.dureach.com/mcp persis dengan klien MCP yang mendukung streamable HTTP.
Selesaikan persetujuan OAuth untuk ruang kerja yang dituju; simpan kredensial di penyimpanan terlindungi milik klien atau pengelola rahasia sisi server.
Jika host atau asal ditolak, periksa URL koneksi dan hubungi dukungan. Jangan menghapus atau memalsukan header keamanan untuk melewati penolakan.
Simpan request_id respons untuk pemecahan masalah; jangan sertakan token atau baris hasil dalam log bersama.

Bagaimana cara mencantumkan tool yang tersedia?

Setelah persetujuan OAuth, panggil tools/list. Setiap alat yang tersedia menyertakan nama dan skema argumen. Gunakan skema yang dikembalikan untuk memvalidasi permintaan sebelum memanggil alat.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Gunakan tools/list untuk melihat alat yang tersedia bagi koneksi Anda. Ketersediaan bergantung pada izin yang diberikan dan akses ruang kerja. Mulai dengan izin baca; minta administrator meninjau akses yang belum tersedia alih-alih meminta izin luas.

Bagaimana cara memanggil tool?

Kirim permintaan tools/call dengan nama lengkap berawalan dureach. dan objek argumen. Nama yang tidak dikenal atau nama tanpa awalan mengembalikan Unknown tool (INVALID_PARAMS):

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "dureach.companies.search",
    "arguments": {"query": "industrial valves", "page": 1, "limit": 10}
  }
}

Hasil yang berhasil mengembalikan satu item teks berisi JSON ditambah salinan structuredContent yang telah diurai. Kegagalan aplikasi mengembalikan isError: true dengan {"error": {"code": "...", "details": {...}}, "request_id": "..."}. Simpan request_id untuk dukungan dan penanganan pengulangan. Batas argumen lengkap tercantum dalam Referensi tool MCP.

Bagaimana cara mengonfigurasi klien umum?

Claude Desktop atau klien berbasis konektor lainnya

Tambahkan server HTTP streamable dengan URL https://app.dureach.com/mcp.
Konfigurasikan autentikasi OAuth dengan ID klien dari pendaftaran OAuth Dureach Anda dan URL metadata sumber daya MCP.
Selesaikan persetujuan, lalu verifikasi bahwa konektor mencantumkan tool yang diawali dengan dureach..
Mulai dengan dureach.workspace.context dan dureach.workspace.capabilities sebelum menjalankan pencarian data.

Klien Python kustom (SDK `mcp` resmi)

import os

from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

MCP_URL = "https://app.dureach.com/mcp"
TOKEN = os.environ["DUREACH_OAUTH_ACCESS_TOKEN"]

async def main():
    async with streamable_http_client(
        MCP_URL, headers={"Authorization": f"Bearer {TOKEN}"}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            result = await session.call_tool(
                "dureach.companies.search",
                {"query": "industrial valves", "page": 1, "limit": 10},
            )
            print("Search completed")

Ganti token dan kueri dengan nilai Anda sendiri. Jangan pernah menyimpan token di repositori kode.

Pemeriksaan apa yang harus dijalankan sebelum membagikan akses?

Panggil dureach.workspace.context dan konfirmasi bahwa ID ruang kerja dan cakupan yang dikembalikan sesuai dengan ruang kerja yang dimaksud.
Panggil dureach.workspace.capabilities dan konfirmasi bahwa hanya tindakan yang diharapkan yang muncul.
Jalankan satu pembacaan terbatas (misalnya, companies.search dengan limit: 5) dan konfirmasi field penomoran halaman.
Untuk jalur tulis, jalankan terlebih dahulu dengan dry_run: true; lihat Persetujuan, kebijakan, dan kuota MCP.
Cabut token di /oauth/revoke atau di Settings → Integrations ketika akses tidak lagi diperlukan.