MCP

Introduction

Overview

The Model Context Protocol (MCP) connects agents to external tools and data sources through a standardized interface. Instead of wiring each service directly into your agent, you run an MCP server that exposes its capabilities. The runtime translates the server’s tool list into LLM::Tool subclasses the model can call.

How it works

The stdio transport runs the server as a child process and communicates over stdin/stdout. Use LLM::MCP#session to avoid launching the same process multiple times.

require "llm"

llm   = LLM.deepseek(key: ENV["KEY"])
mcp   = LLM::MCP.stdio(argv: ["npx", "-y", "@forgejo/mcp-server"])
agent = LLM::Agent.new(llm)

mcp.session do
  agent.talk "What's happening on forgejo?", tools: mcp.tools
end

Why would I use it?

MCP decouples tool implementation from the agent. Add tools by launching a new MCP server. Update them by restarting an existing one. Remove them without touching the agent’s code.

Notes

For stdio, use LLM::MCP#session to avoid launching the same process multiple times. For HTTP, LLM::MCP#session carries little benefit.

HTTP

Overview

The HTTP transport connects to a remote MCP server over HTTP. It is the right choice for cloud-hosted servers like GitHub’s MCP endpoint. Tools exposed by the server become LLM::Tool subclasses the model can call. The server does not need to run locally or even on the same machine. Configure headers for authentication and pick a transport backend for connection management.

How it works

When you want to connect to a remote MCP server, provide a URL and optional headers. The server’s tool list is fetched and translated into LLM::Tool subclasses the model can call.

require "llm"

llm   = LLM.deepseek(key: ENV["KEY"])
mcp   = LLM::MCP.http(
  url: "https://api.githubcopilot.com/mcp/",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch('GITHUB_PAT')}"
  },
  transport: :net_http_persistent
)
agent = LLM::Agent.new(llm)
agent.talk "What's happening on GitHub?", tools: mcp.tools

Why would I use it?

The HTTP transport connects to remote MCP servers. This matters when the server is not running locally or when tools are maintained by a different team and exposed as a service.

Notes

For HTTP, LLM::MCP#session carries little benefit. Use the net_http_persistent transport to avoid tearing down connections repeatedly.