MCP (Model Context Protocol)

MCP (Model Context Protocol) is an open protocol for tool interoperability with AI models. ChatCLI integrates with MCP servers, allowing the AI to access external tools such as file systems, web searches, databases, and any compatible service.

Overview

ChatCLI <-> MCP Manager <-> MCP Server (stdio | sse | http)
                              |
                         External tools
                         (filesystem, search, DB, ...)

Load configuration

The MCP Manager loads the MCP server configuration.

Start servers

Starts the configured servers (stdio, SSE or Streamable HTTP).

Discover tools

Discovers the available tools on each server.

Expose to the model

Exposes the tools to the AI model as ToolDefinition.

Route calls

Routes tool calls to the correct server.

Configuration

The `chatcli mcp` subcommand (recommended)

Manage servers from the shell — same developer experience as claude mcp add, writing to ~/.chatcli/mcp_servers.json atomically (hand-maintained extension keys survive rewrites; re-adding a name replaces it):

# stdio server (everything after -- is the server's command line)
chatcli mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
chatcli mcp add github --env GITHUB_TOKEN=ghp_xxx -- npx -y @modelcontextprotocol/server-github

# remote servers (SSE / streamable HTTP)
chatcli mcp add --transport http notion https://mcp.notion.com/mcp
chatcli mcp add --transport sse asana https://mcp.asana.com/sse

# authenticated remote servers — raw header (Claude Code compatible)…
chatcli mcp add --transport sse private https://api.company.com/sse --header "X-API-Key: your-key"

# …or typed auth with the secret kept in the environment (expanded per request)
chatcli mcp add --transport http secure https://api.example.com/mcp --bearer '${MCP_TOKEN}'
chatcli mcp add --transport sse corp https://mcp.corp.com/sse --basic 'user:${LDAP_PASS}'
chatcli mcp add --transport sse api https://mcp.x.com/sse --auth-header 'X-API-Key: ${KEY}'

chatcli mcp list            # table of configured servers
chatcli mcp get <name>      # full JSON of one server
chatcli mcp remove <name>   # delete

Other flags for add: --cwd DIR (stdio working directory), --description TEXT, --disabled (add without enabling).

Configuration File

Create ~/.chatcli/mcp_servers.json:

{
  "mcpServers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/workspace"],
      "enabled": true
    },
    {
      "name": "web-search",
      "transport": "sse",
      "url": "http://localhost:8080/sse",
      "enabled": true,
      "overrides": ["@webfetch", "@websearch"]
    },
    {
      "name": "database",
      "transport": "stdio",
      "command": "/usr/local/bin/mcp-postgres",
      "args": ["--connection-string", "postgresql://localhost/mydb"],
      "env": {
        "PGPASSWORD": "secret"
      },
      "enabled": true
    }
  ]
}

Extended server capabilities

Beyond the minimum (name, command, args, env, transport, enabled, overrides), each server entry accepts an opt-in set of fields covering the same cases Claude Code, Cline, Cursor, and the AWS EKS MCP server support — tool auto-approval, enabledTools/disabledTools filtering, per-server timeouts, working directory, custom HTTP headers, and HTTP authentication (bearer/basic/header, shared by sse and http), plus metadata (description, tags, category) shown in /mcp status. Any key outside the typed schema is preserved verbatim across save/load (the Extensions catch-all), so a config copied from another client works without losing vendor-specific annotations. Full reference with semantics, examples and troubleshooting: MCP Servers Configuration.

Environment Variables

CHATCLI_MCP_ENABLED=true
CHATCLI_MCP_CONFIG=~/.chatcli/mcp_servers.json

Via Server Flag

chatcli server --mcp-config ~/.chatcli/mcp_servers.json

Transports

stdio
SSE (HTTP+SSE)
http (Streamable HTTP)

The stdio transport starts a local process and communicates via stdin/stdout using JSON-RPC 2.0:

{
  "name": "filesystem",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@anthropic/mcp-server-filesystem", "/workspace"]
}

Use case: Local servers distributed as npm packages, standalone binaries, or scripts.

The sse transport connects to a remote HTTP server that exposes two endpoints — /sse for the stream and /messages for the JSON-RPC POSTs, per the original MCP spec model:

{
  "name": "remote-tools",
  "transport": "sse",
  "url": "http://mcp-server:8080/sse"
}

The GET /sse listener is supervised: connection drops (proxy idle timeout, server restart) trigger reconnect with full-jitter exponential backoff (500 ms → 30 s cap), pending RPCs survive the reconnect, and push notifications on the same stream feed MCP Channels.Use case: remote servers built against the HTTP+SSE model (anything predating the 2025-03-26 spec or keeping that shape for compatibility).

The http transport connects to a remote server that exposes a single endpoint per the MCP 2025-03-26 spec revision (Streamable HTTP). Adopted by the official SDK and by hosts like Cloudflare Workers MCP, FastMCP, mcp.deepwiki.com, and managed MCP gateways:

{
  "name": "remote-tools",
  "transport": "http",
  "url": "https://mcp-server.example.com/mcp/",
  "auth": {
    "type": "bearer",
    "token": "${MCP_TOKEN}"
  }
}

Each call is a single POST; the response can arrive as a one-shot JSON, as an SSE upgrade on the same response (carrying the result plus any interleaved notifications/*), or as 202 Accepted for client→server notifications. If the server emits an Mcp-Session-Id on initialize, the transport captures it and echoes it on every subsequent call.Server-initiated push notifications are read by a separate GET listener (opt-in per spec). ChatCLI starts the listener right after initialize; servers that don’t implement push respond 405/404/501 on the GET and the listener stops cleanly, no retries. When the listener is active, push messages land in /channel list and can fire trigger rules — see MCP Channels.Use case: servers built against the current MCP spec. When in doubt between sse and http, hit the endpoint with curl — whatever answers a GET with event: endpoint is sse; whatever answers a POST directly with JSON or an SSE upgrade is http.

The trailing slash in url is significant. Several Streamable HTTP servers only answer on /mcp/ and 307-redirect /mcp. Full details and troubleshooting: MCP Servers Configuration — http (Streamable HTTP).

OAuth 2.1 authorization (remote servers)

Remote (http/sse) MCP servers increasingly gate access behind OAuth 2.1 rather than a static token — the AWS MCP server is the motivating case. ChatCLI supports this end-to-end, and it needs no client ID, secret, or endpoints in your config: everything is discovered at runtime. When a server answers a request with 401 and an OAuth challenge, ChatCLI:

Discovers the authorization server

Reads the WWW-Authenticate header, fetches the Protected Resource Metadata (RFC 9728), then the Authorization Server Metadata (RFC 8414) to learn the authorization, token, and registration endpoints.

Registers a client dynamically

Registers a public PKCE client via Dynamic Client Registration (RFC 7591) — so you never paste a client_id.

Runs the browser flow

Opens your browser for the authorization-code + PKCE flow through a localhost callback, binding the token to the server via the resource indicator (RFC 8707).

Stores and refreshes the token

Persists the access/refresh tokens in the encrypted auth store (AES-256-GCM, the same vault as /auth login) and refreshes them transparently thereafter.

Authorizing a server

Once a remote server is configured, authorize it in either of two ways:

# opens a browser, stores the token, reconnects the server
/mcp login aws-mcp

# forget the stored credential (and stop the server)
/mcp logout aws-mcp

# When a tool call needs authorization, the error tells the model to
# authorize, and it invokes the built-in @mcp-login tool itself:
MCP tool error: MCP server "aws-mcp" requires OAuth authorization.
Call @mcp-login with {"server":"aws-mcp"} to authorize, then retry.

/mcp status shows a server waiting on authorization with a 🔒 authorization required state and a login hint. After a successful login the server reconnects and its mcp_* tools become available.

No config changes are required for an OAuth server — just add it as a normal http/sse server (chatcli mcp add --transport http aws-mcp https://…/mcp). The first tool call surfaces the authorization prompt. To pin the loopback callback port (for strict redirect-URI allowlists), set CHATCLI_MCP_OAUTH_PORT (default 8765; falls back to an ephemeral port if busy).

The static bearer/basic/header auth documented above still applies for servers that accept a pre-minted token; OAuth is used only when a server actively challenges for it.

Tool Naming

MCP tools are automatically prefixed with mcp_ and receive a description from the source server:

Original name: read_file
Name in ChatCLI: mcp_read_file
Description: [MCP:filesystem] Reads a file from the filesystem

The mcp_ prefix prevents collisions with ChatCLI’s native tools.

Built-in Overrides (Shadow + Fallback)

When an MCP server provides a tool that replaces a native plugin (e.g., @webfetch, @websearch), use the overrides field to declare which built-ins it replaces. ChatCLI automatically hides the listed built-ins while the MCP server is connected. If the server disconnects, the built-ins are immediately restored — the user never loses the capability.

Why use overrides?

Without overrides, the LLM sees two tools that do the same thing (e.g., @webfetch and mcp_web_fetch) and picks randomly. With overrides, the behavior is deterministic: the LLM only sees the MCP tool, with no ambiguity.

Configuration

Add overrides to the MCP server configuration:

CLI (mcp_servers.json)
Helm (values.yaml)
Operator (Instance CRD)

{
  "mcpServers": [
    {
      "name": "web-tools",
      "transport": "sse",
      "url": "http://mcp-web:8080/sse",
      "enabled": true,
      "overrides": ["@webfetch", "@websearch"]
    }
  ]
}

mcp:
  enabled: true
  servers:
    - name: web-tools
      transport: sse
      url: "http://mcp-web:8080/sse"
      enabled: true
      overrides: ["@webfetch", "@websearch"]

apiVersion: platform.chatcli.dev/v1alpha1
kind: Instance
metadata:
  name: my-chatcli
spec:
  mcp:
    enabled: true
    servers:
      - name: web-tools
        transport: sse
        url: "http://mcp-web:8080/sse"
        enabled: true
        overrides: ["@webfetch", "@websearch"]

How it works

MCP server "web-tools" CONNECTED + overrides: ["@webfetch", "@websearch"]
  LLM sees:       mcp_web_fetch, mcp_web_search, @coder, ...
  LLM does NOT see: @webfetch, @websearch  (hidden)

MCP server "web-tools" DISCONNECTED (crash, network, etc.)
  LLM sees:       @webfetch, @websearch, @coder, ...  (automatically restored)
  Log:            "MCP server 'web-tools' disconnected, restoring built-in overrides"

Shadow sync happens on every conversation turn, not just at startup. This means if the MCP server crashes mid-conversation, the built-ins return on the very next message — no restart needed.

Important rules

Rule	Detail
Exact names	Use the full built-in name including `@` (e.g., `"@webfetch"`, not `"webfetch"`)
Multiple servers	Different servers can declare different overrides. If two servers override the same built-in, only one needs to be connected to maintain the shadow
Disabled server	`"enabled": false` on the server = overrides do not apply (server never connects)
Partial override	You can override just one built-in (e.g., only `@websearch`) and keep the others visible
No effect on @coder	`@coder` cannot be overridden via MCP — its subcommands are native tools of /coder mode

The overrides field does not uninstall or modify the built-in plugin. It only hides it from the LLM prompt. The plugin remains available internally and returns automatically when needed. This is shadow, not delete.

Deploy via Helm

Inline MCP Servers
Existing ConfigMap

# values.yaml
mcp:
  enabled: true
  servers:
    - name: filesystem
      transport: stdio
      command: npx
      args: ["-y", "@anthropic/mcp-server-filesystem", "/workspace"]
      enabled: true
    - name: web-tools
      transport: sse
      url: "http://mcp-web:8080/sse"
      enabled: true
      overrides: ["@webfetch", "@websearch"]  # hides built-ins when connected

mcp:
  enabled: true
  existingConfigMap: "my-mcp-config"

The Helm chart automatically creates a ConfigMap with the mcp_servers.json and mounts it at /etc/chatcli/mcp/.

Deploy via Operator (Instance CRD)

When using the ChatCLI Operator, configure MCP directly in the Instance resource:

apiVersion: platform.chatcli.dev/v1alpha1
kind: Instance
metadata:
  name: my-chatcli
spec:
  provider: CLAUDEAI
  model: claude-sonnet-4-20250514
  mcp:
    enabled: true
    servers:
      - name: filesystem
        transport: stdio
        command: npx
        args: ["-y", "@anthropic/mcp-server-filesystem", "/workspace"]
        enabled: true
      - name: github
        transport: stdio
        command: npx
        args: ["-y", "@anthropic/mcp-server-github"]
        env:
          GITHUB_TOKEN: "ghp_xxxxx"
        enabled: true
      - name: remote-search
        transport: sse
        url: "http://mcp-search:8080/sse"
        enabled: true
        overrides: ["@webfetch", "@websearch"]  # hides built-ins when connected

Or reference an existing ConfigMap:

spec:
  mcp:
    enabled: true
    existingConfigMap: "my-mcp-servers"

The controller automatically:

Generates a ConfigMap <instance>-mcp with mcp_servers.json
Mounts at /etc/chatcli/mcp/ (read-only)
Passes --mcp-config /etc/chatcli/mcp/mcp_servers.json to the container

The MCPSpec CRD mirrors the mcp_servers.json format exactly. Each MCPServerSpec field maps to a JSON field — including overrides for built-in shadowing.

Checking Status

The MCP Manager exposes the status of each server:

statuses := mcpMgr.GetServerStatus()
for _, s := range statuses {
    fmt.Printf("Server: %s, Connected: %v, Tools: %d\n",
        s.Name, s.Connected, s.ToolCount)
}

To check if a tool is MCP:

if mcpMgr.IsMCPTool("mcp_read_file") {
    result, err := mcpMgr.ExecuteTool(ctx, "read_file", args)
}

Popular MCP Servers

Server	Description	Installation
`@anthropic/mcp-server-filesystem`	File system access	`npx -y @anthropic/mcp-server-filesystem /path`
`@anthropic/mcp-server-github`	GitHub integration	`npx -y @anthropic/mcp-server-github`
`@anthropic/mcp-server-postgres`	PostgreSQL queries	`npx -y @anthropic/mcp-server-postgres`
`@anthropic/mcp-server-slack`	Slack integration	`npx -y @anthropic/mcp-server-slack`

Check modelcontextprotocol.io for the complete list of available MCP servers.

MCP in Client Mode (TTY)

MCP now works directly in interactive mode (TTY), not just server mode. ChatCLI auto-detects ~/.chatcli/mcp_servers.json and initializes servers automatically on startup.

MCP tools are exposed across all 3 modes:

Mode	How it works
Chat	Tools listed in system prompt as informational context
Agent	Tools invocable via `<tool_call name="mcp_<tool>" args='...' />`
Coder	Same mechanism as Agent mode

Deferred Schemas (Token Savings)

To save tokens in the system prompt, ChatCLI uses deferred schemas:

Only name + description are sent in the prompt (lightweight)
Before first use, the model queries the catalog with @tools describe and gets the full block: owning server, description, parameter JSON Schema and invocation form
The model invokes with the correct arguments

Prompt: "mcp_read_file: [MCP:filesystem] Reads a file from the filesystem"

Model: <tool_call name="@tools" args='{"cmd":"describe","args":{"name":"mcp_read_file"}}' />
→ returns server, description and full JSON Schema

Model invokes with args → real execution

@tools list also indexes MCP tools alongside the builtins, grouped by owning server — every entry carries the [MCP:server] tag, so the model always knows which server a tool comes from. As a fallback, if the model invokes an MCP tool without its required parameters, the full schema is returned as feedback for correction. Index descriptions are clamped: each tool’s description in the system-prompt index is reduced to its first line, capped at 160 characters. Enterprise MCP servers ship multi-paragraph descriptions — with 100+ tools connected, unclamped descriptions alone add tens of KB to every request, which is exactly the payload floor that trips corporate proxy/WAF body caps (see Context Recovery). The full description and schema remain one @tools describe away.

This can save hundreds of tokens per turn when many MCP tools are connected — and with verbose enterprise servers, tens of KB per request.

Dynamic tool discovery

Some MCP servers have a dynamic tool list (the tools.listChanged capability): they connect exposing a minimal catalog and grow it at runtime. HTTP Toolkit is the canonical case — it exposes only start on connect, and after start runs it registers the real tools and emits a notifications/tools/list_changed notification. ChatCLI handles this end-to-end:

The notification fires a debounced, per-server refresh (bursts coalesce into a single tools/list call). The refresh runs asynchronously — a synchronous round-trip from the transport’s reader would deadlock the response pump.
The registry is reconciled: new tools added, changed schemas replaced, vanished tools dropped — touching only tools owned by that server.
At the next turn boundary the agent is told what changed, so it can use the new tools immediately:

🔌 MCP tool catalog updated (http-toolkit: +12/-0) — new tools are available to the agent

The model receives the added/removed tool names and the reminder to @tools describe before first use. Tool dispatch, @tools list/describe and the completer all read the live registry, so the change is visible everywhere at once. The tools/list_changed event is also recorded in the channel inbox for auditability — but as a handled protocol event it does not inflate the unread counter. Controlled by CHATCLI_MCP_DYNAMIC_TOOLS (default on); surfaced under /config integrations.

`/mcp` Command

Manage MCP servers directly from the interactive terminal. Every subcommand that takes a server name has autocomplete — press Tab after /mcp <subcommand> to list the configured servers.

Subcommand	Argument	Description
`/mcp` or `/mcp status [name]`	Optional	Status of all servers (no name) or a specific one
`/mcp tools [name]`	Optional	All tools (no name) or only those of `<name>`
`/mcp start <name>`	Required	Start a stopped server (or one that failed to start)
`/mcp stop <name>`	Required	Stop a server without removing it from config — `start` revives it later
`/mcp restart [name]`	Optional	Restart one server (with name) or all (no name)
`/mcp reload`	—	Re-read `mcp_servers.json` and reconcile (same logic as hot-reload, on demand)
`/mcp logs <name>`	Required	Last 200 stderr lines from the server (in-memory ring buffer)
`/mcp login <name>`	Required	Run the OAuth authorization flow for a remote server and reconnect it (opens a browser)
`/mcp logout <name>`	Required	Forget a server’s stored OAuth credential and stop it

Example: status and logs

> /mcp status

╭── 🔌 MCP SERVERS
│  ● filesystem    connected     3 tools  (2m 15s)
│  ● web-search    connected     2 tools  (2m 15s)
│  ○ database      disconnected
│    ↳ start MCP server "mcp-postgres": exec: not found
│
│  Total: 3 servers, 5 tools available
╰──────────────────────────────────────────────────────

> /mcp logs filesystem

╭── 📜 MCP LOGS — filesystem
│  Server starting on /workspace
│  Loaded 12 file watchers
│  Tool list: read_file, write_file, list_dir
╰──────────────────────────────────────────────────────

Start/stop semantics

Scenario	Behavior
`/mcp stop foo` on a running server	Kills the process, drops its tools; keeps the entry in the manager
`/mcp start foo` after `stop`	Revives using the in-memory config; tools come back
Hot-reload (JSON edit) while `foo` is user-stopped	`Reload` respects the manual stop; restarts only if `foo`’s config changed
`/mcp restart` (no name)	Stop all + start all with a new `mcpCtx` — equivalent to a full reset
`/mcp restart foo`	Stop + start of `foo` only, preserving the global ctx and the other servers
Server that failed at startup (LastError set)	`/mcp start foo` clears `LastError` and retries — useful after fixing command/env

Difference between /mcp restart and /mcp reload:

/mcp restart forces a restart even if the config didn’t change (useful for “reload credentials” after editing shell env).
/mcp reload is a diff-and-apply against mcp_servers.json — nothing that hasn’t changed gets restarted.

Per-server log buffer

Each stdio server keeps a 200-line ring buffer fed from the child process’s stderr. That means:

/mcp logs <name> shows the last 200 lines without enabling --debug;
Chatty servers don’t grow memory unboundedly — old lines drop off the front;
Captures like npm 404, panic stacks and startup messages stay available even after startup ends.

Useful combo for diagnosing connection issues: /mcp status (state), then /mcp logs <name> (the why). No need to restart with CHATCLI_LOG_LEVEL=debug.

Push notifications — MCP Channels

Beyond tools (request/response), ChatCLI accepts push notifications from any MCP server across all three transports. Notifications are JSON-RPC messages without id (the spec form for “the server wants to tell me something, it isn’t asking for anything back”). ChatCLI captures, persists, and automatically injects them into the next conversations, and — optionally — fires the agent via trigger rules.

The essentials

Works on stdio, sse, and http — each transport has its own listener:
- sse: the GET /sse that already carries tool responses receives notifications on the same stream.
- http: a separate GET on the endpoint (opt-in by the client, optional by the spec) pulls notifications. Servers that don’t support it respond with 405/404/501 and the listener stops cleanly, no retries.
- stdio: JSON-RPC lines on stdout without id are treated as notifications.
Durable persistence at ~/.chatcli/mcp/channels.jsonl (up to 10 MiB, rotates, replays on boot).
Auto-injection of the 5 most recent in the system prompt of chat/agent/coder (uncached so cache isn’t trashed).
Per-server filter: channels field in mcp_servers.json accepts a literal allow-list.
Optional rules engine in ~/.chatcli/mcp/triggers.json with 3 modes: notify (discreet banner, default), confirm (manual yes/no), auto (runs the agent — requires tool whitelist).
Slash commands: /channel list, /channel ack, /channel pause, /channel rules, /channel confirm <id>, /channel run <seq>, /channel inject.

Minimal example — server with channels

{
  "name": "prom-alerts",
  "transport": "sse",
  "url": "https://prom-alerts.internal/sse",
  "enabled": true,
  "channels": ["alerts/critical", "alerts/error"]
}

With that, alerts land in /channel list, show up in the next prompt banner, and are auto-injected into the agent context.

Example — trigger that investigates CI failures

~/.chatcli/mcp/triggers.json:

{
  "rules": [
    {
      "name": "ci-investigator",
      "server": "ci-monitor",
      "channel": "ci-pipeline",
      "contentRegex": "(?i)fail|broken",
      "mode": "confirm",
      "prompt": "Investigate this CI failure: {{content}}",
      "rateLimit": "5m"
    }
  ]
}

Every CI failure asks the user with a prompt in the banner; /channel confirm <id> accepts and the agent starts investigating.

Full channels, rules, and troubleshooting docs: MCP Channels. Complete channels schema and triggers.json reference: MCP Config.

Next steps

MCP Channels

Push messages across all three transports (stdio, sse, http) with durable persistence, per-server filter, and a rules engine (notify/confirm/auto).

Agentic plugins

ChatCLI’s plugin system — compared with MCP.

Native Tool Use

Native Anthropic/OpenAI APIs that power MCP under the hood.

MCP Config

Full mcp_servers.json format and examples.

​Overview

​Configuration

​The chatcli mcp subcommand (recommended)

​Configuration File

​Extended server capabilities

​Environment Variables

​Via Server Flag

​Transports

​OAuth 2.1 authorization (remote servers)

​Authorizing a server

​Tool Naming

​Built-in Overrides (Shadow + Fallback)

​Why use overrides?

​Configuration

​How it works

​Important rules

​Deploy via Helm

​Deploy via Operator (Instance CRD)

​Checking Status

​Popular MCP Servers

​MCP in Client Mode (TTY)

​Deferred Schemas (Token Savings)

​Dynamic tool discovery

​/mcp Command

​Example: status and logs

​Start/stop semantics

​Per-server log buffer

​Push notifications — MCP Channels

​The essentials

​Minimal example — server with channels

​Example — trigger that investigates CI failures

​Next steps

MCP Channels

Agentic plugins

Native Tool Use

MCP Config

Overview

Configuration

The `chatcli mcp` subcommand (recommended)

Configuration File

Extended server capabilities

Environment Variables

Via Server Flag

Transports

OAuth 2.1 authorization (remote servers)

Authorizing a server

Tool Naming

Built-in Overrides (Shadow + Fallback)

Why use overrides?

Configuration

How it works

Important rules

Deploy via Helm

Deploy via Operator (Instance CRD)

Checking Status

Popular MCP Servers

MCP in Client Mode (TTY)

Deferred Schemas (Token Savings)

Dynamic tool discovery

`/mcp` Command

Example: status and logs

Start/stop semantics

Per-server log buffer

Push notifications — MCP Channels

The essentials

Minimal example — server with channels

Example — trigger that investigates CI failures

Next steps