Model Context Protocol

Model Context Protocol (MCP) is an open protocol that lets models safely call tools exposed by external processes or services — for example, reading GitHub issues, querying databases, or operating the local file system. Kiki acts as an MCP client to connect these external tools and exposes them to the Agent alongside built-in tools (Read, Bash, Grep, etc.) with no behavioral difference.

MCP tool results can carry embedded media. When the current model cannot take an embedded image — because of its format or because the part is over the per-part size cap — Kiki keeps a text notice and saves the original into the session's media storage, so nothing is lost. The notice carries the saved file's absolute path and a kimi-file:// reference; pass the path to Read or ReadMediaFile to inspect the original. A resource blob in a format Kiki does not deliver is preserved the same way. When the list of saved attachments would crowd the tool output, it is written to a text file and the output keeps a short pointer to it.

Share Kiki tools with another client

Kiki can also serve its native tools to an explicitly authorized MCP client. The feature is available by default; it does not start a listener or authorize a client until you configure access.

1. In Settings → Connection & remote → Access from elsewhere → Agents & clients, add an external client and choose its shared tools and permission ceiling. These are access settings, not a workspace or conversation.
2. Create a conversation in Kiki, choose that external client, and select the workspace, worktree, Profile, and permission mode there. Kiki binds the resolved workspace to the conversation; the client cannot supply an arbitrary working directory.
3. Configure the other application's MCP entry with the local command below, replacing CONNECTION_ID with the connection's ID. For remote access, enable the MCP listener on the same tab and use its displayed HTTPS URL; approve the client's authorization request in Kiki.

kiki mcp --client CONNECTION_ID --tools

Connecting alone does not create a conversation. Before a conversation is attached, the tool catalog contains only kiki_session, kiki_operation, and kiki_save_text. Call kiki_session with {"action":"list"}, then explicitly resume a shared conversation with {"action":"resume","session_ref":"SESSION_REF"}. Keep the returned reference in _kiki.session_ref on native tool calls. After attachment, the catalog exposes the selected conversation's shared native tools and sends a tool-list change notification. To start another conversation with the same workspace and settings, call kiki_session with action: "new", that session_ref, and a stable _kiki.idempotency_key.

For side-effecting calls, keep the same _kiki.idempotency_key when retrying. Use kiki_operation to query or cancel an accepted operation instead of resubmitting it; its read action pages the saved original result. kiki_save_text saves only text the external client explicitly supplies—it does not synchronize the client's private chat automatically. Pause or revoke the connection in Settings to stop its access.

Connection Methods

Kiki supports three MCP server connection methods:

• stdio: The CLI starts the local MCP server as a child process and communicates via standard input/output. Suitable for local command-line tools.
• HTTP: The CLI connects to an already-running HTTP endpoint. Suitable for remote services or processes that need to run persistently.
• SSE: The CLI connects to a legacy HTTP+SSE endpoint (Server-Sent Events, a streaming HTTP mechanism). Prefer HTTP for new MCP servers, but use transport: "sse" when a service still exposes only the older SSE transport.

Configuration

MCP server configuration is written in mcp.json, at two levels:

• User level: ~/.kiki/mcp.json (or $KIKI_HOME/mcp.json), shared across projects
• Project level: .kiki/mcp.json in the working directory, effective only for the current repository

The legacy .kimi-code/mcp.json path is not read.

Entries with the same name: the project-level entry takes precedence and overrides the user-level entry.

Run /kiki-ops help me configure MCP in the TUI to interactively add, edit, or delete servers without manually editing the JSON file. Run /mcp to view the connection status of all current servers.

Deleting a server from the configuration does not interrupt open sessions: the server stays listed in /mcp as removed, its tools remain visible there, and calls to them fail with a removal notice, while new sessions do not register the tools at all. Conversely, a server added mid-session — by editing mcp.json or installing a plugin — is not registered in already-open sessions; it only joins sessions created later.

Before trusting a folder, the TUI shows project MCP launch targets and their defining configuration files, configured additional directories and their source, and available AGENTS.md, skill and agent-profile sources. It inspects these sources without connecting MCP servers. If inspection fails, the prompt shows a warning rather than implying that no configuration exists. The prompt defaults to Trust this folder; review the commands, arguments, remote URLs and paths before confirming. Trusting the folder enables its project-level MCP servers and configured additional directories.

Structure of mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "linear": {
      "url": "https://mcp.linear.app/mcp"
    },
    "legacy-events": {
      "transport": "sse",
      "url": "https://mcp.example.com/sse"
    }
  }
}

Entries with a command field are stdio servers; entries with a url field and no transport are HTTP servers. For legacy SSE servers, set transport to "sse" explicitly.

Optional fields:

Field	Type	Applies to	Description
env	Record<string, string>	stdio	Environment variables injected into the child process
cwd	string	stdio	Working directory for the child process
headers	Record<string, string>	HTTP, SSE	Static request headers appended to every request
bearerTokenEnvVar	string	HTTP, SSE	Name of an environment variable that contains a bearer token
enabled	boolean	All	Set to false to disable this server
startupTimeoutMs	number	All	Connection timeout from 1 to 2147483647 milliseconds; default 30000
toolTimeoutMs	number	All	Timeout from 1 to 2147483647 milliseconds for a single tool call
enabledTools	string[]	All	Tool allowlist
disabledTools	string[]	All	Tool blocklist

On Windows, command can be an executable path or a name such as node or npx. Names are resolved through the child's effective PATH/PATHEXT, not by searching its working directory; env overrides such as Path replace inherited values without case sensitivity. To run a file in the child working directory, give command an explicit relative path such as .\server.cmd. Keep paths unquoted in command and put each argument in its own args entry, including arguments containing spaces, quotes or &.

Kiki launches Windows .cmd/.bat wrappers automatically; do not add cmd /c for them. Batch-wrapper arguments cannot contain NUL or line breaks; for multiline arguments, launch the underlying executable directly, such as node with the script path as its first argument. A missing command reports ENOENT; install it or provide its absolute path.

You do not have to set the connection timeout or the single tool-call timeout per server: [mcp] startup_timeout_ms / [mcp] tool_timeout_ms in config.toml or the KIKI_MCP_STARTUP_TIMEOUT_MS / KIKI_MCP_TOOL_TIMEOUT_MS environment variables change the global defaults. Precedence is: per-server field > environment variable > config.toml > built-in default. See Configuration files.

HTTP and SSE servers support providing static credentials via headers or bearerTokenEnvVar. When OAuth is needed, run /kiki-ops help me log in to MCP <server-name> to complete browser-based authorization. If the server's authorization metadata says it supports offline_access, Kiki asks for that scope during login so the authorization can be refreshed later without a new sign-in; otherwise your original scopes are used as they are. A server that advertises the scope may still show an extra consent page, and does not guarantee it issues a refresh token. An already-signed-in server keeps its existing grant and goes on refreshing it — a new scope does not sign you out.

Plugins can also declare MCP servers in their manifest. Servers declared by a plugin are enabled by default and can be disabled or re-enabled in /plugins: disabling or removing stops the tools in open sessions — calls fail with a removal notice — while re-enabling reconnects the server in open sessions immediately and restores its tools, as long as the server already existed when the session was created (this includes re-enabling an enabled: false entry in mcp.json). A brand-new server still follows the rule above: it only joins sessions created later. See Plugins for details.

Note

stdio entries in a project-level .kiki/mcp.json execute local commands when a session starts. Only enable these in repositories you trust.

Tool Naming and Permissions

MCP tools are named in the format mcp__<server>__<tool>, for example mcp__github__create_issue. Permission rules support * and ** wildcards, for example mcp__github__* matches all tools under that server. MCP tool parameters are not included in permission matching.

Calls that do not match any permission rule trigger an approval request. Selecting "Approve for this session" in the approval dialog automatically allows subsequent calls of the same kind within the current session.

You can also pre-configure permanent rules in [[permission.rules]] in config.toml:

[[permission.rules]]
decision = "allow"
pattern = "mcp__github__*"

[[permission.rules]]
decision = "deny"
pattern = "mcp__filesystem__write_file"

For the full permission rule syntax, see Configuration files.

Security

When connecting to external MCP servers, be aware of:

• Only connect to servers from trusted sources
• Verify that tool names and parameters look reasonable in approval requests
• Keep manual approval for high-risk tools (file writes, command execution, etc.); avoid using mcp__* wildcards to allow all tools at once

Note

In YOLO mode, MCP tool calls are automatically approved. Only use this mode when you fully trust the MCP servers you have connected.

Let an external client use Kiki tools

External clients reverse the direction described above: an MCP-capable model calls Kiki's native file, media, agent, task, History and authorized Memory tools. Kiki keeps the tool activity in a normal session without binding a local model to its main agent. This does not automatically import the external chat, its thinking, or its usage.

Open Settings → Connection & remote → Access from elsewhere → Agents & clients to create a named connection and choose its shared tools and permission ceiling. The workspace is chosen when you create a conversation for that client. The capability is available by default; setting external_clients = false under [experimental], or KIKI_EXPERIMENTAL_EXTERNAL_CLIENTS=0, keeps it off, and changing that override requires a host restart. Leave local commands off unless the client needs them. A connection is a permission grant, not a chat: initialization and tool discovery do not create business sessions.

Connect a local client

Copy the connection's stdio configuration into your MCP client, keeping its generated --home path so it reaches the same Kiki instance. A command written by hand must include that same --home. Leaving it out, or pointing it at another directory, reaches a different Kiki home, not this connection. Its shape is:

{
  "command": "kiki",
  "args": ["mcp", "--client", "client_YOUR_CONNECTION_ID", "--tools", "--home", "C:/Users/Example/.kiki"]
}

The bridge obtains a separate short-lived credential through the local owner channel. It renews an expired local credential without resubmitting a business error. If the MCP address changes or the host restarts on another port, restart the client's MCP connection; then resume the saved business session instead of recreating its work. Do not place your Kiki owner token in this configuration. The older kiki mcp --workspace <dir> delegation mode remains separate.

Connect over HTTPS

Enable the external MCP listener and configure a stable public HTTPS origin in the same settings page. Add its displayed /mcp URL to a client that supports Streamable HTTP and OAuth authorization-code flow with PKCE. Confirm the client's pending authorization in Kiki and select the connection it may use; the external model cannot approve itself. Public HTTPS hosting or a tunnel is a separate service, and a listening port does not prove that discovery is reachable from the client.

This listener serves only MCP, OAuth and health routes, not the GUI, owner API or debug API. Client support and account eligibility depend on the external product; do not assume that every ChatGPT account accepts custom connectors. Kiki uses the installed MCP SDK's protocol negotiation rather than requiring an unpublished protocol version.

Sessions, retries and recovery

ChatGPT conversation metadata, when supplied by the client as _meta["openai/session"], maps each conversation to its own session under the connection. Other clients call kiki_session with action: "new" once, retain the returned session_ref, and put it in _kiki.session_ref on subsequent calls. resume is explicit; a copied reference cannot silently attach a new conversation to an old one.

Side effects require a stable _kiki.idempotency_key. Retry the same call with the same key; different arguments under that key are rejected. Long operations and approvals return an operation_id: query kiki_operation instead of resubmitting. If the host stopped before committing an outcome, outcome_unknown means inspect the target before an explicit recovery, not that the operation is safe to repeat.

Manual approval requires a real local approval consumer. Without one, the tool is refused. Once an external operation has reached approval, disconnecting the consumer does not resubmit or execute it; it remains pending until approved or cancelled. Revoking a connection stops its unfinished work and children while retaining the records. Changing its access policy cancels unfinished work so an old approval cannot authorize the new policy.

Use kiki_save_text or the session's note editor to save supplied text with its source kind. These are external records, not verified user messages or an automatically synchronized chat. Continue locally previews saved text and native tool records, then creates a separate local branch; select a local model and send a goal explicitly. The preview reads a bounded subset without calling a model: partial or unavailable material is not an empty report. Large results can be paged with kiki_operation and action: "read"; follow its next request. Text ranges use UTF-16 offsets, media ranges use byte offsets, and media chunks are base64 resources from the saved result rather than the current host file.

Only grant access to clients you trust. Native permissions and workspace file checks remain in force, but local command access can run processes with the host user's privileges; it is not an operating-system sandbox. If the shared folder contains Kiki's private home, give Glob/Grep a narrower search folder outside that home. Workspace Memory is the default, global Memory requires explicit sharing, and persona administration is not exposed.

Next steps

• Plugins — Declare MCP servers in a plugin manifest to package and distribute them together
• Configuration files — Full field reference for permission rules