GoSuda

Understanding the MCP Host

By snowmerak
views ...

What is MCP?

MCP is a protocol developed by Anthropic for Claude. MCP stands for Model Context Protocol, which enables an LLM to actively request external actions or resources. Since MCP is literally just a protocol that provides requests and responses, the process and execution must be handled by the developer.

Regarding Internal Operation

Before explaining the internal operation, we will briefly discuss Gemini Function Calling. Gemini Function Calling, like MCP, allows an LLM to proactively call external actions. One might wonder why Function Calling is brought up. The reason it is brought up is that Function Calling predates MCP, and they both utilize the OpenAPI schema, making them compatible and suggesting similar interactions. Consequently, Gemini Function Calling offers more detailed explanations, which are helpful, hence its inclusion.

FunctionCalling

The overall flow is as follows:

  1. Define a function.
  2. Send the function definition to Gemini along with the prompt.
    1. "Send user prompt along with the function declaration(s) to the model. It analyzes the request and determines if a function call would be helpful. If so, it responds with a structured JSON object."
  3. Gemini requests a function call if necessary.
    1. If Gemini requires it, the caller receives the name and parameters for the function call.
    2. The caller can decide whether to execute it or not.
      1. Whether to call it and return a legitimate value.
      2. Whether to return data as if it were called, without actually calling it.
      3. Whether to simply ignore it.
  4. In the process above, Gemini performs and requests actions such as calling multiple functions at once, or calling a function and then, based on the results, calling another.
  5. The process terminates when a refined answer is produced.

This flow generally aligns with MCP. This is similarly explained in the MCP tutorial. Ollama tools also exhibit similar behavior.

Fortunately, these three tools—Ollama tools, MCP, and Gemini Function Calling—share a nearly identical schema structure, meaning that implementing MCP alone allows for its use across all three.

Oh, and there's a common drawback they all share. Ultimately, the model executes these functions, so if the model you are using is in poor condition, it might fail to call functions, call them incorrectly, or even launch a DoS attack on the MCP server, leading to erroneous operations.

MCP Host in Go

mark3lab's mcphost

In Go, there is mcphost, which is under development by the mark3lab organization.

Its usage is very straightforward.

1go install github.com/mark3labs/mcphost@latest

After installation, create a $HOME/.mcp.json file and populate it as follows:

 1{
 2  "mcpServers": {
 3    "sqlite": {
 4      "command": "uvx",
 5      "args": [
 6        "mcp-server-sqlite",
 7        "--db-path",
 8        "/tmp/foo.db"
 9      ]
10    },
11    "filesystem": {
12      "command": "npx",
13      "args": [
14        "-y",
15        "@modelcontextprotocol/server-filesystem",
16        "/tmp"
17      ]
18    }
19  }
20}

Then, execute it with an Ollama model as follows. Of course, if necessary, first acquire the model with ollama pull mistral-small.

Although Claude or Qwen2.5 are generally recommended, I currently recommend mistral-small.

1mcphost -m ollama:mistral-small

However, executing it this way limits its use to a command-line interface for question-and-answer interactions. Therefore, we will modify the code of this mcphost to enable more programmatic behavior.

Forking mcphost

As already observed, mcphost includes functionality for extracting metadata and calling functions using MCP. Thus, components for calling the LLM, managing the MCP server, and handling message history are required.

The Runner in the following package represents the portion that incorporates these elements.

 1package runner
 2
 3import (
 4	"context"
 5	"encoding/json"
 6	"fmt"
 7	"log"
 8	"strings"
 9	"time"
10
11	mcpclient "github.com/mark3labs/mcp-go/client"
12	"github.com/mark3labs/mcp-go/mcp"
13
14	"github.com/mark3labs/mcphost/pkg/history"
15	"github.com/mark3labs/mcphost/pkg/llm"
16)
17
18type Runner struct {
19	provider   llm.Provider
20	mcpClients map[string]*mcpclient.StdioMCPClient
21	tools      []llm.Tool
22
23	messages []history.HistoryMessage
24}

We will not examine the internal declarations of this section separately. However, they are largely self-explanatory by their names.

 1func NewRunner(systemPrompt string, provider llm.Provider, mcpClients map[string]*mcpclient.StdioMCPClient, tools []llm.Tool) *Runner {
 2	return &Runner{
 3		provider:   provider,
 4		mcpClients: mcpClients,
 5		tools:      tools,
 6		messages: []history.HistoryMessage{
 7			{
 8				Role: "system",
 9				Content: []history.ContentBlock{{
10					Type: "text",
11					Text: systemPrompt,
12				}},
13			},
14		},
15	}
16}

For mcpClients and tools used here, please refer to this file. For provider, which will be Ollama's, please refer to this file.

