What Is MCP? Understanding Model Context Protocol Through Bugoon's Implementation

AI-powered editors like Claude Code and Cursor have become serious development tools — but their real power comes from connecting them to your own data and workflows. Model Context Protocol (MCP) is the open standard that makes those connections possible. This post explains MCP concepts concretely, using the Bugoon MCP server as a working case study.

1. What Is MCP?

Model Context Protocol is a lightweight, JSON-RPC-based protocol that lets AI editors communicate with external tools in a standardized way. Before MCP, every editor had its own plugin format, every tool had its own integration layer, and connecting them was a bespoke engineering project each time.

MCP solves this by defining a common language. An AI host that speaks MCP can connect to any compliant server — whether that server wraps a bug tracker, a database, a file system, or an internal API — without knowing anything specific about the underlying system.

For Bugoon, this means Claude Code can list unresolved bug reports, read their full detail, and propose a fix — all without leaving the editor and without any custom editor plugin.

2. The Three-Layer Model

Every MCP integration involves three distinct roles:

Host — the AI editor or agent runtime. Claude Code is the host in Bugoon's setup. The host is responsible for spawning MCP server processes, routing tool calls, and rendering results back to the user.
Server — a lightweight process that exposes tools, prompts, and resources over the MCP protocol. @rubyjobs-jp/bugoon-mcp-server is Bugoon's server. It talks to the Bugoon REST API on behalf of the host.
Client — the MCP library embedded inside the server that handles the low-level protocol details. Bugoon's server uses @modelcontextprotocol/sdk, which abstracts JSON-RPC serialization, capability negotiation, and transport setup.

The host and server communicate through a transport layer. The client library on the server side manages that transport so application code only needs to register handlers.

3. How STDIO Transport Works

Bugoon's MCP server uses STDIO transport — the simplest and most portable option. The host spawns the server as a child process and communicates with it over standard input and standard output. Each JSON-RPC message is a single line on stdin or stdout.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_bug_reports",
    "arguments": { "project_id": "demo-699", "status": "open" }
  }
}

The server reads from stdin, executes the handler, and writes the response to stdout. Because the protocol is newline-delimited JSON, it works across any language boundary — the host can be written in TypeScript, the server in Python, and they interoperate without modification.

Setting up STDIO transport with the SDK takes a single call:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({ name: "bugoon-mcp-server", version: "1.0.0" });
const transport = new StdioServerTransport();
await server.connect(transport);

4. Tools, Prompts, and Resources

MCP distinguishes three types of capabilities a server can expose.

Tools

Tools are callable functions. The host can invoke them with arguments, and they return a result. Bugoon's server exposes the following tools:

list_bug_reports — fetch open or resolved reports for a project
get_bug_report — retrieve full detail for a single report, including screenshot path, interaction steps, and annotation data
update_bug_report_status — mark a report as resolved or in-progress after a fix is applied

Tools are the right primitive when you want the AI to take an action or retrieve structured data on demand.

Prompts

Prompts are reusable message templates. Unlike tools, they do not execute arbitrary logic — they return a pre-structured message array that the host inserts into the conversation. They are useful for standardizing how the AI approaches a recurring task.

Resources

Resources expose static or semi-static content — documentation, configuration files, database schemas — that the host can attach to context. Bugoon does not currently expose resources, but they are the right choice for things like attaching your OpenAPI spec so the AI understands your API surface before writing a fix.

5. How Bugoon's `fix_bug` Prompt Injects Context

The most interesting primitive in Bugoon's server is the fix_bug prompt. When invoked, it does not just return a static string — it calls get_bug_report internally, fetches the full report detail, and injects it into the prompt template before returning the message array to the host.

server.setRequestHandler(GetPromptRequestSchema, async (request) => {
  if (request.params.name === "fix_bug") {
    const reportId = request.params.arguments?.report_id as string;

    // Fetch live data from the Bugoon API
    const report = await bugoonClient.getBugReport(reportId);

    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `You are fixing a bug reported in Bugoon.\n\n` +
              `## Bug Report: ${report.title}\n` +
              `**Status**: ${report.status}\n` +
              `**Description**: ${report.description}\n` +
              `**Steps to reproduce**:\n${report.interaction_steps
                .map((s: string, i: number) => `${i + 1}. ${s}`)
                .join("\n")}\n\n` +
              `Locate the root cause and propose a minimal fix. ` +
              `After applying the fix, call update_bug_report_status to mark it resolved.`
          }
        }
      ]
    };
  }
});

This pattern — fetching live context inside a prompt handler — is what makes MCP prompts more powerful than static system-prompt snippets. The AI receives the exact bug details at the moment it starts the fix, not a stale copy from whenever the prompt was authored. Combined with the update_bug_report_status tool, the entire fix-and-close loop can happen inside one editor session.

6. Summary

MCP gives AI editors a standard way to connect to any external system. The three-layer model — Host, Server, Client — keeps each concern separate: the editor handles user interaction, the server owns domain logic, and the SDK handles protocol plumbing. STDIO transport keeps deployment simple — no ports, no auth headers, just a spawned process.

Bugoon's implementation shows the pattern in action: tools for data retrieval and state mutation, and a prompt that auto-injects live bug context so the AI arrives at a fix task fully informed. If you are building your own MCP server, the same structure applies to any domain — replace the Bugoon API calls with your own data source, register your handlers, and any MCP-compatible host can start using your tools immediately.

The Bugoon MCP server is published on npm as @rubyjobs-jp/bugoon-mcp-server. The source follows the patterns described here and is a useful reference if you are building your first server with the TypeScript SDK.