6.2 Mastra sebagai MCP Server

Tujuan bab

Setelah bab ini kamu bisa:

• Mengekspos tool, agent, dan workflow Mastra sebagai MCP server
• Menjelaskan nama tool yang dihasilkan untuk agent dan workflow
• Memutuskan kapan kamu tidak perlu membuat MCP server
• Menulis description dan instructions server yang berguna bagi klien luar
• Memilih antara transport stdio dan SSE

Prasyarat

• 6.1 MCP sebagai Client
• Paket @mastra/mcp terpasang

Kapan kamu tidak butuh ini

Mari mulai dari yang paling sering salah dipahami. Dokumentasi menyatakannya langsung:

Kalau kamu hanya perlu memakai tool atau agent-mu di dalam aplikasi Mastra-mu sendiri, kamu tidak perlu membuat MCP server.

API ini khusus untuk mengekspos kemampuanmu ke klien MCP eksternal — Cursor, Windsurf, Claude Desktop, atau aplikasi lain yang berbicara MCP.

Jadi tanyakan dulu: siapa yang akan memakainya? Kalau jawabannya "agent saya sendiri di file sebelah", cukup impor tool-nya. MCP server menambah lapisan protokol yang tidak memberi manfaat apa pun dalam kasus itu.

Kalau jawabannya "tim lain", "editor saya", atau "aplikasi di luar sana" — bab ini untukmu.

Membuat server

// src/mastra/mcp/server.ts
import { Agent } from '@mastra/core/agent'
import { createTool } from '@mastra/core/tools'
import { MCPServer } from '@mastra/mcp'
import { z } from 'zod'
import { dataProcessingWorkflow } from '../workflows/data-processing-workflow.ts'

const myAgent = new Agent({
  id: 'my-example-agent',
  name: 'MyExampleAgent',
  description: 'Generalis untuk membantu pertanyaan dasar.',
  instructions: 'Kamu asisten yang membantu.',
  model: 'openai/gpt-5.6-sol',
})

const weatherTool = createTool({
  id: 'getWeather',
  description: 'Ambil cuaca terkini untuk sebuah lokasi.',
  inputSchema: z.object({ location: z.string() }),
  execute: async inputData => `Cuaca di ${inputData.location} sedang cerah.`,
})

export const server = new MCPServer({
  id: 'my-custom-server',
  name: 'My Custom Server',
  version: '1.0.0',
  description: 'Server yang menyediakan data cuaca dan kemampuan agent',
  instructions:
    'Pakai tool yang tersedia untuk membantu pengguna dengan informasi cuaca ' +
    'dan tugas pemrosesan data.',
  tools: { weatherTool },
  agents: { myAgent },
  workflows: { dataProcessingWorkflow },
})

Tiga jenis kemampuan, tiga pola penamaan

Yang menarik dari MCPServer adalah ia tidak hanya mengekspos tool. Agent dan workflow ikut menjadi tool bagi klien luar, dengan pola penamaan yang berbeda:

Yang kamu daftarkan	Menjadi tool bernama	Contoh
tools: { weatherTool }	Nama tool itu sendiri	getWeather
agents: { myAgent }	ask_<key>	ask_myAgent
workflows: { dataProcessingWorkflow }	run_<key>	run_dataProcessingWorkflow

Awalan ask_ dan run_ bukan kebetulan — keduanya menggambarkan sifat yang berbeda. Kamu bertanya kepada agent dan mendapat jawaban hasil penalaran; kamu menjalankan workflow dan mendapat hasil dari proses yang pasti.

Ini juga berarti key yang kamu pakai saat mendaftarkan menjadi bagian dari nama publik. Pilih key yang deskriptif — myAgent menghasilkan ask_myAgent, yang tidak memberitahu klien apa-apa.

Yang dibaca klien

Server MCP-mu akan dipakai oleh agent yang tidak kamu kendalikan, dan satu-satunya cara agent itu memahami kemampuanmu adalah lewat teks yang kamu tulis. Tiga tempat yang menentukan:

description server — menjelaskan server ini secara keseluruhan.

instructions server — panduan cara memakai kemampuannya. Ingat dari 6.1 bahwa klien bisa memilih menambahkan ini ke system prompt agent mereka lewat forwardInstructions. Karena itu, tulis instructions yang membantu, bukan yang memaksa — kamu sedang menulis untuk system prompt orang lain.

description tiap tool dan agent — inilah yang paling menentukan. Perhatikan bahwa myAgent pada contoh punya description sendiri; tanpa itu, klien tidak tahu kapan harus bertanya kepadanya.

Semua prinsip dari 2.2 berlaku di sini, dan taruhannya lebih tinggi — pemakainya tidak bisa membaca kodemu untuk mengklarifikasi.

Kamu tidak akan ada saat mereka memakainya

Menulis deskripsi untuk tool internal itu mudah diperbaiki: kalau agent-mu salah pilih, kamu ubah deskripsinya. Untuk MCP server publik, pemakainya di tempat lain, dan mereka tidak akan melapor — mereka hanya berhenti memakai.

Transport

