Skip to content

MCP.md

Latest commit

 

History

History
309 lines (230 loc) · 8.47 KB

MCP.md

File metadata and controls

309 lines (230 loc) · 8.47 KB

MCP (Model Context Protocol) Support

Overview

CLIO supports the Model Context Protocol (MCP), an open standard that lets AI applications connect to external tool servers. With MCP, you can extend CLIO's capabilities by connecting to third-party tools - databases, APIs, file systems, and more - without modifying CLIO itself.

MCP servers provide tools that the AI can discover and call just like CLIO's built-in tools. The protocol uses JSON-RPC 2.0 over stdio for communication.

Requirements

MCP servers are typically distributed as npm packages or Python packages. You need at least one of the following runtimes installed:

Runtime Used For Install
npx (Node.js) npm-based MCP servers brew install node / apt install nodejs npm
node Local JS MCP servers Comes with Node.js
uvx Python MCP servers (uv) pip install uv
python3 Python MCP servers Usually pre-installed

If no compatible runtime is found, MCP is silently disabled and CLIO works normally without it.

Configuration

MCP servers are configured in ~/.clio/config.json under the mcp key:

{
  "mcp": {
    "filesystem": {
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
      "enabled": true
    },
    "sqlite": {
      "command": ["npx", "-y", "@modelcontextprotocol/server-sqlite", "path/to/database.db"],
      "enabled": true
    },
    "memory": {
      "command": ["npx", "-y", "@modelcontextprotocol/server-memory"],
      "enabled": true
    }
  }
}

Server Config Options

Key Type Description
type String local (default, stdio) or remote (HTTP/SSE)
command Array Command and arguments for local servers
url String URL endpoint for remote servers
headers Object Custom HTTP headers for remote servers
enabled Boolean Set to false to disable without removing config
environment Object Extra environment variables (local servers only)
timeout Number Connection/request timeout in seconds (default: 30)

Example: Local Server

{
  "mcp": {
    "filesystem": {
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
      "enabled": true
    }
  }
}

Example: Remote Server

{
  "mcp": {
    "remote-tools": {
      "type": "remote",
      "url": "https://mcp.example.com/api",
      "headers": {
        "Authorization": "Bearer your-api-key"
      },
      "timeout": 60
    }
  }
}

Example: Custom Environment

{
  "mcp": {
    "github": {
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxx"
      }
    }
  }
}

Commands

/mcp or /mcp status

Show connection status of all configured MCP servers:

✓ filesystem (MCP Filesystem Server) - 11 tool(s)
✗ broken-server (failed: Connection refused)
− disabled-server (disabled)

/mcp list

List all tools from all connected MCP servers:

MCP Tools (14 total):

  [filesystem]
    mcp_filesystem_read_file: Read the complete contents of a file...
    mcp_filesystem_write_file: Create a new file or overwrite...
    mcp_filesystem_list_directory: Get a detailed listing...
    ...

  [sqlite]
    mcp_sqlite_read_query: Execute a SELECT query...
    mcp_sqlite_write_query: Execute an INSERT, UPDATE, or DELETE...
    mcp_sqlite_list_tables: List all tables in the database

/mcp add <name> <command...> or /mcp add <name> <url>

Add and connect to a new MCP server:

# Local server (stdio)
/mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /tmp

# Remote server (HTTP/SSE)
/mcp add remote-tools https://mcp.example.com/api

This also saves the server to your config for persistence across sessions.

/mcp remove <name>

Disconnect and remove an MCP server:

/mcp remove filesystem

How It Works

  1. Startup: CLIO reads MCP config and creates a transport for each enabled server
    • Local servers (type: local or default): Spawned as subprocesses, communicate via stdio
    • Remote servers (type: remote): Connected via HTTP POST with SSE streaming support
  2. Handshake: Sends initialize request (MCP 2025-11-25 protocol), receives capabilities
  3. Discovery: Calls tools/list to discover what tools the server provides
  4. Registration: Each MCP tool is registered as a CLIO tool with the mcp_ prefix
  5. Execution: When the AI calls an MCP tool, CLIO sends tools/call via JSON-RPC
  6. Shutdown: On exit, CLIO closes stdin to each server and waits for clean exit

Tool Naming

MCP tools are namespaced to prevent collisions:

mcp_<servername>_<toolname>

For example, a read_file tool from the filesystem server becomes: mcp_filesystem_read_file

The AI sees these as regular tools and can call them alongside built-in tools.

Popular MCP Servers

Server Package Description
Filesystem @modelcontextprotocol/server-filesystem Read/write files in specified directories
SQLite @modelcontextprotocol/server-sqlite Query SQLite databases
PostgreSQL @modelcontextprotocol/server-postgres Query PostgreSQL databases
Memory @modelcontextprotocol/server-memory Knowledge graph memory
GitHub @modelcontextprotocol/server-github GitHub API operations
Git @modelcontextprotocol/server-git Git repository operations
Fetch @modelcontextprotocol/server-fetch HTTP fetch with readability
Puppeteer @modelcontextprotocol/server-puppeteer Browser automation
Brave Search @modelcontextprotocol/server-brave-search Web search via Brave

Browse more at: github.com/modelcontextprotocol/servers

Troubleshooting

"MCP not initialized"

MCP couldn't find any compatible runtime (npx, node, uvx, python). Install Node.js:

brew install node          # macOS
sudo apt install nodejs npm  # Debian/Ubuntu

Server shows "failed" status

Run the server command manually to check for errors:

npx -y @modelcontextprotocol/server-filesystem /tmp

Common issues:

  • Package not found (check spelling)
  • Missing API keys (check environment config)
  • Permission denied (check file/directory permissions)

Server connects but tools don't work

Enable debug mode to see MCP JSON-RPC traffic:

./clio --debug --new
/mcp status

Debug output shows all JSON-RPC messages between CLIO and the MCP server.

OAuth 2.0 Authentication

CLIO supports OAuth 2.0 with PKCE for MCP servers that require authentication:

{
  "mcp": {
    "protected-server": {
      "type": "remote",
      "url": "https://mcp.example.com/api",
      "oauth": {
        "authorization_url": "https://auth.example.com/authorize",
        "token_url": "https://auth.example.com/token",
        "client_id": "your-client-id",
        "scopes": ["tools:read", "tools:execute"]
      }
    }
  }
}

On first connection, CLIO opens a browser for authorization. Tokens are cached at ~/.clio/mcp-tokens/<servername>.json (permissions 0600) and refreshed automatically.

To re-authenticate manually:

/mcp auth <servername>

Architecture

Module Structure

Module Purpose
CLIO::MCP::Manager Server lifecycle, tool discovery, routing
CLIO::MCP::Client JSON-RPC 2.0 client implementation
CLIO::MCP::Transport::Stdio Local server communication (stdin/stdout)
CLIO::MCP::Transport::HTTP Remote server communication (HTTP POST + SSE)
CLIO::MCP::Auth::OAuth OAuth 2.0 + PKCE flow
CLIO::Tools::MCPBridge Tool registration bridge (MCP tools -> CLIO tools)

Limitations

  • No MCP resources - Only tools are bridged (resources and prompts planned)
  • No sampling - Server-initiated LLM requests not supported
  • No progress notifications - Long-running tools show no progress

Protocol Reference

CLIO implements the MCP 2025-11-25 specification: