MCPHost

⚠️ MCPHost is No Longer Actively Maintained

Active development on MCPHost has been stopped.This project has been succeeded byKit, which builds on the foundations of MCPHost with a more powerful and extensible architecture.

👉We recommend all users migrate toKit.

- Overview
- Features
- Requirements
- Environment Setup
- Installation
- SDK Usage
- Configuration

- MCP Servers
- Environment Variable Substitution
- Simplified Configuration Schema
- Tool Filtering
- Legacy Configuration Support
- Transport Types
- System Prompt

- Interactive Mode
- Script Mode
- Hooks System
- Non-Interactive Mode
- Model Generation Parameters
- Available Models
- Examples
- Flags
- Authentication Subcommands
- Configuration File Support
- Interactive Commands

- Go 1.23 or later
- For OpenAI/Anthropic: API key for the respective provider
- For Ollama: Local Ollama installation with desired models
- For Google/Gemini: Google API key (seehttps://aistudio.google.com/app/apikey)
- One or more MCP-compatible tool servers

# For all providers (use --provider-api-key flag or these environment variables) export OPENAI_API_KEY='your-openai-key' # For OpenAI export ANTHROPIC_API_KEY='your-anthropic-key' # For Anthropic export GOOGLE_API_KEY='your-google-key' # For Google/Gemini

- Install Ollama fromhttps://ollama.ai
- Pull your desired model:

export GOOGLE_API_KEY='your-api-key'

mcphost --provider-url https://192.168.1.100:443 --tls-skip-verify

go install github.com/mark3labs/mcphost@latest

package main import ( "context" "fmt" "github.com/mark3labs/mcphost/sdk" ) func main() { ctx := context.Background() // Create MCPHost instance with default configuration host, err := sdk.New(ctx, nil) if err != nil { panic(err) } defer host.Close() // Send a prompt and get response response, err := host.Prompt(ctx, "What is 2+2?") if err != nil { panic(err) } fmt.Println(response) }

For detailed SDK documentation, examples, and API reference, see theSDK README.

mcpServers: github: type: local command: ["docker", "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN=${env://GITHUB_TOKEN}", "ghcr.io/github/github-mcp-server"] environment: DEBUG: "${env://DEBUG:-false}" LOG_LEVEL: "${env://LOG_LEVEL:-info}" model: "${env://MODEL:-anthropic/claude-sonnet-4-5-20250929}" provider-api-key: "${env://OPENAI_API_KEY}" # Required - will fail if not set

# Set required environment variables export GITHUB_TOKEN="ghp_your_token_here" export OPENAI_API_KEY="your_openai_key" # Optionally override defaults export DEBUG="true" export MODEL="openai/gpt-4" # Run mcphost mcphost

MCPHost now supports a simplified configuration schema with three server types:

For local MCP servers that run commands on your machine:

{ "mcpServers": { "filesystem": { "type": "local", "command": ["npx", "@modelcontextprotocol/server-filesystem", "${env://WORK_DIR:-/tmp}"], "environment": { "DEBUG": "${env://DEBUG:-false}", "LOG_LEVEL": "${env://LOG_LEVEL:-info}", "API_TOKEN": "${env://FS_API_TOKEN}" }, "allowedTools": ["read_file", "write_file"], "excludedTools": ["delete_file"] }, "github": { "type": "local", "command": ["docker", "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN=${env://GITHUB_TOKEN}", "ghcr.io/github/github-mcp-server"], "environment": { "DEBUG": "${env://DEBUG:-false}" } }, "sqlite": { "type": "local", "command": ["uvx", "mcp-server-sqlite", "--db-path", "${env://DB_PATH:-/tmp/foo.db}"], "environment": { "SQLITE_DEBUG": "${env://DEBUG:-0}", "DATABASE_URL": "${env://DATABASE_URL:-sqlite:///tmp/foo.db}" } } } }

- type: Must be set to"local"
- command: Array containing the command and all its arguments
- environment: (Optional) Object with environment variables as key-value pairs
- allowedTools: (Optional) Array of tool names to include (whitelist)
- excludedTools: (Optional) Array of tool names to exclude (blacklist)

For remote MCP servers accessible via HTTP:

{ "mcpServers": { "websearch": { "type": "remote", "url": "${env://WEBSEARCH_URL:-https://api.example.com/mcp}", "headers": ["Authorization: Bearer ${env://WEBSEARCH_TOKEN}"] }, "weather": { "type": "remote", "url": "${env://WEATHER_URL:-https://weather-mcp.example.com}" } } }

- type: Must be set to"remote"
- url: The URL where the MCP server is accessible
- headers: (Optional) Array of HTTP headers for authentication and custom headers

Remote servers automatically use the StreamableHTTP transport for optimal performance.

For builtin MCP servers that run in-process for optimal performance:

{ "mcpServers": { "filesystem": { "type": "builtin", "name": "fs", "options": { "allowed_directories": ["${env://WORK_DIR:-/tmp}", "${env://HOME}/documents"] }, "allowedTools": ["read_file", "write_file", "list_directory"] }, "filesystem-cwd": { "type": "builtin", "name": "fs" } } }

- type: Must be set to"builtin"
- name: Internal name of the builtin server (e.g.,"fs"for filesystem)
- options: Configuration options specific to the builtin server

- fs(filesystem): Secure filesystem access with configurable allowed directories

- allowed_directories: Array of directory paths that the server can access (defaults to current working directory if not specified)

- No configuration options required (todos are stored in memory and reset on restart)

- Tools:fetch(fetch and convert web content),fetch_summarize(fetch and summarize web content using AI),fetch_extract(fetch and extract specific data using AI),fetch_filtered_json(fetch JSON and filter using gjson path syntax)
- No configuration options required

{ "mcpServers": { "filesystem": { "type": "builtin", "name": "fs", "options": { "allowed_directories": ["/tmp", "/home/user/documents"] } }, "bash-commands": { "type": "builtin", "name": "bash" }, "task-manager": { "type": "builtin", "name": "todo" }, "web-fetcher": { "type": "builtin", "name": "http" } } }

All MCP server types support tool filtering to restrict which tools are available:

- allowedTools: Whitelist - only specified tools are available from the server
- excludedTools: Blacklist - all tools except specified ones are available

{ "mcpServers": { "filesystem-readonly": { "type": "builtin", "name": "fs", "allowedTools": ["read_file", "list_directory"] }, "filesystem-safe": { "type": "local", "command": ["npx", "@modelcontextprotocol/server-filesystem", "/tmp"], "excludedTools": ["delete_file"] } } }

Note:allowedToolsandexcludedToolsare mutually exclusive - you can only use one per server.

MCPHost maintains full backward compatibility with the previous configuration format.Note: A recent bug fix improved legacy stdio transport reliability for external MCP servers (Docker, NPX, etc.).

{ "mcpServers": { "sqlite": { "command": "uvx", "args": ["mcp-server-sqlite", "--db-path", "/tmp/foo.db"], "env": { "DEBUG": "true" } } } }

{ "mcpServers": { "server_name": { "url": "http://some_host:8000/sse", "headers": ["Authorization: Bearer my-token"] } } }

{ "mcpServers": { "phalcon": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/mark3labs/phalcon-mcp:latest", "serve" ] } } }

{ "mcpServers": { "websearch": { "transport": "streamable", "url": "https://api.example.com/mcp", "headers": ["Authorization: Bearer your-api-token"] } } }

- stdio: Launches a local process and communicates via stdin/stdout (used by"local"servers)
- sse: Connects to a server using Server-Sent Events (legacy format)
- streamable: Connects to a server using Streamable HTTP protocol (used by"remote"servers)
- inprocess: Runs builtin servers in-process for optimal performance (used by"builtin"servers)

The simplified schema automatically maps:

- "local"type →stdiotransport
- "remote"type →streamabletransport
- "builtin"type →inprocesstransport

You can specify a custom system prompt using the--system-promptflag. You can either:

mcphost --system-prompt "You are a helpful assistant that responds in a friendly tone."

Pass a path to a text file containing the prompt:

mcphost --system-prompt ./prompts/assistant.md

You are a helpful coding assistant. Please: - Write clean, readable code - Include helpful comments - Follow best practices - Explain your reasoning

MCPHost is a CLI tool that allows you to interact with various AI models through a unified interface. It supports various tools through MCP servers and can run in both interactive and non-interactive modes.

Start an interactive conversation session:

Run executable YAML-based automation scripts with variable substitution support:

# Using the script subcommand mcphost script myscript.sh # With variables mcphost script myscript.sh --args:directory /tmp --args:name "John" # Direct execution (if executable and has shebang) ./myscript.sh

Scripts combine YAML configuration with prompts in a single executable file. The configuration must be wrapped in frontmatter delimiters (---). You can either include the prompt in the YAML configuration or place it after the closing frontmatter delimiter:

#!/usr/bin/env -S mcphost script --- # This script uses the container-use MCP server from https://github.com/dagger/container-use mcpServers: container-use: type: "local" command: ["cu", "stdio"] prompt: | Create 2 variations of a simple hello world app using Flask and FastAPI. Each in their own environment. Give me the URL of each app ---

Or alternatively, omit theprompt:field and place the prompt after the frontmatter:

#!/usr/bin/env -S mcphost script --- # This script uses the container-use MCP server from https://github.com/dagger/container-use mcpServers: container-use: type: "local" command: ["cu", "stdio"] --- Create 2 variations of a simple hello world app using Flask and FastAPI. Each in their own environment. Give me the URL of each app

Scripts support both environment variable substitution and script argument substitution:
- Environment Variables:${env://VAR}and${env://VAR:-default}- Processed first
- Script Arguments:${variable}and${variable:-default}- Processed after environment variables

Variables can be provided via command line arguments: