@ikhono/mcp

MCP server for 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

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

Claude Desktop

Add to claude_desktop_config.json:

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

Cursor

Add to .cursor/mcp.json:

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

Windsurf

Add to ~/.codeium/windsurf/mcp_config.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:

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:

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

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
• Creating Skills
• CLI Reference
• GitHub

License

MIT