Cara Mengintegrasikan LangChain dengan Server MCP Menggunakan langchain-mcp-adapters

Protokol Konteks Model (MCP) bertujuan untuk menstandarisasi cara model AI berinteraksi dengan alat dan layanan eksternal. Ia mendefinisikan antarmuka umum, yang memungkinkan model dan penyedia alat yang berbeda untuk berkomunikasi secara efektif. Namun, mengintegrasikan alat yang sesuai dengan MCP ini secara langsung ke dalam kerangka kerja AI yang ada seperti LangChain memerlukan adaptasi.

Di sinilah pustaka langchain-mcp-adapters berperan. Ia bertindak sebagai jembatan penting, dengan mulus menerjemahkan alat MCP ke dalam format yang dapat dipahami dan digunakan oleh LangChain dan kerangka kerja agennya yang kuat, LangGraph. Pustaka ini menyediakan pembungkus ringan, yang memungkinkan pengembang untuk memanfaatkan ekosistem alat MCP yang berkembang dalam aplikasi LangChain mereka.

Fitur utama meliputi:

Konversi Alat MCP: Secara otomatis mengonversi alat MCP menjadi objek BaseTool yang kompatibel dengan LangChain.
Klien Multi-Server: Menyediakan klien yang kuat (MultiServerMCPClient) yang mampu terhubung ke beberapa server MCP secara bersamaan, mengumpulkan alat dari berbagai sumber.
Fleksibilitas Transportasi: Mendukung transportasi komunikasi MCP umum seperti input/output standar (stdio) dan Server-Sent Events (sse).

Tutorial ini akan memandu Anda melalui pengaturan server MCP, menghubungkannya menggunakan pustaka adaptor, dan mengintegrasikan alat yang dimuat ke dalam agen LangGraph.

💡

Ingin alat Pengujian API hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform Terintegrasi, All-in-One untuk Tim Pengembang Anda untuk bekerja bersama dengan produktivitas maksimum?

Apidog memberikan semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!

button

Apa itu Server MCP? Bagaimana Cara Kerjanya?

Memahami beberapa konsep inti sangat penting sebelum menyelami contoh:

Server MCP:

Server MCP mengekspos alat (fungsi) yang dapat dipanggil oleh model AI.
Pustaka mcp (dependensi dari langchain-mcp-adapters) menyediakan alat seperti FastMCP untuk dengan mudah membuat server ini di Python.
Alat didefinisikan menggunakan dekorator @mcp.tool(), yang secara otomatis menyimpulkan skema input dari petunjuk tipe dan docstring.
Server juga dapat mendefinisikan perintah menggunakan @mcp.prompt(), menyediakan starter atau instruksi percakapan terstruktur.
Server dijalankan dengan menentukan mekanisme transportasi (misalnya, mcp.run(transport="stdio") atau mcp.run(transport="sse")). stdio menjalankan server sebagai subproses yang berkomunikasi melalui input/output standar, sedangkan sse biasanya menjalankan server web sederhana untuk komunikasi.

Klien MCP (langchain-mcp-adapters):

Peran klien adalah untuk terhubung ke satu atau lebih server MCP.
Ia menangani detail protokol komunikasi (stdio, sse).
Ia mengambil daftar alat yang tersedia dan definisinya (nama, deskripsi, skema input) dari server.
Kelas MultiServerMCPClient adalah cara utama untuk mengelola koneksi, terutama saat berurusan dengan beberapa server alat.

Konversi Alat:

Alat MCP memiliki format definisi sendiri. LangChain menggunakan struktur kelas BaseTool-nya.
Pustaka langchain-mcp-adapters menyediakan fungsi seperti load_mcp_tools (ditemukan di langchain_mcp_adapters.tools) yang terhubung ke server melalui ClientSession aktif, mencantumkan alat MCP, dan membungkus masing-masing ke dalam StructuredTool LangChain.
Pembungkus ini menangani pemanggilan panggilan alat MCP yang sebenarnya (session.call_tool) ketika agen LangChain memutuskan untuk menggunakan alat tersebut dan memformat respons dengan benar.

Konversi Perintah:

Mirip dengan alat, perintah MCP dapat diambil menggunakan load_mcp_prompt (dari langchain_mcp_adapters.prompts).
Fungsi ini mengambil struktur perintah dari server MCP dan mengubahnya menjadi daftar objek HumanMessage atau AIMessage LangChain, yang cocok untuk menginisialisasi atau memandu percakapan.

Instal Langchain-mcp-adapter

Pertama, instal paket yang diperlukan:

pip install langchain-mcp-adapters langgraph langchain-openai # Atau integrasi LLM LangChain pilihan Anda

