Troubleshooting Guide

Symptoms

• Claude says "Stompy tools not available"
• SSE connection fails
• No Stompy tools appear in Claude Desktop

Why this happens

Claude Desktop cannot find or connect to the Stompy MCP server. This is usually a setup issue.

Solution

Example

// Option 1: Custom Connector (recommended)
// Claude Desktop → Settings → Integrations → Add Custom MCP Server
// Enter: https://mcp.stompy.ai → Sign in

// Option 2: Manual config
{
  "mcpServers": {
    "stompy": {
      "url": "https://mcp.stompy.ai/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Symptoms

• Claude Desktop shows config error on startup
• MCP servers fail to load
• JSON parse error in logs

Why this happens

The claude_desktop_config.json file contains invalid JSON syntax such as trailing commas, missing quotes, or mismatched brackets.

Solution

Example

// WRONG - has trailing comma
{
  "mcpServers": {
    "stompy": {
      "url": "https://mcp.stompy.ai/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer token",  // <- Remove this comma!
      }
    }
  }
}

// CORRECT
{
  "mcpServers": {
    "stompy": {
      "url": "https://mcp.stompy.ai/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Symptoms

• Connection to Stompy server failed
• SSE endpoint unreachable
• Network error when connecting

Why this happens

The SSE connection to Stompy servers cannot be established. This may be due to network issues, firewall restrictions, or server maintenance.

Solution

Example

{
  "mcpServers": {
    "stompy": {
      "url": "https://mcp.stompy.ai/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Symptoms

• Unauthorized error when using Stompy tools
• Token expired or invalid
• Authentication failed
• 401 or 403 errors

Why this happens

Your Stompy bearer token is missing, expired, or incorrectly configured in the Authorization header.

Solution

Symptoms

• New user, tools not working
• Unsure if setup is correct
• Want to verify installation

Why this happens

First-time setup requires several steps to be completed in the correct order.

Solution

Example

// Custom Connector (recommended - no config files!)
// Claude Desktop → Settings → Integrations
// → Add Custom MCP Server → https://mcp.stompy.ai

// Or manual config:
{
  "mcpServers": {
    "stompy": {
      "url": "https://mcp.stompy.ai/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Symptoms

• One MCP server works but not others
• Tools from different servers mixed up
• Intermittent connection issues

Why this happens

When running multiple MCP servers, they may have conflicting tool names or resource contention.

Solution

Symptoms

• Unsure where to add bearer token
• Token not being recognized
• Need to configure authentication

Why this happens

Stompy uses bearer token authentication in the HTTP headers of the SSE connection.

Solution

Symptoms

• Features not working as documented
• Unexpected tool behavior
• New parameters or options available

Why this happens

Stompy is a hosted service that receives regular updates. New features or changes may affect tool behavior.

Solution

Symptoms

• recall_context returns "not found"
• Context exists but cannot be retrieved
• Topic name not recognized

Why this happens

The topic name does not exist, has a typo, or you are looking in the wrong project.

Solution

Example

// Find all contexts in a project
context_explore(project="my_project")

// Search for contexts about authentication
context_search("authentication")

// Recall with exact topic name
recall_context("auth-api-rules")

Symptoms

• lock_context fails with "novelty" error
• Content rejected as redundant
• "Delta evaluation: <10% novelty" message

Why this happens

Stompy prevents storing duplicate content. If your new context is more than 90% similar to existing contexts, it will be rejected to prevent clutter.

Solution

Example

// Check what similar content exists
context_search("API authentication rules")

// If updating, just lock with same topic (creates new version)
lock_context(
  content="Updated auth rules...",
  topic="auth-rules"  // Same topic = new version
)

// Force store if intentionally similar
lock_context(
  content="Similar but distinct content...",
  topic="auth-rules-v2",
  force_store=True
)

Symptoms

• Need older version of context
• Want to see version history
• Accidentally overwrote content

Why this happens

Contexts are versioned (1.0, 1.1, etc.) and you may need to access a specific version rather than the latest.

Solution

Example

// Get latest version
recall_context("api-spec")

// Get original version
recall_context("api-spec", version="1.0")

// Get specific version
recall_context("api-spec", version="1.2")

Symptoms

• Unsure which priority to use
• Context not appearing in searches
• Critical rules being missed

Why this happens

Stompy has three priority levels that affect how contexts are retrieved and displayed.

Solution

Example

// Critical security rule
lock_context(
  content="NEVER store passwords in plain text",
  topic="security-rules",
  priority="always_check"
)

// Important API documentation
lock_context(
  content="API uses JWT with 15min expiry...",
  topic="api-auth",
  priority="important"
)

// Reference material (default)
lock_context(
  content="Historical context about v1 API...",
  topic="api-v1-history"
  // priority defaults to "reference"
)

Symptoms

• context_search returns empty
• Know content exists but search fails
• Semantic search not finding matches

Why this happens

The search query may not semantically match your content, or you may be searching in the wrong project.

Solution

Example

// Broad semantic search
context_search("authentication")

// Search with tag filter
context_search("api", tags="security")

// Keyword-only search (no semantic)
context_search("JWT token", use_semantic=False)

// Search with priority filter
context_search("rules", priority="always_check")

Symptoms

• Search finds unexpected results
• Exact phrase not matching
• Want literal string matching

Why this happens

By default, context_search uses semantic search (meaning-based) not keyword matching. This finds conceptually related content but may miss exact phrases.

Solution

Example

// Semantic: finds related concepts
context_search("how users log in")
// Might find: "authentication", "JWT tokens", "session management"

// Keyword: exact matching
context_search("JWT", use_semantic=False)
// Only finds contexts containing "JWT"

// Combine with filters for precision
context_search("authentication", priority="important", tags="api")

Symptoms

• unlock_context fails for critical context
• "Requires force=True" error
• Cannot remove always_check priority context

Why this happens

Contexts with priority="always_check" are protected from accidental deletion. This is a safety feature for critical rules.

Solution

Example

// Protected by default - this fails:
unlock_context("security-rules")
// Error: Critical context requires force=True

// Override protection:
unlock_context("security-rules", force=True)
// Archived and deleted

// Alternative: downgrade priority
// (Update the context with lower priority instead)

Symptoms

• Confused about versions
• Want to understand update behavior
• Need to manage context history

Why this happens

Understanding how Stompy versions contexts helps you manage knowledge effectively.

Solution

Example

// Create initial version (v1.0)
lock_context(content="Initial API spec", topic="api-spec")

// Update creates v1.1 (v1.0 still exists)
lock_context(content="Updated API spec", topic="api-spec")

// Recall latest
recall_context("api-spec")  // Gets v1.1

// Recall original
recall_context("api-spec", version="1.0")  // Gets v1.0

// See all versions
db_query("SELECT version, created_at FROM context_locks WHERE label = 'api-spec'")

Symptoms

• ticket_board shows empty board
• ticket_search returns no results
• Ticket ID not recognized

Why this happens

Tickets are project-scoped. You may be looking in the wrong project, or no tickets have been created yet.

Solution

Example

// View board for a specific project
ticket_board(view="summary", project="my_project")

// Search tickets
ticket_search("authentication", project="my_project")

// Create a ticket
ticket(action="create", title="Add login page", priority="high", project="my_project")

Symptoms

• Unsure how to move tickets between columns
• Want to update ticket status
• Need to close a ticket

Why this happens

Tickets follow a status workflow. Understanding the available statuses helps manage your board.

Solution

Example

// Create a ticket (starts in backlog)
ticket(action="create", title="Implement OAuth", priority="high")

// Start working on it
ticket(action="update", ticket_id="TKT-1", status="in_progress")

// Mark as done
ticket(action="update", ticket_id="TKT-1", status="done")

// View the board
ticket_board(view="summary")

Symptoms

• Want to connect a ticket to stored knowledge
• Need to reference a context from a ticket
• ticket_link usage unclear

Why this happens

Tickets can be linked to contexts so Claude sees both your task board and the knowledge behind each task.

Solution

Example

// Link a ticket to a context
ticket_link(
  ticket_id="TKT-5",
  context_topic="api-architecture"
)

// View the ticket with its links
ticket(action="get", ticket_id="TKT-5")

Symptoms

• Want to upload a PDF or image
• Need to ingest a document into Stompy
• Looking for file upload functionality
• How to store files in a project

Why this happens

Document uploads (PDFs, images, code files) are handled through the Stompy web dashboard, not via MCP tools. The dashboard supports drag-and-drop with progress tracking.

Solution

Symptoms

• "Embedding generation failed" error
• Context stored but not searchable
• VoyageAI errors

Why this happens

Text embeddings are generated by VoyageAI. If the service is unavailable, contexts may be stored without embeddings.

Solution

Symptoms

• db_query rejects INSERT/UPDATE/DELETE
• "Write operation not allowed" error
• Need to modify data directly

Why this happens

db_query is read-only by design. Stompy only provides read-only database access to protect your data integrity. Use the dedicated tools (lock_context, unlock_context, ticket, etc.) for write operations.

Solution

Example

// Read operation - use db_query
db_query("SELECT label, priority FROM context_locks")

// Inspect table structure
db_schema(table="context_locks")

// For writes, use dedicated tools instead:
lock_context(content="Updated rules", topic="auth-rules")

Symptoms

• db_schema shows no tables
• Cannot see database structure
• Schema appears empty

Why this happens

You may be looking at the wrong project schema, or the project has not been initialized with any data yet.

Solution

Example

// List all tables in a project
db_schema(project="my_project")

// Get details for specific table
db_schema(table="context_locks")

// Query table structure directly
db_query("SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'context_locks'")

Symptoms

• Query takes too long
• Operation timed out
• Large result set issues

Why this happens

Complex queries or large result sets can exceed timeout limits. db_query auto-adds LIMIT 100 for safety.

Solution

Example

// Efficient: select specific columns with filter
db_query(
  "SELECT label, priority, version FROM context_locks WHERE priority = %s",
  params=["important"]
)

// Paginate large results
db_query("SELECT * FROM context_locks LIMIT 50")
db_query("SELECT * FROM context_locks LIMIT 50 OFFSET 50")

Symptoms

• Contexts from wrong project appearing
• Confused about project boundaries
• Want to understand data separation

Why this happens

Each Stompy project is a completely isolated PostgreSQL schema. Understanding this helps manage multiple projects effectively.

Solution

Example

// See all projects
project_list()

// Scope operations to a project via the project param
lock_context(content="Acme API spec", topic="api", project="client_acme")
// This context only exists in client_acme project

// Search a different project
context_search("auth", project="personal_blog")
// Cannot see client_acme contexts here

Symptoms

• Tool returns "project not found" error
• Cannot access project data
• Project name not recognized

Why this happens

The project name may be misspelled, not yet created, or you may need to use the exact name.

Solution

Example

// List available projects
project_list()

// Access a specific project
context_explore(project="my_project")

// Create if doesn't exist
project_create("new_project")

Symptoms

• Previous session context missing
• Handover shows empty
• "No handover available" message

Why this happens

Handover summaries are created at session end. If no previous session exists or it was empty, there may be no handover to load.

Solution

Symptoms

• project_delete fails
• "Requires confirmation" error
• Project deletion blocked

Why this happens

Project deletion is destructive and requires explicit confirmation to prevent accidental data loss.

Solution

Example

// First, review what will be deleted
project_info(project="old_project")
context_explore(project="old_project")

// Delete with explicit confirmation
project_delete("old_project", confirm=True)

// Verify deletion
project_list()

Symptoms

• Embedding generation fails
• Semantic search not working
• VoyageAI API errors

Why this happens

VoyageAI provides embeddings for semantic search. Service outages or rate limits can cause temporary failures.

Solution

Symptoms

• Image analysis fails
• No description generated for images
• Vision API timeout

Why this happens

OpenRouter provides AI vision for image analysis. This is optional - images work without it.

Solution

Symptoms

• Document upload fails
• S3 authentication error
• Cannot store files

Why this happens

Document storage requires S3/DigitalOcean Spaces credentials. This is typically configured server-side.

Solution

Symptoms

• context_search takes too long
• Search feels slow
• Timeout on large projects

Why this happens

Semantic search requires embedding comparison across all contexts. Large projects may take longer.

Solution

Example

// Fast: filtered search
context_search("api", priority="always_check", limit=3)

// Fast: keyword only
context_search("auth-rules", use_semantic=False)

// Slower: broad semantic search
context_search("how does authentication work")

Symptoms

• lock_context times out
• Large content fails to store
• Operation exceeds time limit

Why this happens

Very large contexts take longer to process (embedding generation, storage). Consider chunking or using lazy embedding.

Solution

Example

// Defer embedding for large content
lock_context(
  content="Very long technical specification...",
  topic="full-spec",
  lazy=True  // Embedding generated on first search
)

// Better: split into logical chunks
lock_context(content="Overview...", topic="spec-overview")
lock_context(content="API details...", topic="spec-api")
lock_context(content="Data models...", topic="spec-models")