> 🌐 Language: **English** | [中文](MCP-Server.zh-CN.md)

# MCP Server

KinetAios includes a **built-in MCP (Model Context Protocol) Server** — an HTTP+SSE endpoint that exposes your local agent to remote machines. Other KinetAios instances (or any MCP-compatible client) can invoke `run_agent` to run tasks on your machine with full tool access.

This is the foundation of the [[Town]] remote collaboration feature.

## How it works

```
Remote machine                          Your machine (MCP Server)
     │                                            │
     │  POST /mcp  (JSON-RPC over HTTP)           │
     │  Authorization: Bearer <token>             │
     │ ─────────────────────────────────────────> │
     │                                            │  → run_agent(prompt, cwd, engine)
     │                                            │  → TaskManager dispatches to engine
     │                                            │  → streams AgentEvents
     │  <── SSE: data: {type:"token",...} ──────  │
     │  <── SSE: data: {type:"tool",...}  ──────  │
     │  <── SSE: data: {type:"done"}     ──────  │
     │                                            │
```

## Configuration

In **⚙ Settings → Behavior**:

| Setting | Effect |
|---|---|
| MCP Server enabled | Toggles the HTTP listener |
| Port | Default `0` (random) → displayed in status bar after start |
| Token | Auto-generated; required for all requests |

The server binds `0.0.0.0` (accessible from LAN). The token is shown in the status bar when the server is running.

## Authentication

- **Bearer token** in `Authorization` header (timing-safe comparison via HMAC-SHA256 normalization — no length-based timing leak).
- SSE endpoints **reject tokens passed as URL query parameters** (prevent logging in proxy/CDN logs).
- 5-minute idle timeout per connection.

## Endpoints

| Method | Path | Description |
|---|---|---|
| `POST` | `/mcp` | JSON-RPC: `tools/list`, `tools/call` (returns SSE stream for `run_agent`) |
| `GET` | `/mcp` | SSE event stream (live agent events, read-only) |
| `GET` | `/` | Health check: `{ ok: true, server, mcp: true }` |

## `run_agent` tool

The primary remote tool. Accepts:

```json
{
  "prompt": "Fix the failing tests in src/utils.test.ts",
  "cwd": "/home/user/project",
  "engine": "direct",
  "model": "glm-4.6"
}
```

Returns an SSE stream of `AgentEvent`s (`token`, `tool`, `cost`, `status`, `done`, `error`) — same unified event union used internally.

## Other exposed tools

- `list_conversations` — list local sessions
- `export_session` — serialize a session for handoff (auto-redacts API keys/secrets)
- `import_session` — deserialize a session (validates message structure, role whitelist, length limits)
- `sync_memories` — push/pull long-term memories between machines (deduplicates by content)
- `search_history` — FTS5 full-text search across all conversations

## Security

- **Export redaction**: `exportSession` strips API keys, secrets, and tokens matching common patterns (`sk-...`, `api_key=...`, etc.) before serialization.
- **Import validation**: `importSession` validates message roles (whitelist: system/user/assistant/tool), content types, and enforces length limits (500 messages, 50K chars/message).
- **Zombie connection cleanup**: SSE connections track backpressure; 3 consecutive write failures → destroy + remove from active list.

## Key source files

- `src/main/mcp-server.ts` — HTTP server, SSE streaming, tool dispatch, auth
- `src/main/TaskManager.ts` — `runAgent`, `exportSession`, `importSession`, `syncMemories`
- `src/shared/types.ts` — `AgentEvent` union, `McpTool` type