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:

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

Quick Start

Create an MCP config file for the daemon:

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

Start the daemon with that config:

bash
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:

bash
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)

yaml
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)

yaml
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 with exponential backoff kicks in (up to 5 retries, max 60s backoff)
• On agent shutdown, all connections are gracefully closed

Idempotency

discover_mcp_tools() is idempotent -- calling it multiple times only connects to servers that aren't already connected. Failed servers are retried on subsequent calls.

Transport Types

Stdio Transport

The most common transport. Kheish launches the MCP server as a subprocess and communicates over stdin/stdout.

yaml
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

The subprocess inherits a filtered environment (see Security section below) plus any variables you specify in env.

HTTP / StreamableHTTP Transport

For remote or shared MCP servers. Requires the mcp package to include HTTP client support (mcp.client.streamable_http).

yaml
mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer <api_token>"

If HTTP support is not available in your installed mcp version, the server will fail with an ImportError and other servers will continue normally.

Security

Environment Variable Filtering

For stdio servers, Kheish does NOT pass your full shell environment to MCP subprocesses. Only safe baseline variables are inherited:

• PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR
• Any XDG_* variables

All other environment variables (API keys, tokens, secrets) are excluded unless you explicitly add them via the env config key. This prevents accidental credential leakage to untrusted MCP servers.

yaml
mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      # Only this token is passed to the subprocess
      GITHUB_PERSONAL_ACCESS_TOKEN: "<github_personal_access_token>"

Credential Stripping in Error Messages

If an MCP tool call fails, any credential-like patterns in the error message are automatically redacted before being shown to the LLM. This covers:

• GitHub PATs
• OpenAI-style keys (sk-...)
• Bearer tokens
• Generic token=, key=, API_KEY=, password=, secret= patterns

Troubleshooting

"MCP SDK not available -- skipping MCP tool discovery"

The mcp Python package is not installed. Install it:

bash
pip install mcp

"No MCP servers configured"

No mcp_servers key in ~/.kheish/config.yaml, or it's empty. Add at least one server.

"Failed to connect to MCP server 'X'"

Common causes:

• Command not found: The command binary isn't on PATH. Ensure npx, uvx, or the relevant command is installed.
• Package not found: For npx servers, the npm package may not exist or may need -y in args to auto-install.
• Timeout: The server took too long to start. Increase connect_timeout.
• Port conflict: For HTTP servers, the URL may be unreachable.

"MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available"

Your mcp package version doesn't include HTTP client support. Upgrade:

bash
pip install --upgrade mcp

Tools not appearing

• Check that the server is listed under mcp_servers (not mcp or servers)
• Ensure the YAML indentation is correct
• Look at Kheish startup logs for connection messages
• Tool names are prefixed with mcp_{server}_{tool} -- look for that pattern

Connection keeps dropping

The client retries up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s, capped at 60s). If the server is fundamentally unreachable, it gives up after 5 attempts. Check the server process and network connectivity.

Examples

Time Server (uvx)

yaml
mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

Registers tools like mcp_time_get_current_time.

Filesystem Server (npx)

yaml
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
    timeout: 30

Registers tools like mcp_filesystem_read_file, mcp_filesystem_write_file, mcp_filesystem_list_directory.

GitHub Server with Authentication

yaml
mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "<github_personal_access_token>"
    timeout: 60

Registers tools like mcp_github_list_issues, mcp_github_create_pull_request, etc.

Remote HTTP Server

yaml
mcp_servers:
  company_api:
    url: "https://mcp.mycompany.com/v1/mcp"
    headers:
      Authorization: "Bearer <api_token>"
      X-Team-Id: "engineering"
    timeout: 180
    connect_timeout: 30

Multiple Servers

yaml
mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "<github_personal_access_token>"

  company_api:
    url: "https://mcp.internal.company.com/mcp"
    headers:
      Authorization: "Bearer <api_token>"
    timeout: 300

All tools from all servers are registered and available simultaneously. Each server's tools are prefixed with its name to avoid collisions.

Sampling (Server-Initiated LLM Requests)

Kheish supports MCP's sampling/createMessage capability — MCP servers can request LLM completions through the agent during tool execution. This enables agent-in-the-loop workflows (data analysis, content generation, decision-making).

Sampling is enabled by default. Configure per server:

yaml
mcp_servers:
  my_server:
    command: "npx"
    args: ["-y", "my-mcp-server"]
    sampling:
      enabled: true           # default: true
      model: "gemini-3-flash" # model override (optional)
      max_tokens_cap: 4096    # max tokens per request
      timeout: 30             # LLM call timeout (seconds)
      max_rpm: 10             # max requests per minute
      allowed_models: []      # model whitelist (empty = all)
      max_tool_rounds: 5      # tool loop limit (0 = disable)
      log_level: "info"       # audit verbosity

Servers can also include tools in sampling requests for multi-turn tool-augmented workflows. The max_tool_rounds config prevents infinite tool loops. Per-server audit metrics (requests, errors, tokens, tool use count) are tracked via get_mcp_status().

Disable sampling for untrusted servers with sampling: { enabled: false }.

Notes

• MCP tools are called synchronously from the agent's perspective but run asynchronously on a dedicated background event loop
• Tool results are returned as JSON with either {"result": "..."} or {"error": "..."}
• The native MCP client is independent of mcporter -- you can use both simultaneously
• Server connections are persistent and shared across all conversations in the same agent process
• Adding or removing servers requires restarting the agent (no hot-reload currently)