Troubleshooting Guide

This guide helps you diagnose and resolve common issues when using the Atlantis MCP Server.

Table of Contents

Connection Issues

Problem: Cannot Connect to MCP Server

Symptoms: - AI assistant reports connection failed - Timeout errors - “Server not responding” messages

Possible Causes:

  1. Incorrect URL
  2. Network Issues
  3. Server Downtime

Solutions:

# Test connection with curl
curl -X POST https://mcp.atlantis.63klabs.net/mcp/v1 \
  -H "Content-Type: application/json" \
  -d '{}'

# Expected: JSON response with categories

For Claude Desktop:

{
  "mcpServers": {
    "atlantis": {
      "url": "https://mcp.atlantis.63klabs.net/mcp/v1",
      "timeout": 30000
    }
  }
}

For Cursor/Kiro: - Verify settings.json syntax - Reload window after configuration changes - Check IDE logs for detailed errors

Rate Limiting

Problem: HTTP 429 - Too Many Requests

Symptoms: - “Rate limit exceeded” error - HTTP 429 status code - Requests blocked for 1 hour

Understanding Rate Limits:

Rate limits vary by tier. See the rate limits page for the full breakdown of request limits per tier.

Check Rate Limit Status:

Response headers show current status:

X-RateLimit-Limit: <your-tier-limit>
X-RateLimit-Remaining: <requests-remaining>
X-RateLimit-Reset: <unix-timestamp>

Solutions:

  1. Wait for Reset
  2. Reduce Request Frequency
  3. Self-Host for Higher Limits

Prevention:

Tool Errors

Problem: TEMPLATE_NOT_FOUND

Symptoms: - “Template ‘xyz’ not found” error - Empty results when expecting templates

Possible Causes:

  1. Incorrect Template Name
  2. Wrong Category
  3. Template Not in Configured Buckets

Solutions:

# List all templates to find correct name
Ask AI: "List all available templates"

# Search by category
Ask AI: "Show me all Pipeline templates"

# Check specific bucket
Ask AI: "List templates from bucket xyz"

Error Response Example:

{
  "error": {
    "code": "TEMPLATE_NOT_FOUND",
    "message": "Template 'template-pipline.yml' not found",
    "details": {
      "availableTemplates": [
        "template-pipeline.yml",
        "template-storage.yml"
      ]
    }
  }
}

Note the typo: “pipline” vs “pipeline”

Problem: INVALID_INPUT

Symptoms: - “Invalid input” error - JSON Schema validation failed - Missing required parameters

Common Causes:

  1. Missing Required Parameters

    # Wrong - missing category
Ask AI: "Get template-pipeline.yml"

# Correct
Ask AI: "Get template-pipeline.yml from Pipeline category"

  2. Invalid Parameter Types

    # Wrong - version should be string
version: 2.0.18

# Correct
version: "v2.0.18"

  3. Invalid Parameter Values

    # Wrong - invalid category
category: "Pipelines"

# Correct
category: "pipeline"

Solutions:

Problem: STARTER_NOT_FOUND

Symptoms: - “Starter ‘xyz’ not found” error - Empty results for get_starter_info

Possible Causes:

  1. Missing Sidecar Metadata
  2. Missing GitHub Custom Property
  3. Incorrect Starter Name

Solutions:

# List all starters to find correct name
Ask AI: "List all available starters"

# Check specific organization
Ask AI: "List starters from 63klabs"

For Self-Hosted: - Verify sidecar metadata files exist in S3 - Check GitHub custom properties are set - Review logs for warnings about skipped starters

Problem: DOCUMENT_NOT_FOUND

Symptoms: - “Document not found in storage” error from get_document or get_document_chunk - Error response includes a githubUrl field (possibly null)

Possible Causes:

  1. Not indexed yet — the file hasn’t been picked up by a documentation index build.
  2. Stale filePath/hash — the lookup key came from an older search result and the underlying entry has since been superseded or expired.

Solutions:

Performance Issues

Problem: Slow Response Times

Symptoms: - Requests take >10 seconds - Timeout errors - Inconsistent performance

Possible Causes:

  1. Large Result Sets
  2. Network Latency
  3. Cache Miss

Solutions:

  1. Use Filters

    # Slow - lists everything
Ask AI: "List all templates"

# Faster - filtered results
Ask AI: "List Pipeline templates"

  2. Increase Timeout

    {
  "mcpServers": {
    "atlantis": {
      "url": "https://mcp.atlantis.63klabs.net/mcp/v1",
      "timeout": 60000
    }
  }
}

Performance Tips:

Authentication Problems

Problem: Authentication Required

Symptoms: - “Authentication required” error - HTTP 401 Unauthorized - Invalid credentials

Solutions:

If you see authentication errors:

  1. Verify URL

Problem: Forgot your password

If you can’t sign in because you’ve forgotten your password, use the self-service reset flow:

  1. Go to /forgot-password/ or click Forgot your password? on the login page.
  2. Enter the email address for your account and submit.
  3. Check your inbox for a reset code. If it doesn’t arrive within a few minutes, check your spam or junk folder.
  4. Enter the code and choose a new password that meets the policy requirements shown on the page.
  5. Once the reset succeeds, sign in at /login/ with your new password.