The primary function is the Run method.

  1func (r *Runner) Run(ctx context.Context, prompt string) (string, error) {
  2	if len(prompt) != 0 {
  3		r.messages = append(r.messages, history.HistoryMessage{
  4			Role: "user",
  5			Content: []history.ContentBlock{{
  6				Type: "text",
  7				Text: prompt,
  8			}},
  9		})
 10	}
 11
 12	llmMessages := make([]llm.Message, len(r.messages))
 13	for i := range r.messages {
 14		llmMessages[i] = &r.messages[i]
 15	}
 16
 17	const initialBackoff = 1 * time.Second
 18	const maxRetries int = 5
 19	const maxBackoff = 30 * time.Second
 20
 21	var message llm.Message
 22	var err error
 23	backoff := initialBackoff
 24	retries := 0
 25	for {
 26		message, err = r.provider.CreateMessage(
 27			context.Background(),
 28			prompt,
 29			llmMessages,
 30			r.tools,
 31		)
 32		if err != nil {
 33			if strings.Contains(err.Error(), "overloaded_error") {
 34				if retries >= maxRetries {
 35					return "", fmt.Errorf(
 36						"claude is currently overloaded. please wait a few minutes and try again",
 37					)
 38				}
 39
 40				time.Sleep(backoff)
 41				backoff *= 2
 42				if backoff > maxBackoff {
 43					backoff = maxBackoff
 44				}
 45				retries++
 46				continue
 47			}
 48
 49			return "", err
 50		}
 51
 52		break
 53	}
 54
 55	var messageContent []history.ContentBlock
 56
 57	var toolResults []history.ContentBlock
 58	messageContent = []history.ContentBlock{}
 59
 60	if message.GetContent() != "" {
 61		messageContent = append(messageContent, history.ContentBlock{
 62			Type: "text",
 63			Text: message.GetContent(),
 64		})
 65	}
 66
 67	for _, toolCall := range message.GetToolCalls() {
 68		input, _ := json.Marshal(toolCall.GetArguments())
 69		messageContent = append(messageContent, history.ContentBlock{
 70			Type:  "tool_use",
 71			ID:    toolCall.GetID(),
 72			Name:  toolCall.GetName(),
 73			Input: input,
 74		})
 75
 76		parts := strings.Split(toolCall.GetName(), "__")
 77
 78		serverName, toolName := parts[0], parts[1]
 79		mcpClient, ok := r.mcpClients[serverName]
 80		if !ok {
 81			continue
 82		}
 83
 84		var toolArgs map[string]interface{}
 85		if err := json.Unmarshal(input, &toolArgs); err != nil {
 86			continue
 87		}
 88
 89		var toolResultPtr *mcp.CallToolResult
 90		req := mcp.CallToolRequest{}
 91		req.Params.Name = toolName
 92		req.Params.Arguments = toolArgs
 93		toolResultPtr, err = mcpClient.CallTool(
 94			context.Background(),
 95			req,
 96		)
 97
 98		if err != nil {
 99			errMsg := fmt.Sprintf(
100				"Error calling tool %s: %v",
101				toolName,
102				err,
103			)
104			log.Printf("Error calling tool %s: %v", toolName, err)
105
106			toolResults = append(toolResults, history.ContentBlock{
107				Type:      "tool_result",
108				ToolUseID: toolCall.GetID(),
109				Content: []history.ContentBlock{{
110					Type: "text",
111					Text: errMsg,
112				}},
113			})
114
115			continue
116		}
117
118		toolResult := *toolResultPtr
119
120		if toolResult.Content != nil {
121			resultBlock := history.ContentBlock{
122				Type:      "tool_result",
123				ToolUseID: toolCall.GetID(),
124				Content:   toolResult.Content,
125			}
126
127			var resultText string
128			for _, item := range toolResult.Content {
129				if contentMap, ok := item.(map[string]interface{}); ok {
130					if text, ok := contentMap["text"]; ok {
131						resultText += fmt.Sprintf("%v ", text)
132					}
133				}
134			}
135
136			resultBlock.Text = strings.TrimSpace(resultText)
137
138			toolResults = append(toolResults, resultBlock)
139		}
140	}
141
142	r.messages = append(r.messages, history.HistoryMessage{
143		Role:    message.GetRole(),
144		Content: messageContent,
145	})
146
147	if len(toolResults) > 0 {
148		r.messages = append(r.messages, history.HistoryMessage{
149			Role:    "user",
150			Content: toolResults,
151		})
152
153		return r.Run(ctx, "")
154	}
155
156	return message.GetContent(), nil
157}

The code itself is a compilation of parts from this file.

The content is generally as follows:

  1. The prompt and the list of tools are sent to request execution or response generation.
  2. If a response is generated, the recursion stops, and the response is returned.
  3. If the LLM requests tool execution, the host calls the MCP Server.
  4. The response is added to the history, and the process returns to step 1.

Conclusion

Already finished?

Indeed, there is not much more to elaborate on. This article was written to provide an understanding of how the MCP Server generally operates. I hope this article has offered a small degree of assistance in comprehending the operation of an MCP host.