MCP Tools Reference

Model Context Protocol (MCP) Integration Guide

The Model Context Protocol exposes Fold's memory system as composable tools for AI agents like Claude Code, Cursor, and Windsurf. This reference covers all available MCP tools and how to use them.

What is MCP?

MCP (Model Context Protocol) is a standard interface that lets AI agents interact with external systems. Think of it as a standardized toolkit making Fold's knowledge accessible to any AI tool.

Why MCP Matters

Traditional AI agents:

Read code files directly (slow, limited context)
Don't understand architectural decisions
Miss relationships between code and decisions
Can't learn from team patterns

With Fold + MCP, AI agents:

Query semantic memory (fast, rich context)
Understand why code was written
See relationships across your entire project
Apply consistent patterns automatically

Connecting Claude Code to Fold

Step 1: Create an API Token

In Fold's web UI:

Settings → API Tokens → Create Token
Name: "Claude Code"
Projects: Select your projects

Copy the token (shown only once).

Step 2: Configure Claude Code

Add Fold as an MCP server:

claude mcp add -t http -s user fold http://localhost:8765/mcp \
  --header "Authorization: Bearer fold_YOUR_TOKEN_HERE"

Or manually edit ~/.claude/settings.json:

{
  "mcpServers": {
    "fold": {
      "url": "http://localhost:8765/mcp",
      "headers": {
        "Authorization": "Bearer fold_YOUR_TOKEN_HERE"
      }
    }
  }
}

Step 3: Start Using

Ask Claude directly:

"Search for authentication patterns in my codebase"
"What's the decision about how we handle sessions?"
"Show me recent changes to the payment service"
"Add a new API endpoint following our patterns"

Claude will automatically use Fold tools to get the information.

Tool Categories

1. Project Management

Tools for discovering and accessing projects.

`project_list`

List all projects your token can access.

Parameters:

limit (optional, default: 50) - Max projects to return

Response Example:

{
  "projects": [
    {
      "id": "proj_abc123",
      "slug": "my-app",
      "name": "My Application",
      "description": "Main application",
      "created_at": "2026-01-15T10:00:00Z",
      "memory_counts": {
        "total": 5432,
        "by_type": {
          "codebase": 4800,
          "decision": 42,
          "session": 156,
          "spec": 25,
          "commit": 234,
          "other": 175
        }
      }
    }
  ]
}

Usage:

Claude: "What projects do you have?"

Returns: List of accessible projects with memory statistics.

`project_get`

Get detailed information about a specific project.

Parameters:

slug (required) - Project slug (e.g., "my-app")

Response Example:

{
  "id": "proj_abc123",
  "slug": "my-app",
  "name": "My Application",
  "description": "Main application",
  "created_at": "2026-01-15T10:00:00Z",
  "stats": {
    "total_memories": 5432,
    "last_activity": "2026-02-03T14:22:00Z",
    "repositories": 3,
    "languages": {
      "typescript": 2100,
      "rust": 1200,
      "python": 850
    }
  }
}

Usage:

Claude: "Tell me about the my-app project"

Returns: Project details and statistics.

2. Memory Management

Tools for creating, retrieving, and managing memories.

`memory_add`

Create a new memory.

Parameters:

project (required) - Project slug
content (required) - Memory content (markdown)
source (optional, default: "Agent") - File, Agent, or Git
type (optional, default: "general") - codebase, session, spec, decision, commit, pr, task, general
title (optional) - Human-readable title (auto-generated if omitted)
keywords (optional) - Key terms (max 15, auto-extracted if omitted)
tags (optional) - Category tags (max 6)
auto_metadata (optional, default: true) - Auto-analyse content

Response Example:

{
  "id": "aBcD123456789abc",
  "project_id": "proj_abc123",
  "title": "Refactored authentication flow",
  "type": "session",
  "source": "Agent",
  "content": "...",
  "keywords": ["auth", "refactoring", "jwt"],
  "tags": ["backend", "security"],
  "context": "Session notes on refactoring the authentication...",
  "created_at": "2026-02-03T10:30:00Z"
}

Usage:

# Claude internally calls this
memory = fold.memory_add(
  project="my-app",
  type="session",
  source="Agent",
  title="Fixed login timeout issue",
  content="Today we fixed the session timeout bug...",
  keywords=["sessions", "timeout", "auth"],
  tags=["bugfix", "backend"]
)

Returns: Created memory with ID and metadata.

`memory_list`

List memories in a project.

Parameters:

project (required) - Project slug
source (optional) - Filter by source (File, Agent, Git)
type (optional) - Filter by type
limit (optional, default: 50) - Max memories
sort (optional, default: "created_at") - Sort by: created_at, updated_at, relevance

Response Example:

{
  "memories": [
    {
      "id": "aBcD123456789abc",
      "title": "Authentication Service",
      "type": "codebase",
      "source": "File",
      "file_path": "src/auth/service.ts",
      "language": "typescript",
      "created_at": "2026-02-03T10:30:00Z"
    }
  ],
  "total": 5432,
  "limit": 50
}

Usage:

Claude: "Show me all decision memories in my-app"
→ memory_list(project="my-app", type="decision")

Returns: List of memories matching filters.

`memory_search`

Search memories using semantic similarity and optional decay weighting.

Parameters:

project (required) - Project slug
query (required) - Natural language search query
limit (optional, default: 10) - Max results
type (optional) - Filter by type
include_decay (optional, default: true) - Apply memory decay

Response Example:

{
  "results": [
    {
      "id": "aBcD123456789abc",
      "title": "Authentication Service",
      "type": "codebase",
      "source": "File",
      "relevance": 0.95,
      "decay_strength": 0.87,
      "combined_score": 0.92,
      "snippet": "Handles JWT validation and session management..."
    },
    {
      "id": "f0123456789abcde",
      "title": "Use JWT for authentication",
      "type": "decision",
      "source": "Agent",
      "relevance": 0.91,
      "decay_strength": 0.92,
      "combined_score": 0.91,
      "snippet": "We chose JWT because it is stateless and scalable..."
    }
  ],
  "total": 34
}

Usage:

Claude: "How do we handle authentication?"
→ memory_search(
    project="my-app",
    query="How do we handle authentication?"
  )

Returns: Semantically relevant memories ranked by combined score (semantic + decay).

`memory_get`

Get a specific memory by ID with full content.

Parameters:

project (required) - Project slug
memory_id (required) - Memory ID (16-char hash)

Response Example:

{
  "id": "aBcD123456789abc",
  "title": "Authentication Service",
  "type": "codebase",
  "source": "File",
  "file_path": "src/auth/service.ts",
  "language": "typescript",
  "keywords": ["auth", "jwt", "security"],
  "tags": ["auth", "typescript"],
  "context": "Implements JWT-based authentication...",
  "content": "Full markdown content of memory...",
  "created_at": "2026-02-03T10:30:00Z",
  "retrieval_count": 47
}

Usage:

Claude: "Show me memory aBcD123456789abc"
→ memory_get(project="my-app", memory_id="aBcD123456789abc")

Returns: Complete memory with content and metadata.

`memory_context`

Get holographic context around a memory (related memories, graph relationships).

Parameters:

project (required) - Project slug
memory_id (required) - Memory ID
depth (optional, default: 2) - How deep to traverse relationships (1-3)

Response Example:

{
  "memory": {
    "id": "aBcD123456789abc",
    "title": "Authentication Service",
    "type": "codebase",
    "content": "..."
  },
  "related_memories": [
    {
      "id": "f0123456789abcde",
      "title": "Use JWT for authentication",
      "type": "decision",
      "link_type": "Related",
      "relevance": 0.92
    },
    {
      "id": "9a8b7c6d5e4f3g2h",
      "title": "Session Timeout Policy",
      "type": "decision",
      "link_type": "Related",
      "relevance": 0.87
    }
  ],
  "similar_memories": [
    {
      "id": "c1234d5678e9f0g1",
      "title": "OAuth Integration",
      "type": "codebase",
      "relevance": 0.81
    }
  ],
  "depth_traversed": 2
}

Usage:

Claude: "What context exists around the auth service?"
→ memory_context(
    project="my-app",
    memory_id="aBcD123456789abc",
    depth=2
  )

Returns: Memory with related memories from the knowledge graph.

3. Memory Links

Tools for managing relationships between memories.

`memory_link_add`

Create a link between two memories.

Parameters:

project (required) - Project slug
source_id (required) - Source memory ID
target_id (required) - Target memory ID
link_type (required) - Related, References, DependsOn, or Modifies
context (optional) - Additional metadata about the link

Response Example:

{
  "id": "link_123",
  "source_id": "aBcD123456789abc",
  "target_id": "f0123456789abcde",
  "link_type": "References",
  "created_at": "2026-02-03T10:30:00Z"
}

Usage:

# Create link between two memories
link = fold.memory_link_add(
  project="my-app",
  source_id="aBcD123456789abc",
  target_id="f0123456789abcde",
  link_type="References"
)

Returns: Created link object.

`memory_link_list`

List all links connected to a memory.

Parameters:

project (required) - Project slug
memory_id (required) - Memory ID

Response Example:

{
  "links": [
    {
      "id": "link_123",
      "source_id": "aBcD123456789abc",
      "target_id": "f0123456789abcde",
      "link_type": "References",
      "source_title": "Session timeout decision",
      "target_title": "Fix timeout bug"
    },
    {
      "id": "link_124",
      "source_id": "9a8b7c6d5e4f3g2h",
      "target_id": "aBcD123456789abc",
      "link_type": "Related",
      "source_title": "Authentication service",
      "target_title": "Session timeout decision"
    }
  ],
  "total": 2
}

Usage:

Claude: "What's linked to the session timeout decision?"
→ memory_link_list(project="my-app", memory_id="aBcD123456789abc")

Returns: List of all links connected to the memory.

4. Codebase Operations

Tools for indexing and searching codebase.

`codebase_index`

Trigger full reindexing of a project's repositories.

Parameters:

project (required) - Project slug

Response Example:

{
  "job_id": "job_abc123",
  "status": "queued",
  "message": "Full reindex queued",
  "repositories": 3,
  "estimated_files": 2450
}

Usage:

Claude: "Re-index my-app codebase"
→ codebase_index(project="my-app")

Returns: Job ID for tracking reindexing progress.

`codebase_search`

Search codebase by keywords and patterns.

Parameters:

project (required) - Project slug
query (required) - Search query (keywords, patterns, or semantic)
limit (optional, default: 10) - Max results
language (optional) - Filter by language

Response Example:

{
  "results": [
    {
      "id": "aBcD123456789abc",
      "title": "Authentication Service",
      "type": "codebase",
      "file_path": "src/auth/service.ts",
      "language": "typescript",
      "relevance": 0.95,
      "snippet": "pub fn validate_token(token: &str) -> Result<Claims>"
    },
    {
      "id": "f0123456789abcde",
      "title": "Middleware",
      "type": "codebase",
      "file_path": "src/middleware/jwt.rs",
      "language": "rust",
      "relevance": 0.89,
      "snippet": "Check JWT token in Authorization header"
    }
  ],
  "total": 15
}

Usage:

Claude: "Show me authentication patterns in the codebase"
→ codebase_search(
    project="my-app",
    query="authentication patterns"
  )

Returns: Code memories matching search with snippets.

5. File Operations

Tools for uploading and managing files.

`files_upload`

Upload one or more files to be indexed as memories.

Parameters:

project (required) - Project slug
files (required) - Array of files to upload
- path (required) - File path (e.g., "src/auth.ts")
- content (required) - File content
- language (optional) - Programming language
author (optional) - Author name or ID

Response Example:

{
  "uploaded": 3,
  "memories": [
    {
      "id": "aBcD123456789abc",
      "title": "Authentication Service",
      "type": "codebase",
      "file_path": "src/auth/service.ts"
    },
    {
      "id": "f0123456789abcde",
      "title": "JWT Middleware",
      "type": "codebase",
      "file_path": "src/middleware/jwt.rs"
    },
    {
      "id": "9a8b7c6d5e4f3g2h",
      "title": "Auth Routes",
      "type": "codebase",
      "file_path": "src/routes/auth.rs"
    }
  ]
}

Usage:

# Upload new files as memories
fold.files_upload(
  project="my-app",
  files=[
    {
      "path": "src/auth/service.ts",
      "content": "...",
      "language": "typescript"
    }
  ],
  author="claude"
)

Returns: List of created memories for uploaded files.

Common Workflows

1. Search and Get Context

Get comprehensive information about a topic:

Claude: "How do we validate JWTs?"

Internally:
1. memory_search(project, "validate JWTs")
   → Gets auth service code
2. memory_context(project, auth_service_id)
   → Gets related decisions, patterns
3. Returns: Complete understanding

2. Find Related Implementations

Find similar code patterns:

Claude: "Show me how we handle timeouts elsewhere"