Anda juga perlu mengonfigurasi kunci API untuk penyedia model bahasa pilihan Anda, biasanya dengan mengatur variabel lingkungan:

export OPENAI_API_KEY=<your_openai_api_key>
# atau export ANTHROPIC_API_KEY=<...> dll.

Bangun Server MCP Tunggal Cepat dengan langchain-mcp-adapters

Mari kita bangun contoh sederhana: server MCP yang menyediakan fungsi matematika dan agen LangGraph yang menggunakan fungsi-fungsi tersebut.

Langkah 1: Buat Server MCP (math_server.py)

# math_server.py
from mcp.server.fastmcp import FastMCP

# Inisialisasi server MCP dengan nama
mcp = FastMCP("Math")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Tambahkan dua angka"""
    print(f"Executing add({a}, {b})") # Log sisi server
    return a + b

@mcp.tool()
def multiply(a: int, b: int) -> int:
    """Kalikan dua angka"""
    print(f"Executing multiply({a}, {b})") # Log sisi server
    return a * b

# Contoh definisi perintah
@mcp.prompt()
def configure_assistant(skills: str) -> list[dict]:
    """Mengonfigurasi asisten dengan keterampilan yang ditentukan."""
    return [
        {
            "role": "assistant", # Sesuai dengan AIMessage
            "content": f"Anda adalah asisten yang membantu. Anda memiliki keterampilan berikut: {skills}. Selalu gunakan hanya satu alat dalam satu waktu.",
        }
    ]

if __name__ == "__main__":
    # Jalankan server menggunakan transportasi stdio
    print("Memulai server Math MCP melalui stdio...")
    mcp.run(transport="stdio")

Simpan kode ini sebagai math_server.py.

Langkah 2: Buat Klien dan Agen (client_app.py)

import asyncio
import os
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

from langchain_mcp_adapters.tools import load_mcp_tools
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

# --- PENTING: Perbarui jalur ini ---
# Dapatkan jalur absolut ke file math_server.py
current_dir = os.path.dirname(os.path.abspath(__file__))
math_server_script_path = os.path.join(current_dir, "math_server.py")
# ---

async def main():
    model = ChatOpenAI(model="gpt-4o") # Atau model pilihan Anda

    # Konfigurasikan parameter untuk menjalankan skrip math_server.py
    server_params = StdioServerParameters(
        command="python", # Perintah untuk dieksekusi
        args=[math_server_script_path], # Argumen (jalur skrip)
        # cwd=..., env=... # Direktori kerja dan variabel lingkungan opsional
    )

    print("Menghubungkan ke server MCP...")
    # Buat koneksi menggunakan pengelola konteks stdio_client
    async with stdio_client(server_params) as (read, write):
        # Buat ClientSession menggunakan aliran baca/tulis
        async with ClientSession(read, write) as session:
            print("Menginisialisasi sesi...")
            # Jabat tangan dengan server
            await session.initialize()
            print("Sesi diinisialisasi.")

            print("Memuat alat MCP...")
            # Ambil alat MCP dan konversikan ke alat LangChain
            tools = await load_mcp_tools(session)
            print(f"Alat yang dimuat: {[tool.name for tool in tools]}")

            # Buat agen LangGraph ReAct menggunakan model dan alat yang dimuat
            agent = create_react_agent(model, tools)

            print("Memanggil agen...")
            # Jalankan agen
            inputs = {"messages": [("human", "berapa (3 + 5) * 12?")]}
            async for event in agent.astream_events(inputs, version="v1"):
                 print(event) # Alirkan peristiwa untuk observabilitas

            # Atau dapatkan respons akhir secara langsung
            # final_response = await agent.ainvoke(inputs)
            # print("Respons agen:", final_response['messages'][-1].content)

if __name__ == "__main__":
    asyncio.run(main())

Simpan ini sebagai client_app.py di direktori yang sama dengan math_server.py.

Untuk Menjalankan:

Jalankan skrip klien:

python client_app.py

Skrip klien akan secara otomatis memulai math_server.py sebagai subproses, terhubung ke sana, memuat alat add dan multiply, dan menggunakan agen LangGraph untuk menyelesaikan masalah matematika dengan memanggil alat-alat tersebut melalui server MCP. Anda akan melihat log dari klien dan server.

Menghubungkan ke Beberapa Server MCP

Seringkali, Anda ingin menggabungkan alat dari server khusus yang berbeda. MultiServerMCPClient membuat ini menjadi mudah.

Langkah 1: Buat Server Lain (weather_server.py)

Mari kita buat server cuaca yang berjalan menggunakan transportasi SSE.

# weather_server.py
from mcp.server.fastmcp import FastMCP
import uvicorn # Perlu: pip install uvicorn

mcp = FastMCP("Weather")

@mcp.tool()
async def get_weather(location: str) -> str:
    """Dapatkan cuaca untuk lokasi."""
    print(f"Executing get_weather({location})")
    # Dalam skenario nyata, ini akan memanggil API cuaca
    return f"Selalu cerah di {location}"

if __name__ == "__main__":
    # Jalankan server menggunakan transportasi SSE (memerlukan server ASGI seperti uvicorn)
    # Pustaka mcp secara implisit membuat aplikasi FastAPI untuk SSE.
    # Secara default, ia berjalan di port 8000 di endpoint /sse.
    print("Memulai server Weather MCP melalui SSE di port 8000...")
    # uvicorn.run(mcp.app, host="0.0.0.0", port=8000) # Anda dapat menjalankan secara manual
    mcp.run(transport="sse", host="0.0.0.0", port=8000) # Atau gunakan kenyamanan mcp.run

Simpan ini sebagai weather_server.py.

Langkah 2: Perbarui Klien untuk Menggunakan MultiServerMCPClient (multi_client_app.py)

import asyncio
import os
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

# --- PENTING: Perbarui jalur ---
current_dir = os.path.dirname(os.path.abspath(__file__))
math_server_script_path = os.path.join(current_dir, "math_server.py")
# Server cuaca berjalan secara terpisah, terhubung melalui URL
# ---

async def main():
    model = ChatOpenAI(model="gpt-4o")

    # Definisikan koneksi untuk beberapa server
    server_connections = {
        "math_service": { # Nama unik untuk koneksi ini
            "transport": "stdio",
            "command": "python",
            "args": [math_server_script_path],
            # Tambahkan parameter StdioConnection lainnya jika diperlukan (env, cwd, dll.)
        },
        "weather_service": { # Nama unik untuk koneksi ini
            "transport": "sse",
            "url": "http://localhost:8000/sse", # URL tempat weather_server berjalan
            # Tambahkan parameter SSEConnection lainnya jika diperlukan (headers, timeout, dll.)
        }
    }

    print("Menghubungkan ke beberapa server MCP...")
    # Gunakan pengelola konteks MultiServerMCPClient
    async with MultiServerMCPClient(server_connections) as client:
        print("Koneksi dibuat.")

        # Dapatkan *semua* alat dari *semua* server yang terhubung
        all_tools = client.get_tools()
        print(f"Alat yang dimuat: {[tool.name for tool in all_tools]}")

        # Buat agen dengan daftar alat gabungan
        agent = create_react_agent(model, all_tools)

        # --- Berinteraksi dengan agen ---
        print("\nMemanggil agen untuk kueri matematika...")
        math_inputs = {"messages": [("human", "berapa (3 + 5) * 12?")]}
        math_response = await agent.ainvoke(math_inputs)
        print("Respons Matematika:", math_response['messages'][-1].content)

        print("\nMemanggil agen untuk kueri cuaca...")
        weather_inputs = {"messages": [("human", "bagaimana cuaca di nyc?")]}
        weather_response = await agent.ainvoke(weather_inputs)
        print("Respons Cuaca:", weather_response['messages'][-1].content)

        # --- Contoh: Mendapatkan perintah ---
        # print("\nMendapatkan perintah server matematika...")
        # prompt_messages = await client.get_prompt(
        #     server_name="math_service", # Gunakan nama yang ditentukan dalam koneksi
        #     prompt_name="configure_assistant",
        #     arguments={"skills": "basic arithmetic"}
        # )
        # print("Perintah:", prompt_messages)


if __name__ == "__main__":
    # Mulai server cuaca terlebih dahulu di terminal terpisah:
    # python weather_server.py
    # Kemudian jalankan skrip klien ini:
    asyncio.run(main())

Simpan ini sebagai multi_client_app.py.

Untuk Menjalankan:

Mulai server cuaca di satu terminal: python weather_server.py
Jalankan aplikasi multi-klien di terminal lain: python multi_client_app.py

MultiServerMCPClient akan memulai subproses math_server.py (stdio) dan terhubung ke weather_server.py (sse) yang sedang berjalan. Ia mengumpulkan alat (add, multiply, get_weather) yang kemudian tersedia untuk agen LangGraph.

Integrasi dengan Server API LangGraph

Anda dapat menyebarkan agen LangGraph menggunakan alat MCP sebagai layanan API persisten menggunakan langgraph deploy. Kuncinya adalah mengelola siklus hidup MultiServerMCPClient dengan benar dalam konteks aplikasi LangGraph.

Buat file graph.py:

# graph.py
from contextlib import asynccontextmanager
import os
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI # Atau Anthropic, dll.

# --- PENTING: Perbarui jalur ---
# Dengan asumsi server relatif terhadap tempat server LangGraph berjalan
math_server_script_path = os.path.abspath("math_server.py")
# ---

# Definisikan koneksi (pastikan jalur/URL benar untuk lingkungan server)
server_connections = {
    "math_service": {
        "transport": "stdio",
        "command": "python",
        "args": [math_server_script_path],
    },
    "weather_service": {
        "transport": "sse",
        "url": "http://localhost:8000/sse", # Server cuaca harus berjalan secara independen
    }
}

model = ChatOpenAI(model="gpt-4o")

# Gunakan pengelola konteks asinkron untuk menangani pengaturan/penghancuran klien
@asynccontextmanager
async def lifespan(_app): # LangGraph mengharapkan struktur ini untuk manajemen masa pakai
    async with MultiServerMCPClient(server_connections) as client:
        print("Klien MCP diinisialisasi dalam masa pakai.")
        # Buat agen *di dalam* konteks tempat klien aktif
        agent = create_react_agent(model, client.get_tools())
        yield {"agent": agent} # Jadikan agen tersedia

# Tidak perlu definisi grafik utama terpisah jika masa pakai menghasilkannya

Konfigurasikan langgraph.json Anda (atau pyproject.toml di bawah [tool.langgraph]) untuk menggunakan definisi grafik ini dengan pengelola masa pakai:

// langgraph.json (contoh)
{
  "dependencies": ["."], // Atau tentukan paket yang diperlukan
  "graphs": {
    "my_mcp_agent": {
      "entrypoint": "graph:agent", // Mengacu pada kunci yang dihasilkan oleh masa pakai
      "lifespan": "graph:lifespan"
    }
  }
}

Sekarang, ketika Anda menjalankan langgraph up, fungsi lifespan akan dieksekusi, memulai MultiServerMCPClient (dan server matematika stdio). Agen yang dibuat dalam konteks ini akan dilayani oleh LangGraph. Ingat server cuaca SSE masih perlu dijalankan secara terpisah.

Transportasi Server (stdio vs. SSE)

stdio:

Komunikasi: Melalui aliran input dan output standar proses server.
Pro: Pengaturan sederhana untuk pengembangan lokal; klien mengelola siklus hidup server. Tidak ada jaringan yang terlibat.
Kontra: Terikat erat; kurang cocok untuk sistem terdistribusi atau server non-Python. Memerlukan konfigurasi command dan args.

sse (Server-Sent Events):

Komunikasi: Melalui HTTP menggunakan protokol SSE. Server berjalan sebagai layanan web (seringkali menggunakan FastAPI/Uvicorn secara implisit).
Pro: Protokol web standar; cocok untuk server jaringan/jarak jauh, berpotensi diimplementasikan dalam bahasa yang berbeda. Server berjalan secara independen.
Kontra: Memerlukan server untuk berjalan secara terpisah. Membutuhkan konfigurasi url.

Pilih transportasi berdasarkan kebutuhan penyebaran Anda.

Konfigurasi Klien Tingkat Lanjut untuk Penyiapan langchain-mcp-adapters

Kamus StdioConnection dan SSEConnection dalam MultiServerMCPClient menerima parameter opsional tambahan untuk kontrol yang lebih baik:

Stdio: env (variabel lingkungan khusus untuk subproses), cwd (direktori kerja), encoding, encoding_error_handler, session_kwargs (diteruskan ke mcp.ClientSession).
SSE: headers (header HTTP khusus), timeout (waktu tunggu koneksi HTTP), sse_read_timeout, session_kwargs.

Lihat definisi MultiServerMCPClient di langchain_mcp_adapters/client.py untuk detailnya.

Kesimpulan (100 kata)

Pustaka langchain-mcp-adapters secara efektif menjembatani kesenjangan antara Protokol Konteks Model yang distandarisasi dan ekosistem LangChain yang fleksibel. Dengan menyediakan MultiServerMCPClient dan konversi alat otomatis, ia memungkinkan pengembang untuk dengan mudah menggabungkan beragam alat yang sesuai dengan MCP ke dalam agen LangChain dan aplikasi LangGraph mereka.

Alur kerja inti melibatkan:

Mendefinisikan alat (dan secara opsional perintah) di server MCP menggunakan @mcp.tool().
Mengonfigurasi MultiServerMCPClient dengan detail koneksi (stdio atau sse) untuk setiap server.
Menggunakan pengelola konteks klien (async with ...) untuk terhubung dan mengambil alat melalui client.get_tools().
Meneruskan alat yang kompatibel dengan LangChain yang diambil ke agen Anda (create_react_agent atau agen khusus).

Ini memungkinkan pembangunan aplikasi AI modular yang kuat yang memanfaatkan alat eksternal khusus melalui protokol standar. Jelajahi contoh dan pengujian dalam repositori untuk wawasan lebih lanjut.