Skip to Content
MCP ServerMCP Server

MCP Server

The airs-mcp is an optional MCP (Model Context Protocol) server that extends AI assistants with capabilities that pure prompting can’t provide.

When Do You Need It?

You don’t need the MCP server if:

  • You just want to read and follow skills (use the docs site or raw files)
  • You’re contributing skills (use the CLI validator)
  • Your AI assistant can read the skill files directly

You need the MCP server if:

  • You want AI-assisted skill discovery and filtering
  • You need semantic search across skills
  • You want structured tool access beyond text-based prompting

What It Solves

Skills are documentation — they tell you how to do something. But some research tasks require:

  1. Structured queries: Filter skills by tags, search semantically
  2. Semantic search: Find skills by meaning, not just keywords
  3. Programmatic access: Machine-readable skill data for AI clients

The MCP server provides these as callable tools that AI clients can invoke.

Runtime Model

Default: Local Skills Directory

npm install
npm run mcp -- --skills-dir ./skills

The server reads skills.semantic.json from docs/public/ (generated by the sync script). It will also try to auto-discover this file by walking up parent directories, so running from the repo root is usually enough.

Alternative: Pre-built Catalog

npm install
npm run mcp -- --catalog ./catalog.json

Use a pre-generated JSON catalog for faster startup (useful in production).

Implemented Tools

ToolDescription
skills.listList skills with optional filtering (category, tags)
skills.getGet full skill content by ID
skills.semantic_searchSemantic search with keyword fallback

Search skills by meaning using natural language queries:

{
  "method": "skills.semantic_search",
  "params": {
    "query": "how to analyze text patterns",
    "top_k": 5
  }
}

Returns:

{
  "results": [
    { "id": "analysis.textual-analysis-basic", "score": 8.0, "title": "...", "summary": "..." }
  ],
  "method": "keyword_fallback",
  "provider": "none"
}

Fallback Behavior:

When no embedding provider is configured, the search uses keyword-based ranking:

  • Title matches: 3.0 points
  • Summary matches: 2.0 points
  • Tag matches: 1.5 points
  • Content matches: 1.0 points

Environment Configuration

VariableValuesDescription
AIRS_EMBED_PROVIDERnone, cloudflareEmbedding provider for semantic search
# Use Cloudflare AI for semantic ranking
export AIRS_EMBED_PROVIDER=cloudflare
export CLOUDFLARE_ACCOUNT_ID=...
export CLOUDFLARE_API_TOKEN=...
npm run mcp -- --skills-dir ./skills

Client Configuration

Claude Code / Claude Desktop

Add to your MCP settings (~/.claude/settings.json or similar):

{
  "mcpServers": {
    "airs": {
      "command": "/path/to/ai-research-skills/node_modules/.bin/tsx",
      "args": ["/path/to/ai-research-skills/mcp/airs-mcp.ts", "--skills-dir", "/path/to/ai-research-skills/skills"]
    }
  }
}

Other MCP Clients

Any MCP-compatible client can connect using stdio transport:

{
  "command": "tsx",
  "args": ["mcp/airs-mcp.ts", "--skills-dir", "./skills"],
  "transport": "stdio"
}

Status

Working - Core tools implemented with keyword fallback; Cloudflare semantic ranking is supported.

Run with --health (or health) to verify it’s working:

npm run mcp:health
# {"status":"ok","message":"AI Research Skills MCP server","skills_loaded":2,"embed_provider":"none"}
  • Clients - Different ways to use AI Research Skills
  • CLI Tool - Validator for contributors
Last updated on