MCP (Model Context Protocol) Support

May 30, 2026 · View on GitHub

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

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
Handshake: Sends initialize request (MCP 2025-11-25 protocol), receives capabilities
Discovery: Calls tools/list to discover what tools the server provides
Registration: Each MCP tool is registered as a CLIO tool with the mcp_ prefix
Execution: When the AI calls an MCP tool, CLIO sends tools/call via JSON-RPC
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: