MCP Integration Guide

Complete guide to integrating Kybernesis Brain with AI agents via the Model Context Protocol (MCP).

What is MCP?
Why Integrate with AI Agents?
Prerequisites
Generate an API Key
Claude Desktop Setup
Available MCP Tools
Testing the Integration
Troubleshooting
Security Best Practices
Example Workflows

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect with external data sources and tools. It provides:

Standardized Communication: Common protocol for AI tools to interact with services
Secure Authentication: Token-based access control
Tool Discovery: Automatic detection of available capabilities
Type Safety: Structured schemas for requests and responses

Kybernesis Brain implements MCP to let AI agents like Claude Code directly access, search, and store memories in your knowledge base.

Why Integrate with AI Agents?

Connecting Kybernesis to AI agents enables powerful workflows:

Persistent Context: Agents remember conversations, decisions, and facts across sessions
Knowledge Retrieval: Agents can search your entire memory corpus to answer questions
Automatic Storage: Agents store important information without manual intervention
Connected Insights: Agents leverage relationship graphs to find related memories
Multi-Source Intelligence: Query memories from uploads, chats, Google Drive, and Notion

Example use case: An AI coding assistant that remembers your project's architecture decisions, API designs, and common patterns—surfacing them automatically when writing new code.

Prerequisites

Before setting up MCP integration, ensure you have:

Kybernesis Account: Active organization with memories
Claude Desktop (for Claude Code integration) or another MCP-compatible client
API Access: Ability to generate API keys from the web console
Network Access: Ability to reach https://api.kybernesis.ai

Generate an API Key

API keys authenticate MCP requests from AI agents.

Step-by-Step Key Generation

Open Kybernesis: Navigate to https://kybernesis.ai
Open Settings: Press Cmd+A (or Ctrl+A on Windows)
Navigate to API Access: Scroll to the "API Access" section
Generate New Key: Click "+ Generate New API Key"
Enter key name: Give it a descriptive name like "Claude Desktop"
Select permissions: Choose [read] [write] or both
Copy Key: Save the key securely—it will only be shown once

Key Properties

Format: kb_ prefix + 64 hex characters (e.g., kb_a1b2c3d4...)
Scopes: Read and/or write access to memories, connectors, and search
Expiration: Keys do not expire by default (rotate manually)
Rate Limits: 100 requests per minute per key

Claude Desktop Setup

Configure Claude Desktop to connect to Kybernesis Brain via MCP.

Locate Configuration File

Claude Desktop stores MCP server configurations in a JSON file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Edit Configuration

Open the file in a text editor and add the Kybernesis MCP server:

terminal

{
  "mcpServers": {
    "kybernesis-brain": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.kybernesis.ai/mcp",
        "--header",
        "Authorization:${KYBERNESIS_AUTH}",
        "--transport",
        "http-only"
      ],
      "env": {
        "KYBERNESIS_AUTH": "Bearer kb_your_api_key_here"
      }
    }
  }
}

Replace placeholders:

kb_your_api_key_here: API key from previous step (includes kb_ prefix)

Configuration Notes:

--header: Passes authentication header to mcp-remote (required)
--transport http-only: Uses HTTP-only transport (skips OAuth attempts)
${KYBERNESIS_AUTH}: Environment variable substitution for the Bearer token

Alternative: Local Development Setup

For developers running the MCP server locally:

terminal

{
  "mcpServers": {
    "kybernesis-local": {
      "command": "node",
      "args": ["/absolute/path/to/kybernesis-brain/apps/mcp/dist/server.js"],
      "env": {
        "KYBERNESIS_API_KEY": "kb_your_api_key_here",
        "KYBERNESIS_BASE_URL": "https://api.kybernesis.ai",
        "KYBERNESIS_ORG_ID": "your-org-id-here"
      }
    }
  }
}

Prerequisites for local setup:

Clone repository: git clone https://github.com/ianborders/kybernesis-brain.git
Install dependencies: cd kybernesis-brain && npm install
Build MCP server: npm --workspace apps/mcp run build
Use absolute path to dist/server.js in configuration

Restart Claude Desktop

After saving the configuration:

Quit Claude Desktop completely (Cmd+Q on macOS, Alt+F4 on Windows)
Reopen Claude Desktop
Verify Connection: Type "What MCP servers are available?" in a new chat

You should see "kybernesis" listed with available tools.

Available MCP Tools

The Kybernesis MCP server exposes five tools for AI agents:

1. `kybernesis_add_memory`

Store a new memory in Kybernesis.

Input Schema:

terminal

{
  orgId: string;         // Organization ID (required)
  content: string;       // Memory content (required)
  title?: string;        // Optional title (defaults to first 80 chars)
  tags?: string[];       // Optional manual tags
  source?: string;       // Source identifier (defaults to "mcp")
  metadata?: object;     // Arbitrary metadata
}

Example Usage:

terminal

Claude, please remember that our API rate limit is 100 requests/minute and log this to Kybernesis.

Claude will use kybernesis_add_memory to store this information.

Response:

terminal

{
  "memoryId": "550e8400-e29b-41d4-a716-446655440000",
  "chunkId": "660e8400-e29b-41d4-a716-446655440001",
  "status": "stored"
}

2. `kybernesis_search_memory`

Search memories using hybrid vector + metadata search.

Input Schema:

terminal

{
  orgId: string;         // Organization ID (required)
  query: string;         // Search query (required)
  limit?: number;        // Max results (default: 10, max: 50)
}

Example Usage:

terminal

Claude, search my Kybernesis memories for "authentication flow design decisions".

Claude will use kybernesis_search_memory to find relevant memories.

Response:

terminal

{
  "results": [
    {
      "memoryId": "550e8400-e29b-41d4-a716-446655440000",
      "title": "OAuth 2.0 Authentication Architecture",
      "summary": "Decided to use refresh token rotation with 7-day expiry...",
      "score": 0.92,
      "tags": ["authentication", "oauth", "security"],
      "createdAt": "2025-10-15T14:30:00Z"
    }
  ]
}

3. `kybernesis_list_memories`

List all memories with pagination.

Input Schema:

terminal

{
  orgId: string;         // Organization ID (required)
  limit?: number;        // Page size (default: 20, max: 50)
  offset?: number;       // Skip N results (default: 0)
}

Example Usage:

terminal

Claude, list my 10 most recent memories from Kybernesis.

Response:

terminal

{
  "memories": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Project Architecture Decisions",
      "summary": "Microservices with event-driven communication...",
      "tags": ["architecture", "design"],
      "createdAt": "2025-10-20T10:15:00Z"
    }
  ],
  "total": 156,
  "hasMore": true
}

4. `kybernesis_list_connectors`

List configured data connectors (Google Drive, Notion, etc.).

Input Schema:

terminal

{
  orgId: string;         // Organization ID (required)
}

Example Usage:

terminal

Claude, what connectors do I have set up in Kybernesis?

Response:

terminal

{
  "connectors": [
    {
      "id": "conn_google_drive_001",
      "type": "google_drive",
      "displayName": "Google Drive",
      "status": "connected",
      "lastSyncedAt": "2025-10-24T08:00:00Z"
    },
    {
      "id": "conn_notion_001",
      "type": "notion",
      "displayName": "Engineering Wiki",
      "status": "connected",
      "lastSyncedAt": "2025-10-24T09:30:00Z"
    }
  ]
}

5. `kybernesis_sync_connector`

Trigger a manual sync for a specific connector.

Input Schema:

terminal

{
  orgId: string;         // Organization ID (required)
  connectorId: string;   // Connector ID (required)
}

Example Usage:

terminal

Claude, sync my Google Drive connector in Kybernesis to pick up the latest documents.

Response:

terminal

{
  "connectorId": "conn_google_drive_001",
  "status": "queued",
  "message": "Sync job enqueued. New documents will be available within 5-10 minutes."
}

Testing the Integration

Verify the MCP integration is working correctly.

1. Check Server Discovery

In Claude Desktop, type:

terminal

What MCP tools are available from Kybernesis?

Expected response:

terminal

I can see the following Kybernesis tools:
- kybernesis_add_memory: Store new memories
- kybernesis_search_memory: Search existing memories
- kybernesis_list_memories: List all memories with pagination
- kybernesis_list_connectors: View configured connectors
- kybernesis_sync_connector: Trigger connector sync

2. Test Memory Storage

terminal

Claude, remember that our production database URL is postgres://prod.db.kybernesis.ai:5432 and store this in Kybernesis.

Claude should use kybernesis_add_memory and confirm:

terminal

I've stored that information in your Kybernesis memory. The production database URL has been saved with the tag "database".

3. Test Memory Retrieval

terminal

Claude, what's the production database URL? Check Kybernesis.

Claude should use kybernesis_search_memory and return:

terminal

According to your Kybernesis memories, the production database URL is postgres://prod.db.kybernesis.ai:5432.

4. Test Connector Operations

terminal

Claude, list my Kybernesis connectors and sync the Google Drive one.

Claude should use kybernesis_list_connectors followed by kybernesis_sync_connector.

Troubleshooting

Common issues and solutions.

MCP Server Not Appearing

Symptoms: Claude Desktop doesn't show "kybernesis" in available servers.

Solutions:

Check Configuration Path: Ensure JSON file is in correct location for your OS
Validate JSON Syntax: Use a JSON validator—missing commas or brackets break parsing
Restart Completely: Quit and reopen Claude Desktop (force quit if necessary)
Check Logs: View Claude Desktop logs at ~/Library/Logs/Claude/ (macOS) or %APPDATA%\Claude\logs\ (Windows)

Authentication Failures

Symptoms: "Unauthorized" or "Invalid API key" errors.

Solutions:

Verify API Key: Check key is correctly copied (no extra spaces/newlines)
Check Org ID: Ensure organization ID matches your account
Key Expiration: API keys don't expire, but can be manually revoked—regenerate if needed
Network Issues: Test connectivity: curl https://api.kybernesis.ai/health

MCP Tools Failing Silently

Symptoms: Claude acknowledges but doesn't execute MCP calls.

Solutions:

Check Required Fields: Ensure orgId is provided in all tool calls
Test Direct API: Verify API endpoint works: curl https://api.kybernesis.ai/mcp
Review Payload Size: Content over 100KB may fail—chunk large memories
Check Rate Limits: 100 requests/minute—wait if hitting limit

Search Returns No Results

Symptoms: searchMemory returns empty array despite having memories.

Solutions:

Wait for Indexing: New memories take 5-30 seconds to index in Chroma
Check Org ID: Ensure searching correct organization
Broaden Query: Use more general terms—"auth" instead of "OAuth 2.0 PKCE flow"
Verify Memories Exist: Use listMemories to confirm data is present

Local MCP Server Won't Start

Symptoms: Claude Desktop shows "kybernesis" server as "disconnected".

Solutions:

Install Dependencies: Run npm install in /apps/mcp directory
Build MCP Server: Run npm run build in /apps/mcp
Check Node Version: Requires Node 20.17.0+ (verify with node --version)
Use Absolute Path: Configuration args must use full path, not relative

Security Best Practices

Protect your Kybernesis API keys and data.

Key Management

Never Commit Keys: Don't store API keys in Git repositories
Use Environment Variables: Store in env files excluded by .gitignore
Rotate Regularly: Generate new keys every 90 days
Revoke Compromised Keys: Immediately revoke if exposed (via web console)
Unique Keys Per Client: Use separate keys for different agents/machines

Access Control

Principle of Least Privilege: MCP keys have full access—only share with trusted agents
Monitor Usage: Review API access logs in web console regularly
Network Restrictions: Use firewall rules to limit which IPs can access API
Audit Logs: Track which memories were accessed by which API key

Data Privacy

Sensitive Information: Be cautious storing passwords, tokens, or PII in memories
Tag Sensitive Memories: Use special tags for memories requiring extra care
Regular Cleanup: Archive or delete outdated sensitive memories
Encryption at Rest: All memories encrypted in Convex and Chroma storage

Rate Limiting

Respect Limits: 100 requests/minute per key—design agents accordingly
Exponential Backoff: Retry failed requests with increasing delays
Batch Operations: Use listMemories with pagination instead of many individual calls
Cache Results: Store search results temporarily to avoid redundant queries

Example Workflows

Real-world scenarios using MCP integration.

Workflow 1: Project Knowledge Assistant

Scenario: AI assistant that remembers project decisions, patterns, and context.

Setup:

Connect Claude Desktop via MCP

During code reviews, ask Claude to remember key decisions:

terminal

Claude, remember that we're using event sourcing for the order service, not CRUD. Store this in Kybernesis.

When starting new features, Claude retrieves context:

terminal

Claude, what's our pattern for service communication? Check Kybernesis.

Claude searches memories and finds: "Use event-driven architecture with RabbitMQ for async communication..."

Benefits:

New team members ask Claude for architectural context
Decisions persist across conversation sessions
Agent suggests patterns consistent with past decisions

Workflow 2: Document Sync Agent

