MCP Integration

Gyrus includes a built-in MCP (Model Context Protocol) server that exposes your knowledge and ADR tools to AI agents. This allows any MCP-compatible tool to read, search, create, and update your notes.

What is MCP?

The Model Context Protocol is a standard for connecting AI models to external tools and data sources. Instead of each AI tool implementing its own plugin system, MCP provides a unified interface.

Gyrus acts as an MCP server, exposing tools that AI clients (like Claude, Cursor, or Zed) can call.

Starting the MCP Server

Start the MCP server with:

bash

gyrus mcp

This runs an MCP server over stdio, which is the standard transport for local MCP integrations.

Options

bash

# Use a specific workspace
gyrus mcp --workspace work

Configuring AI Clients

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

json

{
  "mcpServers": {
    "gyrus": {
      "command": "gyrus",
      "args": ["mcp"]
    }
  }
}

Cursor

Add to your Cursor MCP settings (usually in .cursor/mcp.json):

json

{
  "mcpServers": {
    "gyrus": {
      "command": "gyrus",
      "args": ["mcp"]
    }
  }
}

Zed Editor

Add to your Zed settings (~/.config/zed/settings.json):

json

{
  "context_servers": {
    "gyrus": {
      "command": {
        "path": "gyrus",
        "args": ["mcp"]
      }
    }
  }
}

VS Code with Continue

Add to your Continue configuration:

json

{
  "mcpServers": [
    {
      "name": "gyrus",
      "command": "gyrus",
      "args": ["mcp"]
    }
  ]
}

Available Tools

Workspace Management

`gyrus_list`

List all registered workspaces.

Parameters: None required

Returns: Array of workspaces with name, path, description, and available features.

`gyrus_switch`

Switch the active workspace for the current session.

Parameters:

name (required): The workspace name to switch to

Example:

json

{ "name": "work" }

Knowledge Tools

`knowledge_list`

List all knowledge notes with optional filtering.

Parameters:

workspace (optional): Target workspace name
category (optional): Filter by category (projects, patterns, tools, gotchas, decisions)
tags (optional): Filter by tags (matches notes with any of these tags)

Example:

json

{ "category": "patterns", "tags": ["reliability"] }

`knowledge_read`

Read a specific knowledge note by ID or path.

Parameters:

id (optional): The note's unique identifier
path (optional): The relative file path
workspace (optional): Target workspace name

At least one of id or path must be provided.

Example:

json

{ "id": "pattern-retry-with-backoff" }

`knowledge_search`

Search knowledge notes by text, tags, or category.

Parameters:

query (optional): Text to search in titles, content, and descriptions
category (optional): Filter by category
tags (optional): Filter by tags
workspace (optional): Target workspace name

At least one search parameter must be provided.

Example:

json

{ "query": "authentication", "tags": ["security"] }

`knowledge_create`

Create a new knowledge note.

Parameters:

id (required): Unique identifier in kebab-case
title (required): Human-readable title
category (required): Category folder (projects, patterns, tools, gotchas, decisions)
content (required): Markdown content (without frontmatter)
description (optional): Brief description
tags (optional): Tags for categorization
related (optional): IDs of related notes
workspace (optional): Target workspace name

Example:

json

{
  "id": "pattern-circuit-breaker",
  "title": "Circuit Breaker Pattern",
  "category": "patterns",
  "content": "# Circuit Breaker Pattern\n\nPrevent cascading failures by failing fast...",
  "tags": ["patterns", "reliability"]
}

`knowledge_update`

Update an existing knowledge note.

Parameters:

id (required): The note's unique identifier
title (optional): New title
content (optional): New markdown content
description (optional): New description
tags (optional): New tags (replaces existing)
related (optional): New related note IDs (replaces existing)
workspace (optional): Target workspace name

Only provided fields are updated. The updated date is automatically set.

Example:

json

{
  "id": "pattern-circuit-breaker",
  "tags": ["patterns", "reliability", "microservices"]
}

ADR Tools

`adr_list`

List all Architecture Decision Records with optional filtering.

Parameters:

workspace (optional): Target workspace name
status (optional): Filter by status (todo, in-progress, in-review, blocked, completed, deprecated)
type (optional): Filter by type (enhancement, debug, research)
tags (optional): Filter by tags

Example:

json

{ "status": "in-progress", "type": "enhancement" }

`adr_read`

Read a specific ADR by name.

Parameters:

name (required): ADR filename (without .md) or partial match
workspace (optional): Target workspace name

Example:

json

{ "name": "oauth-authentication" }

`adr_search`

Search ADRs by text, status, type, or tags.

Parameters:

query (optional): Text to search in titles, descriptions, and content
status (optional): Filter by status
type (optional): Filter by type
tags (optional): Filter by tags
workspace (optional): Target workspace name

Example:

json

{ "query": "database", "status": "completed" }

`adr_create`

Create a new Architecture Decision Record.

Parameters:

title (required): Human-readable title
type (required): ADR type (enhancement, debug, research)
workingFolder (required): Full path to the project working folder
description (optional): Brief description
status (optional): Initial status (defaults to 'todo')
tags (optional): Tags for categorization
content (optional): Custom content (uses default template if not provided)
workspace (optional): Target workspace name

Example:

json

{
  "title": "OAuth Authentication",
  "type": "enhancement",
  "workingFolder": "/Users/name/project",
  "description": "Add OAuth 2.0 authentication to the API",
  "tags": ["api", "security"]
}

`adr_update`

Update an existing ADR.

Parameters:

name (required): ADR to update (partial match supported)
status (optional): New status
title (optional): New title
description (optional): New description
content (optional): New content
tags (optional): New tags
type (optional): New type
workingFolder (optional): New working folder
workspace (optional): Target workspace name

Example:

json

{
  "name": "oauth-authentication",
  "status": "in-progress"
}

Skill Tools

`skill_list`

List all skills with optional filtering.

Parameters:

workspace (optional): Target workspace name
tags (optional): Filter by tags

Example:

json

{ "tags": ["typescript", "quality"] }

`skill_read`

Read a specific skill by name.

Parameters:

name (required): The skill name (e.g., 'code-review')
workspace (optional): Target workspace name

Example:

json

{ "name": "code-review" }

`skill_search`

Search skills by text, tags, or trigger.

Parameters:

query (optional): Text to search in names, titles, content, and descriptions
tags (optional): Filter by tags
trigger (optional): Filter by trigger pattern (e.g., '/code-review')
workspace (optional): Target workspace name

Example:

json

{ "query": "testing", "tags": ["quality"] }

Or by trigger:

json

{ "trigger": "/code-review" }

`skill_create`

Create a new skill.

Parameters:

name (required): Unique name in kebab-case
title (required): Human-readable title
content (required): Markdown content (without frontmatter)
description (optional): Brief description
tags (optional): Tags for categorization
triggers (optional): Trigger patterns that activate this skill
applyTo (optional): File patterns this skill applies to
related (optional): Names of related skills
workspace (optional): Target workspace name

Example:

json

{
  "name": "code-review",
  "title": "Code Review Guide",
  "content": "# Code Review\n\nWhen reviewing code, follow these guidelines...",
  "tags": ["quality", "review"],
  "triggers": ["/code-review", "/review"]
}

`skill_update`

Update an existing skill.

Parameters:

name (required): The skill name to update
title (optional): New title
content (optional): New content
description (optional): New description
tags (optional): New tags (replaces existing)
triggers (optional): New triggers (replaces existing)
applyTo (optional): New applyTo patterns (replaces existing)
related (optional): New related skill names (replaces existing)
workspace (optional): Target workspace name

Example:

json

{
  "name": "code-review",
  "tags": ["quality", "review", "process"]
}

Example Workflows

Knowledge Capture

User: I just figured out how to handle rate limits in the Stripe API.

Agent: I'll save that to your knowledge base.
[calls knowledge_create]
  id: "gotcha-stripe-rate-limits"
  title: "Stripe API Rate Limits"
  category: "gotchas"
  content: "..."
  tags: ["stripe", "api", "rate-limiting"]

Spec-Driven Development

User: I want to add user authentication to the app.

Agent: Let me create an ADR to plan this feature.
[calls adr_create]
  title: "User Authentication"
  type: "enhancement"
  workingFolder: "/Users/name/myapp"

Agent: I've created the ADR. Let me research the options and update it.
[calls adr_update with research findings]

User: Looks good. Let's start implementing.

Agent: Updating status to in-progress.
[calls adr_update]
  name: "user-authentication"
  status: "in-progress"

Cross-Session Context

User: What do we know about the payment system?

Agent: Let me search your knowledge base.
[calls knowledge_search]
  query: "payment"

Agent: I found 3 relevant notes:
- tool-stripe: Stripe integration notes
- gotcha-stripe-webhooks: Webhook handling pitfalls
- pattern-idempotency: Idempotent payment processing

Would you like me to read any of these?

Loading a Skill

User: Review this code using our review guidelines.

Agent: Let me load the code review skill.
[calls skill_read]
  name: "code-review"

Agent: Using the code review guidelines, I'll check:
- Code follows project conventions
- Tests are included
- Error handling is appropriate
...

Troubleshooting

Server Not Starting

Check that Gyrus is installed and accessible:

bash

which gyrus
gyrus --version

Tools Not Appearing

Ensure your MCP client configuration is correct. Restart the client after changing configuration.

Wrong Workspace

Use gyrus_switch to change workspaces, or specify workspace parameter in each tool call.

Next Steps

Knowledge Notes — Learn about note structure
ADRs — Track architectural decisions
Skills — Create reusable AI instructions
Commands Reference — Full CLI documentation

MCP Integration ​

What is MCP? ​

Starting the MCP Server ​

Options ​

Configuring AI Clients ​

Claude Desktop ​

Cursor ​

Zed Editor ​

VS Code with Continue ​

Available Tools ​

Workspace Management ​

gyrus_list ​

gyrus_switch ​

Knowledge Tools ​

knowledge_list ​

knowledge_read ​

knowledge_search ​

knowledge_create ​

knowledge_update ​

ADR Tools ​

adr_list ​

adr_read ​

adr_search ​

adr_create ​

adr_update ​

Skill Tools ​

skill_list ​

skill_read ​

skill_search ​

skill_create ​

skill_update ​

Example Workflows ​

Knowledge Capture ​

Spec-Driven Development ​

Cross-Session Context ​

Loading a Skill ​

Troubleshooting ​

Server Not Starting ​

Tools Not Appearing ​

Wrong Workspace ​

Next Steps ​

MCP Integration

What is MCP?

Starting the MCP Server

Options

Configuring AI Clients

Claude Desktop

Cursor

Zed Editor

VS Code with Continue

Available Tools

Workspace Management

`gyrus_list`

`gyrus_switch`

Knowledge Tools

`knowledge_list`

`knowledge_read`

`knowledge_search`

`knowledge_create`

`knowledge_update`

ADR Tools

`adr_list`

`adr_read`

`adr_search`

`adr_create`

`adr_update`

Skill Tools

`skill_list`

`skill_read`

`skill_search`

`skill_create`

`skill_update`

Example Workflows

Knowledge Capture

Spec-Driven Development

Cross-Session Context

Loading a Skill

Troubleshooting

Server Not Starting

Tools Not Appearing

Wrong Workspace

Next Steps