Internally:
1. memory_search(project, "timeout handling")
2. memory_link_list(project, each_result)
   → Gets all related patterns
3. Returns: All timeout implementations

3. Build on Patterns

Create new code following existing patterns:

Claude: "Add a new API endpoint following our patterns"

Internally:
1. memory_search(project, "API endpoint patterns")
2. memory_context(project, endpoint_memory)
   → Gets architecture, conventions, decisions
3. Generates: Code matching your patterns

4. Document Decisions

Record important decisions:

Claude: "Document the decision to use Redis for caching"

Internally:
1. memory_add(project, type="decision", content=...)
2. memory_search(project, "related caching")
3. memory_link_add(project, decision, ...)
   → Links to related code/sessions
4. Returns: Decision documented and linked

Error Handling

MCP tools return structured errors:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Memory not found",
    "details": {
      "memory_id": "xyz123"
    }
  }
}

Common Errors:

Code	Meaning	Solution
`PROJECT_NOT_FOUND`	Project doesn't exist	Check project slug
`MEMORY_NOT_FOUND`	Memory doesn't exist	Check memory ID
`INVALID_TOKEN`	Token expired or invalid	Regenerate API token
`RATE_LIMITED`	Too many requests	Retry after delay
`SERVICE_UNAVAILABLE`	Fold server down	Check server status

Tips for Best Results

1. Use Specific Queries

Bad: "show me auth stuff" Good: "How do we validate JWT tokens in our API?"

2. Use Types to Filter

When searching, specify memory types:

type="codebase" - Find implementations
type="decision" - Find architectural choices
type="spec" - Find requirements
type="session" - Find notes and discussions

3. Increase Context Depth for Complex Topics

memory_context(project, id, depth=3)

Use depth=3 for complex features with many relationships.

4. Create Session Notes After Work

memory_add(
  project,
  type="session",
  title="Implemented payment processing",
  content="Today we added Stripe integration..."
)

This helps future searches find what you did and why.

5. Link Important Relationships

memory_link_add(
  project,
  source=implementation_id,
  target=decision_id,
  link_type="References"
)

This helps the knowledge graph stay organized.

Advanced: MCP Protocol Details

If you're implementing a custom MCP client:

Request Format

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "tools/call",
  "params": {
    "name": "memory_search",
    "arguments": {
      "project": "my-app",
      "query": "authentication"
    }
  }
}

Response Format

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    "type": "text",
    "text": "JSON results or markdown summary"
  }
}

Streaming Responses

For large results, responses may be streamed:

GET /mcp/sse
Authorization: Bearer token

Receives Server-Sent Events with result chunks.

Troubleshooting

"Memory not found" errors

Memories are created asynchronously. Wait a moment after creating before searching:

memory = fold.memory_add(...)
time.sleep(1)  # Wait for indexing
results = fold.memory_search(project, query)

"Permission denied" errors

Token doesn't have access to this project. Create a new token with the correct projects selected.

Search returns no results

Try:

Search with simpler, more direct terms
Use memory_list() to browse what exists
Check repository is connected and indexed
Use codebase_index(project) to force reindex

Rate limiting

Fold limits API calls per token. Retry after the Retry-After header duration.

MCP Tools Reference

MCP Tools Reference

What is MCP?

Why MCP Matters

Connecting Claude Code to Fold

Step 1: Create an API Token

Step 2: Configure Claude Code

Step 3: Start Using

Tool Categories

1. Project Management

project_list

project_get

2. Memory Management

memory_add

memory_list

memory_search

memory_get

memory_context

3. Memory Links

memory_link_add

memory_link_list

4. Codebase Operations

codebase_index

codebase_search

5. File Operations

files_upload

Common Workflows

1. Search and Get Context

2. Find Related Implementations

3. Build on Patterns

4. Document Decisions

Error Handling

Tips for Best Results

1. Use Specific Queries

2. Use Types to Filter

3. Increase Context Depth for Complex Topics

4. Create Session Notes After Work

5. Link Important Relationships

Advanced: MCP Protocol Details

Request Format

Response Format

Streaming Responses

Troubleshooting

"Memory not found" errors

"Permission denied" errors

Search returns no results

Rate limiting

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

`project_list`

`project_get`

`memory_add`

`memory_list`

`memory_search`

`memory_get`

`memory_context`

`memory_link_add`

`memory_link_list`

`codebase_index`

`codebase_search`

`files_upload`