# MCP Server

Run Sidekick as an MCP (Model Context Protocol) server to expose every CLI command as a tool to connected clients.

## Installation

### Claude Code plugin (recommended)

```bash
claude plugin marketplace add hesedcasa/sdkck
claude plugin install sidekick@mcp
```

This automatically wires up the MCP server — no manual `.mcp.json` configuration needed.

### Configure in Claude Code

For manual setup, add to `.mcp.json`:

```json
{
  "mcpServers": {
    "sdkck": {
      "command": "sdkck",
      "args": ["mcp", "start"]
    }
  }
}
```

### Streamable HTTP

Starts an HTTP server at `http://<host>:<port>/mcp` using the [MCP Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http). Useful for remote clients or multi-session setups.

```bash
sdkck mcp start --transport http
sdkck mcp start --transport http --host 0.0.0.0 --port 3001
```

| Flag | Default | Description |
|------|---------|-------------|
| `--host` | `127.0.0.1` | IP address to listen on |
| `--port` | `3000` | Port to listen on |

### HTTP Authentication

Bearer token authentication for the HTTP transport:

```bash
sdkck mcp token generate  # Create token
sdkck mcp token show      # View token
sdkck mcp token delete    # Remove token (disables auth)
```

Clients must include `Authorization: Bearer <token>` in requests.

## Exposed tools

The MCP server exposes two tools: `search_tools` and `run_command`.

### `search_tools`

A deliberate design choice: Sidekick exposes a single semantic-search entry point rather than registering every underlying command as an individual MCP tool. Loading hundreds of tool definitions upfront consumes significant context and degrades model tool-selection accuracy, so Sidekick follows the progressive tool-discovery pattern described in Anthropic's [Advanced Tool Use](https://www.anthropic.com/engineering/advanced-tool-use) guidance — returning only the small set of commands relevant to the current query, which the agent then invokes via `run_command`.

The tool delegates to the `search` command. It accepts a `query` (required) and an optional `limit` (default 5). Its advertised description includes a deduplicated keyword index built from every command's ID, summary, and description so clients can route queries accurately without enumerating the full tool surface.

### `run_command`

Accepts a command ID and arguments object, builds the argv array, and runs the command. Use `search_tools` first to discover commands and their arguments.

Command IDs accept both separators:

- `"api import"` (space-separated)
- `"api:import"` (colon-separated)

Both resolve to the same command.

## Example:

A typical interaction walks through the two tools in sequence. Suppose the user asks:

> please get this confluence page 1453068888

**Step 1 — discover the right command with `search_tools`:**

```json
{
  "query": "confluence page get",
  "limit": 5
}
```

The server returns a shortlist of candidate commands:

```json
[
  {
    "command": "conni content get <pageId>",
    "description": "Get details of a Confluence content"
  },
  {
    "command": "conni content search <cql>",
    "description": "Search for Confluence contents using CQL"
  },
  ...
]
```

**Step 2 — invoke the chosen command with `run_command`:**

```json
{
  "commandId": "conni content get",
  "args": {
    "pageId": "1453068888"
  }
}
```

The server runs the command and returns its output:

```json
{
  "data": {
    "id": "1453068888",
    "type": "page",
    "ari": "ari:cloud:confluence:4952d4330-8888-5566-a07c-6bdc3f2aff5c:page/1453068888",
    "status": "current",
    "title": "Company MCP Servers",
    ...
  }
}
```

Only the two commands actually used for this task are ever materialised in the client's context window — the rest of Sidekick's command surface stays out of the way until the next query reaches for it.

## Dependencies

- `@modelcontextprotocol/sdk` ^1.29.0

No extra peer dependency installs needed.
