IDE Integration

Kodebase connects to your AI coding assistant through the Model Context Protocol (MCP), enabling seamless project intelligence without leaving your development environment.

How It Works

MCP is an open protocol that allows AI assistants to access external tools and context. Kodebase provides an MCP server that exposes:

1. Scout tools - For planning and spec generation
2. Sherpa tools - For implementation context and guidance
3. Configuration tools - For project setup and settings

┌─────────────────┐     MCP      ┌─────────────────┐
│  AI Assistant   │◄────────────►│ Kodebase Server │
│  (Claude, etc.) │              │                 │
└─────────────────┘              └────────┬────────┘
                                          │
                                          ▼
                                 ┌─────────────────┐
                                 │  .kodebase/     │
                                 │  artifacts/     │
                                 └─────────────────┘

What the LLM Sees

When connected via MCP, your AI assistant has access to:

Project Context

• Current artifact status (ready, in-progress, blocked)
• Artifact hierarchy and relationships
• Implementation notes from completed work
• Quality gates and acceptance criteria

Available Tools

The AI can call Kodebase tools directly:

scout_start_session    - Begin planning a feature
scout_submit_answers   - Answer clarifying questions
sherpa_get_status      - Check what's ready to work on
sherpa_get_context     - Get implementation context
kodebase_get_config    - Read project configuration

Contextual Awareness

The AI understands:

• Which issue you're currently working on
• What dependencies exist
• What patterns were used in related issues
• What challenges were encountered before

Supported Clients

Claude Code

Claude Code has built-in MCP support. Add Kodebase to your configuration:

{
  "mcpServers": {
    "kodebase": {
      "command": "npx",
      "args": ["@anthropic/kodebase-mcp-server"]
    }
  }
}

Cursor

Cursor supports MCP servers through its settings. Configure the Kodebase server in your Cursor MCP settings.

Other MCP Clients

Any client implementing the MCP specification can connect to Kodebase. Check your client's documentation for MCP configuration.

VSCode Extension

The Kodebase VSCode extension provides additional IDE integration:

Work Tracker Panel

A dedicated panel showing:

• Current artifact status
• In-progress issues with PR links
• Ready issues you can start
• Blocked issues and their dependencies

Quick Actions

• Start Issue - Begin work on a ready issue
• View Context - See full artifact details
• Submit Work - Complete current issue

Status Bar

Shows your current working issue and its state at a glance.

Notifications

Get notified when:

• Dependencies are resolved (issue becomes ready)
• PR checks complete
• Artifacts need attention

Example: Full Integration Flow

Here's how IDE integration works in practice:

1. Open Your Project

$ code my-project

The VSCode extension detects .kodebase/ and activates.

2. Check Status

In Claude Code or your AI assistant:

You: What should I work on?

AI: [calls sherpa_get_status]

Based on your project status:

Ready to start:
• H.2.1: Add input validation
• H.2.2: Error handling middleware

In progress:
• H.1.3: JWT validation (your current branch)

I recommend finishing H.1.3 first since you're already
on that branch.

3. Get Implementation Help

You: How should I structure the JWT validation?

AI: [calls sherpa_get_context for H.1.3]

Based on the artifact context:

The validation should:
1. Use the existing auth middleware pattern from H.1.1
2. Handle these token states: valid, expired, invalid
3. Follow the error response format defined in H.1.2

Here's a suggested implementation:

[AI provides context-aware code suggestion]

4. Complete Work

You: I've finished the implementation, tests pass

AI: Great! You can submit with:

kb submit

This will:
- Push your changes
- Mark PR ready for review
- Update H.1.3 status to completed
- Record any implementation notes

Configuration

MCP Server Settings

Configure Kodebase behavior in .kodebase/config.yml:

mcp:
  auto_context: true      # Automatically provide artifact context
  include_notes: true     # Include implementation notes in context
  max_context_depth: 2    # How many related artifacts to include

Extension Settings

Configure the VSCode extension in your settings:

{
  "kodebase.showStatusBar": true,
  "kodebase.autoRefresh": true,
  "kodebase.refreshInterval": 30000
}

Next Steps

• Install Kodebase in your project
• Follow the Quickstart tutorial
• Explore MCP Tools reference