Scenario: Automatically sync Google Drive documents into Kybernesis for searchable knowledge base.

Setup:

Connect Google Drive connector via web console OAuth flow

Configure Claude to sync weekly:

terminal

Claude, please sync my Google Drive connector in Kybernesis every Monday at 9 AM.

Claude uses listConnectors to find Google Drive connector ID
Claude calls syncConnector on schedule
New docs from Drive are automatically chunked, embedded, and searchable

Benefits:

Documentation stays current without manual uploads
Search across Google Docs, Slides, Sheets in natural language
Connector status monitoring via MCP

Workflow 3: Meeting Notes Repository

Scenario: AI agent stores meeting summaries and retrieves action items.

Setup:

After meetings, paste transcript to Claude:

terminal

Claude, here's the transcript from today's sprint planning. Extract key decisions and action items, then store in Kybernesis.

Claude parses transcript, creates structured memory:

terminal

Storing meeting memory with tags: sprint-planning, 2025-q4, team-alpha
- Decision: Move to biweekly releases
- Action: @john Set up CI/CD pipeline by Nov 1
- Action: @sarah Draft security audit checklist

Before next meeting, retrieve context:

terminal

Claude, what were the action items from last sprint planning? Check Kybernesis.

Claude searches and returns structured summary

Benefits:

Meeting context persists across sessions
Searchable by attendee, topic, or date
Automatic action item tracking

Workflow 4: Cross-Source Research

Scenario: AI assistant searches across uploaded papers, Notion docs, and chat history.

Setup:

Upload research PDFs via web console
Connect Notion workspace with lab notes
Chat with Claude about experiments—memories auto-stored

Ask unified questions:

terminal

Claude, search all my Kybernesis memories for "transformer attention mechanisms" and summarize findings.

Claude uses searchMemory to query across:
- Uploaded papers (PDF → markdown → embeddings)
- Notion lab notes (synced via connector)
- Previous conversations (stored via MCP)

Benefits:

Single search surface for all knowledge sources
Hybrid search combines vector similarity with metadata filters
Relationship graph links related findings

Workflow 5: Debugging Context Preservation

Scenario: AI coding assistant remembers bugs, fixes, and root causes across debugging sessions.

Setup:

When encountering a bug, ask Claude to investigate

Claude searches Kybernesis for similar past issues:

terminal

Claude, search my memories for "database connection timeout" issues.

Finds previous memory: "Fixed connection pool exhaustion by increasing max connections from 10 to 50 in production config"

Claude applies same fix and stores new context:

terminal

Storing debug resolution: Connection timeouts resolved by connection pool tuning. Related to memory [previous-bug-id].

Next time similar issue occurs, Claude immediately suggests proven solution

Benefits:

Tribal knowledge captured automatically
Debugging patterns emerge from memory graph
Faster resolution times for recurring issues

Next Steps

Explore UI: Visit web console to visualize memory topology and relationships
Review Docs: Read API Reference for programmatic access
Configure Connectors: Set up Google Drive and Notion connectors
Optimize Search: Learn about hybrid retrieval strategies

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@kybernesis.ai

MCP Integration Guide

Table of Contents

What is MCP?

Why Integrate with AI Agents?

Prerequisites

Generate an API Key

Step-by-Step Key Generation

Key Properties

Claude Desktop Setup

Locate Configuration File

Edit Configuration

Alternative: Local Development Setup

Restart Claude Desktop

Available MCP Tools

1. kybernesis_add_memory

2. kybernesis_search_memory

3. kybernesis_list_memories

4. kybernesis_list_connectors

5. kybernesis_sync_connector

Testing the Integration

1. Check Server Discovery

2. Test Memory Storage

3. Test Memory Retrieval

4. Test Connector Operations

Troubleshooting

MCP Server Not Appearing

Authentication Failures

MCP Tools Failing Silently

Search Returns No Results

Local MCP Server Won't Start

Security Best Practices

Key Management

Access Control

Data Privacy

Rate Limiting

Example Workflows

Workflow 1: Project Knowledge Assistant

Workflow 2: Document Sync Agent

Workflow 3: Meeting Notes Repository

Workflow 4: Cross-Source Research

Workflow 5: Debugging Context Preservation

Next Steps

Support

1. `kybernesis_add_memory`

2. `kybernesis_search_memory`

3. `kybernesis_list_memories`

4. `kybernesis_list_connectors`

5. `kybernesis_sync_connector`