MCP Integration

Connect Knowns with AI assistants using Model Context Protocol

8 min read

MCP Integration

Integrate Knowns with AI assistants for seamless development workflows.

What is MCP?

Model Context Protocol (MCP) is a standard for connecting AI assistants to external tools and data sources. Knowns implements an MCP server that allows AI to read and manage your tasks and documentation directly.

Session Initialization (Critical)

At the START of every MCP session, run these tools to set the project context:

// 1. Detect available projects
mcp__knowns__detect_projects({})
 
// 2. Set the active project
mcp__knowns__set_project({ "projectRoot": "/path/to/project" })
 
// 3. Verify project is set
mcp__knowns__get_current_project({})

Why? MCP servers (especially global configs like Antigravity/Gemini) don't know which project to work with. Without setting the project, operations will fail or affect the wrong directory.

Support Matrix

Platform	Config File	Auto-discover	Project Scope
Claude Code	`.mcp.json` (project)	Yes	Per-project
Antigravity	`~/.gemini/antigravity/mcp_config.json` (global)	Yes	Needs `set_project`
Gemini CLI	`~/.gemini/settings.json` (global)	Yes	Needs `set_project`
Cursor	`.cursor/mcp.json` (project)	Manual	Per-project
Cline	`.cline/mcp.json` (project)	Manual	Per-project
Continue	`.continue/config.json` (project)	Manual	Per-project

Knowns MCP Server

{
  "command": "npx",
  "args": ["-y", "knowns", "mcp"]
}

Setup

Option A: Auto Setup (Recommended)

knowns mcp setup

What happens:

Creates .mcp.json in your project for Claude Code auto-discovery
Registers the Knowns MCP server with the Claude CLI if installed
Reminds you to restart Claude Code to load the server

Variations

knowns mcp setup --project — only create/update .mcp.json in this project
knowns mcp setup --global — only register with Claude Code CLI

Option B: Manual Setup

Platform Configs

Claude Code: `.mcp.json` (Project-level)

{
  "mcpServers": {
    "knowns": {
      "command": "npx",
      "args": ["-y", "knowns", "mcp"]
    }
  }
}

Antigravity: `~/.gemini/antigravity/mcp_config.json` (Global)

{
  "mcpServers": {
    "knowns": {
      "command": "npx",
      "args": ["-y", "knowns", "mcp"]
    }
  }
}

Note: Antigravity uses global config. Use detect_projects and set_project at session start.

Gemini CLI: `~/.gemini/settings.json` (Global)

{
  "mcpServers": {
    "knowns": {
      "command": "npx",
      "args": ["-y", "knowns", "mcp"]
    }
  }
}

Cursor: `.cursor/mcp.json`

{
  "mcpServers": {
    "knowns": {
      "command": "npx",
      "args": ["-y", "knowns", "mcp"]
    }
  }
}

Continue: `.continue/config.json`

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "knowns",
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "knowns", "mcp"]
        }
      }
    ]
  }
}

CLI Commands

# Auto-generate MCP config
knowns mcp init --all
knowns mcp init --platform claude,cursor
 
# Check status
knowns mcp status

Usage

Once configured, Claude can access your Knowns data automatically.

Example Conversation

You: "Start working on task 42"
 
Claude: [Reads task via MCP]
"I see task #42 'Add user authentication' with these acceptance criteria:
- User can login with email/password
- JWT token is returned on success
- Invalid credentials return 401
 
The description references @doc/patterns/auth. Let me check that..."
 
[Fetches patterns/auth.md via MCP]
 
"Got it! The auth pattern uses JWT with 15-minute access tokens and
7-day refresh tokens. I'll implement following this pattern.
 
Starting timer and beginning implementation..."
 
[Starts time tracking via MCP]

Guidelines for MCP

Sync Instruction Files

# Sync with full embedded MCP guidelines (default)
knowns agents sync --type mcp
 
# Sync with minimal instruction only
knowns agents sync --type mcp --minimal
 
# Sync all files
knowns agents sync --type mcp --all

MCP Guideline Tool

AI agents can get modular guidelines on-demand via MCP:

mcp__knowns__get_guideline({})                    # Full guidelines (all sections)
mcp__knowns__get_guideline({ type: "unified" })   # Same as above

Guidelines include these sections:

Core Rules - Golden rules, must-follow principles
Commands Reference - CLI/MCP commands quick reference
Workflow Creation/Execution/Completion - Stage-specific guides
Common Mistakes - Anti-patterns and DO vs DON'T

Available MCP Tools

Project Tools (Session Init)

Tool	Description
`mcp__knowns__detect_projects`	Scan for Knowns projects
`mcp__knowns__set_project`	Set active project
`mcp__knowns__get_current_project`	Get current project status

Tasks

Tool	Description
`mcp__knowns__list_tasks`	List tasks
`mcp__knowns__get_task`	Get task
`mcp__knowns__create_task`	Create task
`mcp__knowns__update_task`	Update task (status, AC, plan, notes)
`mcp__knowns__search_tasks`	Search tasks

Docs

Tool	Description
`mcp__knowns__list_docs`	List docs
`mcp__knowns__get_doc`	Get doc (with smart mode)
`mcp__knowns__create_doc`	Create doc
`mcp__knowns__update_doc`	Update doc
`mcp__knowns__search_docs`	Search docs

Time

Tool	Description
`mcp__knowns__start_time`	Start timer
`mcp__knowns__stop_time`	Stop timer
`mcp__knowns__add_time`	Add manual time entry
`mcp__knowns__get_time_report`	Get time report

Templates

Tool	Description
`mcp__knowns__list_templates`	List templates
`mcp__knowns__get_template`	Get template config
`mcp__knowns__run_template`	Run template
`mcp__knowns__create_template`	Create template scaffold

Other

Tool	Description
`mcp__knowns__search`	Unified search (tasks + docs)
`mcp__knowns__get_board`	Get kanban board

MCP vs CLI

Aspect	MCP	CLI
Speed	Faster	Slower
Output	JSON	Text
Complex ops	Full support	Full support

Recommendation: Use MCP for all operations when available.

Full Feature Parity

Feature	CLI	MCP
List tasks	`task list`	`list_tasks`
Get task	`task <id>`	`get_task`
Create task	`task create`	`create_task`
Update status	`task edit -s`	`update_task`
Add AC	`--ac`	`addAc`
Check AC	`--check-ac`	`checkAc`
Set plan	`--plan`	`plan`
Set notes	`--notes`	`notes`
Append notes	`--append-notes`	`appendNotes`
Time tracking	`time start/stop`	`start_time/stop_time`
List docs	`doc list`	`list_docs`
Get doc	`doc <path>`	`get_doc`
Create doc	`doc create`	`create_doc`
Update doc	`doc edit`	`update_doc`
Search	`search`	`search`
Templates	`template run`	`run_template`
Project detection	N/A	`detect_projects`

Large Document Workflow:

// Step 1: Use smart mode (recommended) - auto-handles size
{ "path": "readme", "smart": true }
// Small doc → returns full content
// Large doc → returns stats + TOC
 
// Step 2: Read specific section (if large)
{ "path": "readme", "section": "2" }
 
// Edit specific section only
{ "path": "readme", "section": "2", "content": "New content" }

Example: Full Task Workflow via MCP

// 0. Session init (required for global MCP configs)
mcp__knowns__detect_projects({})
mcp__knowns__set_project({ "projectRoot": "/path/to/project" })
 
// 1. Get task
mcp__knowns__get_task({ "taskId": "abc123" })
 
// 2. Take task
mcp__knowns__update_task({
  "taskId": "abc123",
  "status": "in-progress",
  "assignee": "@me"
})
 
// 3. Start timer
mcp__knowns__start_time({ "taskId": "abc123" })
 
// 4. Add acceptance criteria
mcp__knowns__update_task({
  "taskId": "abc123",
  "addAc": ["User can login"]
})
 
// 5. Set implementation plan
mcp__knowns__update_task({
  "taskId": "abc123",
  "plan": "1. Research\n2. Implement\n3. Test"
})
 
// 6. Check AC after completing
mcp__knowns__update_task({
  "taskId": "abc123",
  "checkAc": [1]
})
 
// 7. Append progress notes
mcp__knowns__update_task({
  "taskId": "abc123",
  "appendNotes": "✓ Completed: login feature"
})
 
// 8. Stop timer
mcp__knowns__stop_time({ "taskId": "abc123" })
 
// 9. Mark done
mcp__knowns__update_task({
  "taskId": "abc123",
  "status": "done"
})

Benefits

Zero Context Loss

AI reads your docs directly - no copy-paste
References (@doc/..., @task-42) are resolved automatically
Project patterns are always available

Consistent Implementations

AI follows your documented patterns every time
Same conventions across all sessions
No more "how does your auth work?" questions

Perfect Memory

Documentation persists between sessions
AI can reference any past decision
Knowledge doesn't live in chat history

Time Tracking Integration

AI can start/stop timers automatically
Track time spent on each task
Generate reports for retrospectives

Troubleshooting

MCP server not responding

Verify installation: knowns --version
Run knowns mcp setup again
Restart your AI assistant

Project not detected

# Check project is initialized
knowns init
 
# For global configs, use session init
mcp__knowns__detect_projects({})
mcp__knowns__set_project({ "projectRoot": "/path" })

Tools not appearing

knowns init          # ensure project initialized
knowns mcp --info    # print configuration example

Alternative: --plain Output

If MCP is not available, use --plain flag for AI-readable output:

knowns task 42 --plain | pbcopy  # Copy to clipboard
knowns doc "auth-pattern" --plain

Then paste into any AI assistant.

MCP Integration

MCP Integration

What is MCP?

Session Initialization (Critical)

Support Matrix

Knowns MCP Server

Setup

Option A: Auto Setup (Recommended)

Option B: Manual Setup

Platform Configs

Claude Code: .mcp.json (Project-level)

Antigravity: ~/.gemini/antigravity/mcp_config.json (Global)

Gemini CLI: ~/.gemini/settings.json (Global)

Cursor: .cursor/mcp.json

Continue: .continue/config.json

CLI Commands

Usage

Example Conversation

Guidelines for MCP

Sync Instruction Files

MCP Guideline Tool

Available MCP Tools

Project Tools (Session Init)

Tasks

Docs

Time

Templates

Other

MCP vs CLI

Full Feature Parity

Example: Full Task Workflow via MCP

Benefits

Zero Context Loss

Consistent Implementations

Perfect Memory

Time Tracking Integration

Troubleshooting

MCP server not responding

Project not detected

Tools not appearing

Alternative: --plain Output

Resources

Claude Code: `.mcp.json` (Project-level)

Antigravity: `~/.gemini/antigravity/mcp_config.json` (Global)

Gemini CLI: `~/.gemini/settings.json` (Global)

Cursor: `.cursor/mcp.json`

Continue: `.continue/config.json`