MCPServer mendukung dua transport MCP:

Transport	Cara kerja	Cocok untuk
stdio	Klien menjalankan servermu sebagai subprocess	Editor lokal — Cursor, Claude Desktop
SSE (HTTP)	Servermu berjalan sebagai layanan HTTP	Akses jarak jauh, beberapa pemakai

Untuk kebanyakan kasus awal, stdio yang kamu pakai: pengguna memasang servermu di konfigurasi editor mereka, dan editor yang menjalankannya.

SSE dipakai saat servermu perlu diakses dari luar mesin — dan begitu itu terjadi, semua pertimbangan produksi dari Bagian 9 mulai berlaku, terutama autentikasi.

Dua arah, satu gambar

Setelah dua bab, inilah gambaran lengkap MCP di Mastra:

Aplikasimu bisa berada di kedua sisi sekaligus: memakai tool orang lain di satu sisi, dan menyediakan kemampuan bagi orang lain di sisi lain.

Kesalahan umum

Gejala: Kamu membangun MCP server, lalu bingung bagaimana memanggilnya dari agent di aplikasi yang sama. Penyebab: Salah paham tentang tujuan MCPServer. Ia untuk klien eksternal; memakainya untuk komunikasi internal berarti melewatkan protokol jaringan untuk sesuatu yang cukup diselesaikan dengan import. Perbaikan: Untuk pemakaian di dalam aplikasi yang sama, impor tool atau agent-nya langsung. Sediakan MCPServer hanya kalau memang ada pemakai di luar.

Gejala: Klien MCP terhubung dan melihat tool-mu, tapi agent di sisi klien jarang memakainya atau memakainya pada saat yang salah. Penyebab: description yang terlalu umum, atau agent yang diekspos tidak punya description sama sekali sehingga ask_<key> tidak berarti apa-apa bagi klien. Perbaikan: Tulis description yang menyebut cakupan dan batasnya untuk tiap tool dan agent yang diekspos. Kamu tidak akan ada di sana untuk menjelaskan.

Coba sendiri

Tantangan: Ekspos kemampuan pustaka-agent dari Bagian 2 sebagai MCP server, lalu pakai dari editormu sendiri sebagai klien.

Ketentuan:

1. Buat MCPServer yang mengekspos tiga hal sekaligus: minimal dua tool, satu agent, dan satu workflow
2. Beri key yang deskriptif — ingat bahwa key menjadi bagian dari nama publik ask_<key> dan run_<key>
3. Tulis description untuk server, untuk tiap tool, dan untuk agent yang diekspos
4. Tulis instructions server dengan mengingat bahwa teks itu mungkin masuk ke system prompt orang lain
5. Jalankan dengan transport stdio, dan daftarkan di konfigurasi MCP editormu
6. Dari editor, minta agent melakukan sesuatu yang membutuhkan tiap kemampuan — satu tool, satu ask_, satu run_
7. Catat nama tool persis seperti yang terlihat di sisi klien

Checklist penerimaan:

• [ ] Ketiga jenis kemampuan terlihat di sisi klien dengan pola penamaan yang benar
• [ ] Nama ask_<key> dan run_<key> yang muncul cukup deskriptif untuk dipahami tanpa membaca kodemu
• [ ] Agent di editormu berhasil memakai ketiganya
• [ ] Kamu bisa menyebutkan satu kemampuan di aplikasimu yang tidak layak diekspos, beserta alasannya
• [ ] instructions server-mu tidak memuat perintah yang memaksa agent klien berperilaku di luar urusan servermu

Petunjuk: Checklist keempat menguji penilaian, bukan keterampilan teknis. Tidak semua kemampuan layak dibuka — tool yang menghapus data, tool yang memakai kredensial pribadimu, atau tool yang mahal dipanggil adalah kandidat untuk tetap di dalam. Kalau kamu tetap ingin mengeksposnya, pemakainya sebaiknya menyalakan requireToolApproval di sisi mereka — dan itu keputusan mereka, bukan kamu.

Ikhtisar

• MCPServer untuk klien eksternal, bukan untuk komunikasi di dalam aplikasimu sendiri. Untuk itu, cukup import.
• Ia mengekspos tiga jenis kemampuan dengan pola penamaan berbeda: tool dengan namanya sendiri, agent menjadi ask_<key>, workflow menjadi run_<key>.
• Key yang kamu pakai saat mendaftarkan menjadi nama publik — pilih yang deskriptif.
• description dan instructions adalah satu-satunya cara pemakai memahami kemampuanmu. Mereka tidak bisa membaca kodemu.
• instructions server bisa masuk ke system prompt agent klien — tulis yang membantu, bukan yang memaksa.
• Dua transport: stdio untuk editor lokal, SSE untuk akses jarak jauh. Yang kedua membawa serta seluruh pertimbangan produksi.

Lanjut ke mana

MCP menyelesaikan batas ke tool dan resource. Tiga protokol lain menyelesaikan batas yang berbeda — ke agent lain, ke coding agent, dan ke runtime milik penyedia: 6.3 A2A & ACP.