/native-mcp

description: Built-in MCP (Model Context Protocol) client that connects to external
  MCP servers, discovers their tools, and registers them as native Kheish tools.
  Supports stdio and HTTP transports with automatic reconnection, security filtering,
  and zero-config tool injection.
version: 1.0.0
license: MIT
metadata:
  catalog:
    tags:
    - MCP
    - Tools
    - Integrations
    related_skills:
    - mcporter

Kheish Compatibility

This skill is repo-local and stays inactive until explicitly activated.

When the original instructions refer to legacy tool names, use these Kheish mappings:

• `terminal` => `bash`
• `web_extract` => `web_fetch`, plus `web_search` when discovery is needed
• `search_files` => `grep_search` and `glob_search`
• `browser_*` tools require a browser-capable surfaced tool or MCP; if none is available, use the closest available surface and say so explicitly

When the instructions mention local helper files, resolve them from `${KHEISH_SKILL_DIR}`.

Native MCP Client

Kheish has a built-in MCP client in the daemon. It connects to MCP servers at daemon startup, discovers their tools, and surfaces them as first-class runtime tools when the current session is allowed to see them.

When to Use

Use this whenever you want to:

• Connect to MCP servers and use their tools from within Kheish
• Add external capabilities (filesystem access, GitHub, databases, APIs) via MCP
• Run local stdio-based MCP servers (npx, uvx, or any command)
• Connect to remote HTTP/StreamableHTTP MCP servers
• Have MCP tools discovered by the daemon and exposed to sessions that are allowed to use them

For ad-hoc, one-off MCP tool calls from the terminal without configuring anything, see the `mcporter` skill instead.

Prerequisites

• **mcp Python package** -- optional dependency; install with `pip install mcp`. If not installed, MCP support is silently disabled.
• **Node.js** -- required for `npx`-based MCP servers (most community servers)
• **uv** -- required for `uvx`-based MCP servers (Python-based servers)

Install the MCP SDK:

pip install mcp
# or, if using uv:
uv pip install mcp

Quick Start

Create an MCP config file for the daemon:

[mcp_servers.time]
command = "uvx"
args = ["mcp-server-time"]

Start the daemon with that config:

kheish-daemon serve --mcp-config ./mcp-config.toml

On startup the daemon will: 1. Connect to the server 2. Discover available tools 3. Register them with the prefix `mcp__time__*` 4. Expose them to sessions whose effective capability scope allows them

Verify the result with:

kheish-daemon runtime get

Configuration Reference

Each entry under `mcp_servers` is a server name mapped to its config. There are two transport types: **stdio** (command-based) and **HTTP** (url-based).

Stdio Transport (command + args)

mcp_servers:
  server_name:
    command: "npx"             # (required) executable to run
    args: ["-y", "pkg-name"]   # (optional) command arguments, default: []
    env:                       # (optional) environment variables for the subprocess
      SOME_API_KEY: "value"
    timeout: 120               # (optional) per-tool-call timeout in seconds, default: 120
    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60

HTTP Transport (url)

mcp_servers:
  server_name:
    url: "https://my-server.example.com/mcp"   # (required) server URL
    headers:                                     # (optional) HTTP headers
      Authorization: "Bearer <api_token>"
    timeout: 180               # (optional) per-tool-call timeout in seconds, default: 120
    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60

All Config Options

| Option | Type | Default | Description | |-------------------|--------|---------|---------------------------------------------------| | `command` | string | -- | Executable to run (stdio transport, required) | | `args` | list | `[]` | Arguments passed to the command | | `env` | dict | `{}` | Extra environment variables for the subprocess | | `url` | string | -- | Server URL (HTTP transport, required) | | `headers` | dict | `{}` | HTTP headers sent with every request | | `timeout` | int | `120` | Per-tool-call timeout in seconds | | `connect_timeout` | int | `60` | Timeout for initial connection and discovery |

Note: A server config must have either `command` (stdio) or `url` (HTTP), not both.

How It Works

Startup Discovery

When Kheish starts, `discover_mcp_tools()` is called during tool initialization:

1. Reads `mcp_servers` from `~/.kheish/config.yaml` 2. For each server, spawns a connection in a dedicated background event loop 3. Initializes the MCP session and calls `list_tools()` to discover available tools 4. Registers each tool in the Kheish tool registry

Tool Naming Convention

MCP tools are registered with the naming pattern:

mcp_{server_name}_{tool_name}

Hyphens and dots in names are replaced with underscores for LLM API compatibility.

Examples:

• Server `filesystem`, tool `read_file` → `mcp_filesystem_read_file`
• Server `github`, tool `list-issues` → `mcp_github_list_issues`
• Server `my-api`, tool `fetch.data` → `mcp_my_api_fetch_data`

Auto-Injection

After discovery, MCP tools are made available to Kheish runtime profiles, but the effective session/persona capability scope can still filter individual servers or tools. Do not assume every conversation sees the full MCP surface.

Connection Lifecycle

• Each server runs as a long-lived asyncio Task in a background daemon thread
• Connections persist for the lifetime of the agent process
• If a connection drops, automatic reconnection wit