npm package: @ikhono/mcp
Description: iKhono MCP Server — runtime skill router for AI agents
Latest version: 0.3.2

# @ikhono/mcp

MCP server for [iKhono](https://github.com/ikhono-ai/ikhono) — a runtime skill router that gives AI agents access to community-built skills on the fly.

No local skill installation needed. Your AI agent searches, loads, and follows skills directly from the iKhono registry.

## Quick Setup

### Claude Code

```bash
claude mcp add ikhono -- npx -y @ikhono/mcp
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ikhono": {
      "command": "npx",
      "args": ["-y", "@ikhono/mcp"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ikhono": {
      "command": "npx",
      "args": ["-y", "@ikhono/mcp"]
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "ikhono": {
      "command": "npx",
      "args": ["-y", "@ikhono/mcp"]
    }
  }
}
```

## Authentication

To use authenticated features (pinning, rating, publishing your own skills), log in with the CLI first:

```bash
npx @ikhono/cli login   # GitHub SSO (opens browser)
```

The MCP server automatically reads your token from `~/.ikhono/config.json`.

You can also pass credentials directly:

```bash
# Via CLI args
npx @ikhono/mcp --token YOUR_TOKEN --api-url https://ikhono.io

# Via environment variables
IKHONO_API_TOKEN=YOUR_TOKEN npx @ikhono/mcp
```

**Priority order:** environment variables > CLI args > `~/.ikhono/config.json`

## Available Tools

| Tool | Description |
|------|-------------|
| `ikhono_skill_search` | Search for skills by query, category, or author (returns top 3 previews) |
| `ikhono_skill_get` | Load a skill's full instructions by slug |
| `ikhono_skill_pin` | Pin a skill to your favorites |
| `ikhono_skill_unpin` | Remove a skill from your favorites |
| `ikhono_skill_list_pinned` | List your pinned skills |
| `ikhono_skill_rate` | Rate a skill (1-5 stars) |

### ikhono_skill_search

Search for skills matching a query. Returns a concise preview of the top results (default: 3) with name, description, rating, and usage stats. Use `ikhono_skill_get` to load the full skill instructions.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | No | Search text (e.g., "code review", "test writing") |
| `category` | string | No | Filter by category |
| `author` | string | No | Filter by author (e.g., "@alice") |
| `mine` | boolean | No | Show only your skills |
| `limit` | number | No | Max results (default: 3) |

### ikhono_skill_get

Load a skill's full content to follow its instructions.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `slug` | string | Yes | Skill slug (e.g., "@alice/code-reviewer") |

### ikhono_skill_pin / ikhono_skill_unpin

Pin or unpin a skill.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `slug` | string | Yes | Skill slug to pin/unpin |

### ikhono_skill_list_pinned

List all pinned skills. No parameters.

### ikhono_skill_rate

Rate a skill after using it.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `slug` | string | Yes | Skill slug to rate |
| `stars` | number | Yes | Rating from 1 to 5 |
| `review` | string | No | Optional text review |

## Streamable HTTP Transport

The iKhono MCP server is also available as a hosted HTTP endpoint, useful for MCP registries (Smithery, etc.) and web-based clients:

```
POST https://ikhono.io/mcp
```

Headers:
- `Content-Type: application/json`
- `Accept: application/json, text/event-stream`
- `Authorization: Bearer YOUR_TOKEN` (optional, for authenticated operations)

Sessions are stateful — the server returns an `Mcp-Session-Id` header to include in subsequent requests.

### Programmatic Usage

The server factory and client are available as package exports for embedding in your own server:

```typescript
import { createMcpServer } from '@ikhono/mcp/server';
import { IkhonoClient } from '@ikhono/mcp/client';

const client = new IkhonoClient({ apiUrl: 'https://ikhono.io', token: 'optional' });
const server = createMcpServer(client);
// Connect your own transport...
```

## How It Works

1. Your AI agent receives a task (e.g., "review this code")
2. The agent calls `ikhono_skill_search` to find relevant skills (top 3 previews)
3. The user picks which skill to load — the agent calls `ikhono_skill_get` with that slug
4. The agent follows the skill's instructions for a better, more structured response

If none of the results fit, the user can ask to search again with a higher `limit` or a different query.

Skills are community-created Markdown documents with structured processes, checklists, and templates. The MCP server is a thin proxy to the iKhono API — no local storage or computation needed.

## Links

- [Getting Started](https://github.com/ikhono-ai/ikhono/blob/main/docs/getting-started.md)
- [Creating Skills](https://github.com/ikhono-ai/ikhono/blob/main/docs/creating-skills.md)
- [CLI Reference](https://github.com/ikhono-ai/ikhono/blob/main/docs/cli-reference.md)
- [GitHub](https://github.com/ikhono-ai/ikhono)

## License

MIT