This is the multi-page printable view of this section. Click here to print.
Explanation documents discuss and clarify concepts to broaden the reader’s understanding of topics. They provide context and illuminate ideas.
This section provides deeper background on how gomcptest works, its architecture, and the concepts behind it.
This document explains the architecture of gomcptest, the design decisions behind it, and how the various components interact to create a custom Model Context Protocol (MCP) host.
The gomcptest project implements a custom host that provides a Model Context Protocol (MCP) implementation. It’s designed to enable testing and experimentation with agentic systems without requiring direct integration with commercial LLM platforms.
The system is built with these key principles in mind:
The host is the central component, located in /host/openaiserver. It presents an OpenAI-compatible API interface and connects to Google’s Vertex AI for model inference. This compatibility layer makes it easy to integrate with existing tools and libraries designed for OpenAI.
The host has several key responsibilities:
Unlike commercial implementations, this host is designed for local development and testing, emphasizing flexibility and observability over production-ready features like authentication or rate limiting.
The tools are standalone executables that implement the Model Context Protocol. Each tool is designed to perform a specific function, such as executing shell commands or manipulating files.
Tools follow a consistent pattern:
This approach allows tools to be:
The CLI provides a user interface similar to tools like “Claude Code” or “OpenAI ChatGPT”. It connects to the OpenAI-compatible server and provides a way to interact with the LLM and tools through a conversational interface.
The OpenAI API has become a de facto standard in the LLM space. By implementing this interface, gomcptest can work with a wide variety of existing tools, libraries, and frontends with minimal adaptation.
Vertex AI provides access to Google’s Gemini models, which have strong function calling capabilities. The implementation could be extended to support other model providers as needed.
By implementing tools as standalone executables rather than library functions, we gain several advantages:
The Model Context Protocol provides a standardized way for LLMs to interact with external tools. By adopting this protocol, gomcptest ensures compatibility with tools developed for other MCP-compatible hosts.
The current implementation has several limitations:
Future enhancements could include:
The gomcptest architecture represents a flexible and extensible approach to building custom MCP hosts. It prioritizes simplicity, modularity, and developer experience, making it an excellent platform for experimentation with agentic systems.
By understanding this architecture, developers can effectively utilize the system, extend it with new tools, and potentially adapt it for their specific needs.
This document explores the Model Context Protocol (MCP), how it works, the design decisions behind it, and how it compares to alternative approaches for LLM tool integration.
The Model Context Protocol (MCP) is a standardized communication protocol that enables Large Language Models (LLMs) to interact with external tools and capabilities. It defines a structured way for models to request information or take actions in the real world, and for tools to provide responses back to the model.
MCP is designed to solve the problem of extending LLMs beyond their training data by giving them access to:
At its core, MCP is a protocol based on JSON-RPC that enables bidirectional communication between LLMs and tools. The basic workflow is:
The protocol specifies:
In gomcptest, MCP is implemented using a set of independent executables that communicate over standard I/O. This approach has several advantages:
Each tool in gomcptest follows a consistent pattern:
The core MCP protocol in gomcptest follows this format:
Tools register themselves with a schema that defines their capabilities:
{
"name": "ToolName",
"description": "Description of what the tool does",
"parameters": {
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "Description of parameter 1"
},
"param2": {
"type": "number",
"description": "Description of parameter 2"
}
},
"required": ["param1"]
}
}
When a model wants to use a tool, it generates a function call like:
{
"name": "ToolName",
"params": {
"param1": "value1",
"param2": 42
}
}
The tool executes the requested action and returns:
{
"result": "Output of the tool's execution"
}
Or, in case of an error:
{
"error": {
"message": "Error message",
"code": "ERROR_CODE"
}
}
Several key design decisions shape the MCP implementation in gomcptest:
By using stdin/stdout for communication, tools can be written in any language that can read from stdin and write to stdout. This makes it easy to integrate existing utilities and libraries.
Using JSON Schema for tool definitions provides a clear contract between the model and the tools. It enables:
Tools are designed to be stateless, with each invocation being independent. This simplifies the protocol and makes tools easier to reason about and test.
The protocol doesn’t handle authentication directly; instead, it relies on the host to manage permissions and authentication. This separation of concerns keeps the protocol simple.
MCP is similar to OpenAI’s function calling feature but with these key differences:
Compared to LangChain:
Other agent protocols often focus on higher-level concepts like goals and planning, while MCP focuses specifically on the mechanics of tool invocation.
The MCP protocol in gomcptest could evolve in several ways:
The Model Context Protocol as implemented in gomcptest represents a pragmatic approach to extending LLM capabilities through external tools. Its simplicity, extensibility, and focus on interoperability make it a solid foundation for building and experimenting with agentic systems.
By understanding the protocol, developers can create new tools that seamlessly integrate with the system, unlocking new capabilities for LLM applications.
This document explains the architecture and implementation of the MCP tools in gomcptest, how they work, and the design principles behind them.
MCP (Model Context Protocol) tools are standalone executables that provide specific functions that can be invoked by AI models. They allow the AI to interact with its environment - performing tasks like reading and writing files, executing commands, or searching for information.
In gomcptest, tools are implemented as independent Go executables that follow a standard protocol for receiving requests and returning results through standard input/output streams.
Each tool in gomcptest follows a consistent architecture:
Most tools share these common components:
The tools in gomcptest can be categorized into several functional groups:
The tools in gomcptest were designed with several key principles in mind:
Each tool is a standalone executable that can be developed, tested, and deployed independently. This modular approach allows for:
Security is a major consideration in the tool design:
The tools are designed to be simple to understand and use:
The system is designed to be easily extended:
The communication protocol for tools follows this pattern:
Tools receive JSON input on stdin in this format:
{
"param1": "value1",
"param2": "value2",
"param3": 123
}
Tools return JSON output on stdout in one of these formats:
{
"result": "text result"
}
or
{
"results": [
{"field1": "value1", "field2": "value2"},
{"field1": "value3", "field2": "value4"}
]
}
{
"error": "Error message",
"code": "ERROR_CODE"
}
Most tools follow this basic structure:
package main
import (
"encoding/json"
"fmt"
"os"
)
// Parameters defines the expected input structure
type Parameters struct {
Param1 string `json:"param1"`
Param2 int `json:"param2,omitempty"`
}
// Result defines the output structure
type Result struct {
Result string `json:"result,omitempty"`
Error string `json:"error,omitempty"`
Code string `json:"code,omitempty"`
}
func main() {
// Parse input
var params Parameters
decoder := json.NewDecoder(os.Stdin)
if err := decoder.Decode(¶ms); err != nil {
outputError("Failed to parse input", "INVALID_INPUT")
return
}
// Validate parameters
if params.Param1 == "" {
outputError("param1 is required", "MISSING_PARAMETER")
return
}
// Execute core functionality
result, err := executeTool(params)
if err != nil {
outputError(err.Error(), "EXECUTION_ERROR")
return
}
// Return result
output := Result{Result: result}
encoder := json.NewEncoder(os.Stdout)
encoder.Encode(output)
}
func executeTool(params Parameters) (string, error) {
// Tool-specific logic here
return "result", nil
}
func outputError(message, code string) {
result := Result{
Error: message,
Code: code,
}
encoder := json.NewEncoder(os.Stdout)
encoder.Encode(result)
}
The dispatch_agent tool demonstrates how tools can be composed to create more powerful capabilities. It:
The tool error mechanism is designed to provide useful information back to the model:
Tools are designed with performance in mind:
The tool architecture in gomcptest could evolve in several ways:
The MCP tools in gomcptest provide a flexible, secure, and extensible foundation for enabling AI agents to interact with their environment. By understanding the architecture and design principles of these tools, developers can effectively utilize the existing tools, extend them with new capabilities, or create entirely new tools that integrate seamlessly with the system.