MCP Advanced

Troubleshooting

Common issues and solutions when working with the Trix MCP server.

Server Not Connecting

If the MCP server is not connecting to your AI assistant:

• Verify your API key is correct and starts with gdb_
• Ensure the configuration file path is correct for your operating system
• Restart your AI assistant after making configuration changes
• Check that Node.js and npm/npx are properly installed

# Verify npx works
npx --version

# Test the MCP server directly with debug logging
TRIX_LOG_LEVEL=debug npx @trix/mcp

# Check for npm issues
npm cache clean --force

Tools Not Appearing

If the Trix tools don't appear in your AI assistant:

• Check that the MCP server is properly configured in your client's settings
• Verify npx can run by testing npx @trix/mcp
• Look for error messages in your client's developer console or logs
• Ensure the -y flag is included in the args to auto-accept npm prompts

Authentication Errors

If you're seeing authentication errors:

• Confirm your API key has not expired
• Check that the key starts with gdb_
• Ensure there are no extra spaces or characters in the key
• Verify the Authorization: Bearer gdb_... header is set correctly in your client config
• Check that the MCP server can reach the Trix API to validate the key

Slow Responses

If memory operations are slow:

• Check your network connection
• Consider using a default space to reduce query scope
• Reduce the limit parameter when searching
• Use more specific queries for better performance

Logging and Debugging

Enable verbose logging to debug issues with the MCP server.

# Start the server with debug logging
TRIX_LOG_LEVEL=debug npx @trix/mcp

Then configure your client to connect via HTTP:

{
  "mcpServers": {
    "trix": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer gdb_your_api_key"
      }
    }
  }
}

Log levels available:

• error - Only errors
• warn - Warnings and errors
• info - General information (default)
• debug - Detailed debugging information

Advanced Configuration

Using Multiple Spaces

The Trix MCP server is multi-tenant — you don't need separate server instances for different spaces. A single server handles all your spaces. Spaces are specified per-tool-call via the space_id parameter, so your AI assistant can read from and write to any space within the same session.

{
  "mcpServers": {
    "trix": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer gdb_your_api_key"
      }
    }
  }
}

Custom API Endpoint

For self-hosted or enterprise deployments, start the MCP server with a custom Trix API URL using the TRIX_API_URL environment variable:

# Point the MCP server at your own Trix API instance
TRIX_API_URL=https://your-instance.com npx @trix/mcp

Clients still connect to the MCP server the same way:

{
  "mcpServers": {
    "trix": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer gdb_your_api_key"
      }
    }
  }
}

Session Tracking

The MCP server manages sessions automatically. When a client connects, the server assigns a session ID returned via the mcp-session-id response header. Clients include this header in subsequent requests to maintain session continuity.

Session lifetime is controlled by two server-side environment variables:

• SESSION_TTL - Maximum session duration in seconds (default: 3600)
• SESSION_INACTIVITY_DAYS - Days of inactivity before session cleanup (default: 30)

Best Practices

Memory Organization

• Use spaces - Separate work, personal, and project-specific memories into different spaces
• Tag consistently - Use consistent tags to make filtering easier (e.g., always use "preference" for user preferences)
• Be specific - Store specific, actionable information rather than vague notes
• Update regularly - When information changes, update or remove outdated memories

Security

• Protect your API key - Never share your API key or commit it to version control
• Use separate keys - Create separate API keys for different applications or environments
• Review stored memories - Periodically review what's being stored to ensure no sensitive information is saved inadvertently
• Revoke compromised keys - If you suspect a key has been compromised, revoke it immediately

Performance

• Limit query scope - Use specific spaces and tags to narrow down searches
• Set reasonable limits - Don't request more memories than you need
• Use threshold filtering - Set a minimum similarity threshold to filter out irrelevant results

Client-Specific Tips

Claude Desktop

• Claude will automatically use Trix tools when you ask it to remember or recall information
• You can see which tools Claude is using in the response
• For complex queries, Claude may combine multiple Trix tools

Cursor

• Memories can include code snippets and technical context
• Use the MCP server to remember project-specific conventions
• Store frequently referenced documentation or patterns

Windsurf

• Configure per-project spaces to keep context separate
• Use sessions to track different feature branches or work streams

Common Patterns

Building Context Over Time

Let the AI assistant learn about you naturally through conversations:

• Start by telling it your preferences and working style
• Correct it when it makes assumptions that don't match your needs
• Ask it to remember important decisions or context
• Periodically review and clean up outdated memories

Project-Specific Memory

Use separate spaces to isolate memories for different projects. Since the MCP server is multi-tenant, you use a single API key and a single server instance. Each tool call specifies a space_id to target the right project's memories.

// Your AI assistant targets the right space per tool call:
// store_memory({ space_id: "project-a", content: "..." })
// search_memories({ space_id: "project-b", query: "..." })

Team Memory

Share a space among team members for collective knowledge:

• Create a shared space for team conventions and decisions
• Each team member uses the same space configuration
• AI assistants can access team knowledge when helping any member
• Regular cleanup prevents outdated information from persisting

Next Steps

• Daemon - Run Trix as a background service for offline access
• Integrations - Connect Trix to other services
• Best Practices - Expert tips for memory management