7.6 KiB

Raw Blame History

MCP (Model Context Protocol) Integration

This document describes the MCP integration for Ollama agents, enabling agents to use external tools via the Model Context Protocol.

Overview

MCP allows Ollama agents to communicate with external tool servers over JSON-RPC 2.0 via stdio. This enables agents to access capabilities like web search, file operations, databases, and more through standardized tool interfaces.

Status

Phase	Description	Status
Phase 1	Types & Parser	✅ Complete
Phase 2	Layer Handling	✅ Complete
Phase 3	Runtime Manager	✅ Complete
Phase 4	CLI Commands	✅ Complete

Agentfile Syntax

Simple Command Format

MCP <name> <command> [args...]

Example:

FROM llama3.2
AGENT TYPE conversational
SYSTEM You are a helpful assistant with MCP tools.
MCP calculator python3 ./mcp-server.py
MCP websearch node ./search-server.js

JSON Format

MCP {"name": "custom", "command": "uv", "args": ["run", "server.py"], "env": {"API_KEY": "xxx"}}

Architecture

Type Definitions

MCPRef (types/model/config.go):

type MCPRef struct {
    Name    string            `json:"name,omitempty"`
    Digest  string            `json:"digest,omitempty"`
    Command string            `json:"command,omitempty"`
    Args    []string          `json:"args,omitempty"`
    Env     map[string]string `json:"env,omitempty"`
    Type    string            `json:"type,omitempty"`  // "stdio"
}

Tool Namespacing

MCP tools are namespaced to avoid conflicts:

Format: mcp_{serverName}_{toolName}
Example: Server "calculator" with tool "add" → mcp_calculator_add

Runtime Flow

Agent starts → MCP servers spawn as subprocesses
Initialize via JSON-RPC: initialize → notifications/initialized
Discover tools: tools/list
During chat, model calls tools → routed via tools/call
On shutdown, MCP servers are gracefully terminated

Files

Created

File	Purpose
`cmd/mcp.go`	Runtime MCP manager with JSON-RPC protocol
`cmd/mcp_cmd.go`	CLI commands for managing MCPs (push, pull, list, etc.)
`server/mcp.go`	MCP layer utilities (extraction, creation)

Modified

File	Changes
`types/model/config.go`	Added `MCPRef` type, `MCPs` field to `ConfigV2`
`types/model/name.go`	Added `"mcp"` to `ValidKinds` for 5-part name parsing
`api/types.go`	Added `MCPRef` alias, `MCPs` to `CreateRequest`/`ShowResponse`
`parser/parser.go`	Added `MCP` command parsing with JSON and simple formats
`server/create.go`	Added `setMCPLayers()` for MCP config handling
`server/routes.go`	Added `MCPs` to show response
`cmd/cmd.go`	MCP integration in `chat()` function
`cmd/interactive.go`	Added `/mcp` and `/mcps` REPL commands

Usage Example

1. Create an MCP Server

#!/usr/bin/env python3
# mcp-server.py
import json
import sys

def handle_request(req):
    method = req.get("method", "")
    
    if method == "initialize":
        return {
            "protocolVersion": "2024-11-05",
            "capabilities": {"tools": {}},
            "serverInfo": {"name": "example", "version": "1.0"}
        }
    elif method == "tools/list":
        return {
            "tools": [{
                "name": "add",
                "description": "Adds two numbers",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "a": {"type": "number"},
                        "b": {"type": "number"}
                    },
                    "required": ["a", "b"]
                }
            }]
        }
    elif method == "tools/call":
        args = req["params"]["arguments"]
        return {"content": [{"type": "text", "text": f"{args['a'] + args['b']}"}]}
    return {}

for line in sys.stdin:
    req = json.loads(line)
    if "id" in req:
        result = handle_request(req)
        print(json.dumps({"jsonrpc": "2.0", "id": req["id"], "result": result}), flush=True)

2. Create an Agent

# my-agent.Agentfile
FROM gpt-oss:20b
AGENT TYPE conversational
SYSTEM You have access to a calculator. Use the add tool when asked to add numbers.
MCP calculator python3 ./mcp-server.py

3. Build and Run

ollama create my-agent -f my-agent.Agentfile
ollama run my-agent "What is 15 + 27?"

Output:

Loaded MCP servers: calculator (1 tools)
Executing: mcp_calculator_add
Output: 42
The result is 42.

CLI Commands

The ollama mcp command provides utilities for managing MCP servers:

Global Config Commands

Add an MCP server to the global config (~/.ollama/mcp.json):

# Add MCP to global config (available to all agents)
ollama mcp add web-search uv run ./mcp-server.py
ollama mcp add calculator python3 /path/to/calc.py

# List global MCP servers (shows enabled/disabled status)
ollama mcp list-global

# Disable an MCP server (keeps in config but won't be loaded)
ollama mcp disable web-search

# Re-enable a disabled MCP server
ollama mcp enable web-search

# Remove from global config
ollama mcp remove-global web-search

Registry Commands

Package and push MCPs to a registry:

# Push MCP to registry (creates locally first)
ollama mcp push mcp/websearch:1.0 ./my-mcp-server/

# Pull MCP from registry
ollama mcp pull mcp/websearch:1.0

# List installed MCPs (from registry)
ollama mcp list

# Show MCP details
ollama mcp show mcp/websearch:1.0

# Remove MCP
ollama mcp rm mcp/websearch:1.0

REPL Commands

Inside ollama run, you can manage MCP servers dynamically:

>>> /mcp                                     # Show all MCP servers (model + global)
>>> /mcp add calc python3 ./calc-server.py   # Add MCP server to global config
>>> /mcp remove calc                         # Remove MCP server from global config
>>> /mcp disable calc                        # Disable an MCP server (keep in config)
>>> /mcp enable calc                         # Re-enable a disabled MCP server
>>> /? mcp                                   # Get help for MCP commands

The /mcp command shows all available MCP servers (both bundled with the model and from global config). Disabled servers are shown with a [disabled] marker. Use /mcp add and /mcp remove to manage MCPs in ~/.ollama/mcp.json. Changes take effect on the next message.

Global Config

MCPs can be configured globally in ~/.ollama/mcp.json:

{
  "mcpServers": {
    "web-search": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "./mcp-server.py"]
    },
    "calculator": {
      "type": "stdio",
      "command": "python3",
      "args": ["/path/to/calc.py"],
      "disabled": true
    }
  }
}

The disabled field is optional. When set to true, the MCP server will not be loaded when running agents.

Future Enhancements

Remote Registry Push/Pull: Full support for pushing/pulling MCPs to/from remote registries
Use go-sdk: Consider using github.com/modelcontextprotocol/go-sdk for protocol handling
Resource Support: Add MCP resources (not just tools)
Prompt Support: Add MCP prompts

Protocol Reference

MCP uses JSON-RPC 2.0 over stdio with these key methods:

Method	Direction	Purpose
`initialize`	Client→Server	Handshake with capabilities
`notifications/initialized`	Client→Server	Confirm initialization
`tools/list`	Client→Server	Discover available tools
`tools/call`	Client→Server	Execute a tool

See MCP Specification for full details.

7.6 KiB Raw Blame History