Note: If your account hasn’t been verified yet, you’ll be redirected to complete verification before you can reset your password.

Note: Resetting your password does not change your API key. Your existing API key continues to work after the reset. To regenerate your API key, use the Regenerate API Key button on your profile page after signing in.

Problem: Want to change your password while signed in

You can change your password from your profile page without going through the reset flow:

  1. Sign in and go to your profile page.
  2. Scroll to the Password section at the bottom of the page.
  3. Enter your current password, then enter and confirm your new password.
  4. Submit the form. You’ll stay signed in after the change.

Note: Changing your password does not affect your API key.

Data Quality Issues

Problem: Partial Data Returned

Symptoms: - partialData: true in response - errors array contains failures - Some buckets/orgs missing from results

Understanding Brown-Out Support:

The MCP server continues operation when some data sources fail: - Returns available data from working sources - Includes error information for failed sources - Logs detailed errors for troubleshooting

Example Response:

{
  "templates": [...],
  "partialData": true,
  "errors": [
    {
      "source": "bucket-xyz",
      "sourceType": "s3",
      "error": "Access denied",
      "timestamp": "2025-01-15T10:30:00Z"
    }
  ]
}

Possible Causes:

  1. S3 Bucket Access Issues
  2. GitHub API Issues
  3. Temporary Failures

Solutions:

  1. Review Error Details
  2. For Self-Hosted:
  3. Retry Request
  4. Contact Support

Problem: Stale Data

Symptoms: - Old template versions shown - Missing recent updates - Outdated documentation

Understanding Caching:

Data is cached for performance: - Template metadata: 24 hours - Starter metadata: 24 hours - Documentation index: 24 hours - Full template content: 24 hours

Solutions:

  1. Wait for Cache Expiration
  2. For Self-Hosted:
  3. Verify Source Data

Integration-Specific Issues

Claude Desktop

Problem: Configuration Not Loading

  1. Verify file location:

  2. Check JSON syntax:

    # Validate JSON
cat claude_desktop_config.json | python -m json.tool

  3. Restart Claude Desktop completely

Problem: Tools Not Available

ChatGPT

Problem: Custom GPT Not Working

  1. Verify OpenAPI specification is valid
  2. Check action configuration
  3. Test endpoint directly with curl
  4. Review ChatGPT action logs

Problem: Action Timeout

Cursor

Problem: @ Mention Not Working

  1. Verify server name in settings
  2. Check settings.json syntax
  3. Reload Cursor window
  4. Verify Cursor version supports MCP

Problem: Slow Suggestions

Kiro

Problem: MCP Server Not Connected

  1. Check MCP Servers panel
  2. Click “Reconnect”
  3. Verify URL in settings
  4. Review Kiro logs

Problem: Auto-Approve Not Working

Amazon Q

Problem: Extension Not Loading

  1. Check VS Code/IDE version
  2. Verify Amazon Q extension enabled
  3. Restart IDE
  4. Check extension logs

Problem: Authentication Failed

Reporting an Issue

Before Submitting an Issue

  1. Check This Guide
  2. Check Documentation
  3. Gather Information

Submit an Issue

Include: - Description of issue - Error messages - Request ID - Timestamp - Steps to reproduce - Configuration (remove sensitive data)

GitHub Issues: atlantis-mcp-server/issues

Diagnostic Commands

Test MCP Server Health

# Test server is responding
curl -i -X POST https://mcp.atlantis.63klabs.net/mcp/v1

Check Rate Limit Status

# Make request and check headers
curl -i -X POST https://mcp.atlantis.63klabs.net/mcp/v1

# Look for headers:
# X-RateLimit-Limit: <your-tier-limit>
# X-RateLimit-Remaining: <requests-remaining>
# X-RateLimit-Reset: <unix-timestamp>

Common Error Codes

Code Meaning Solution
400 Bad Request Check input parameters
401 Unauthorized Check URL or credentials
404 Not Found Verify resource name and category (or, for get_document, use the returned githubUrl to fetch directly)
429 Rate Limit Exceeded Wait for reset or self-host
500 Internal Server Error Retry or contact support
503 Service Unavailable Temporary issue, retry later

Frequently Asked Questions

Q: Why am I getting rate limited?

A: You’ve exceeded the request limit for your current tier. Check the rate limits page for details, or wait for your window to reset.

Q: Can I increase rate limits?

A: Yes. Register for a free account to unlock higher limits, or contact us about paid and private tiers. You can also self-host with custom limits.

Q: Why don’t I see my template?

A: Check bucket configuration, verify template name, namespace, and category.

Q: How do I clear the cache?

A: Cache expires automatically. For self-hosted, clear DynamoDB/S3 cache manually.

Q: Why is data stale?

A: Caching for performance. Wait for TTL expiration or adjust TTL in self-hosted instance.

Q: Can I use this in production?

A: Yes, but consider self-hosting for better performance and higher limits.

Support

If you need help with a specific use case: