Cloud MCP External Access Guide

Last Updated: January 22, 2026 (Session 60.2)

Overview

The Cloud MCP Gateway enables external access to GoGrab's AI intelligence system from anywhere - including Claude Cowork, Claude Desktop, external applications, and any HTTP-capable client.

This turns GoGrab MCP into a superpower extension for users, accessible from any AI assistant or development environment.

Authentication Methods

Quick Start: Claude Cowork / External Access

Step 1: Create a Project (One-Time Setup)

You need to create a project to get an API key. This requires a GoGrab Space account.

Option A: Via GoGrab Space UI

1. Log in to gograb.space
2. Navigate to AI Hub → Projects
3. Click Create Project
4. Copy the API key (shown only once!)

Option B: Via API

# Get JWT from browser DevTools (Application → Cookies or localStorage)
curl -X POST https://ai-api.gograb.space/ai-api/mcp/projects \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "my-claude-cowork",
    "displayName": "Claude Cowork Project"
  }'

Response:

{
  "success": true,
  "project": {
    "projectId": "my-claude-cowork",
    "displayName": "Claude Cowork Project",
    "databaseName": "ai-mcp-my-claude-cowork",
    "status": "active"
  },
  "apiKey": "mcp_a1b2c3d4e5f6...",  // SAVE THIS - shown only once!
  "message": "Project created successfully. Save the API key - it will not be shown again."
}

Step 2: Use MCP Tools from Claude Cowork

Once you have your API key, you can call any MCP tool from Claude Cowork or any external environment.

Get Context Before Starting (Preflight)

curl -X POST https://ai-api.gograb.space/ai-api/mcp/preflight \
  -H "X-MCP-API-Key: mcp_a1b2c3d4e5f6..." \
  -H "X-MCP-Project-Id: my-claude-cowork" \
  -H "Content-Type: application/json" \
  -d '{"task": "Implementing user authentication"}'

Response:

{
  "success": true,
  "preflight": {
    "task": "Implementing user authentication",
    "workingMemory": [...],
    "historicalHints": [...],
    "conventions": [...],
    "guidance": "Based on past decisions..."
  }
}

Log a Decision

curl -X POST https://ai-api.gograb.space/ai-api/mcp/tools/call \
  -H "X-MCP-API-Key: mcp_a1b2c3d4e5f6..." \
  -H "X-MCP-Project-Id: my-claude-cowork" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "log_decision",
    "arguments": {
      "type": "implementation",
      "question": "Which authentication strategy to use?",
      "chosen": "JWT with refresh tokens",
      "reasoning": "Stateless, scalable, works with mobile apps",
      "confidence": 0.9,
      "projectId": "my-claude-cowork"
    }
  }'

Search Similar Decisions

curl -X POST https://ai-api.gograb.space/ai-api/mcp/tools/call \
  -H "X-MCP-API-Key: mcp_a1b2c3d4e5f6..." \
  -H "X-MCP-Project-Id: my-claude-cowork" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "find_similar",
    "arguments": {
      "query": "user authentication JWT",
      "limit": 5
    }
  }'

List Available Tools

curl -X GET https://ai-api.gograb.space/ai-api/mcp/tools \
  -H "X-MCP-API-Key: mcp_a1b2c3d4e5f6..." \
  -H "X-MCP-Project-Id: my-claude-cowork"

Available MCP Tools

API Endpoints

Tool Endpoints (JWT or API Key)

Project Management (JWT Only)

Health & Metrics (No Auth)

Database Isolation

Each project gets its own isolated database:

MongoDB Atlas
├── ai-agents              (Platform decisions)
├── ai-mcp-dev             (GoGrab dev team)
├── ai-mcp-my-claude-cowork (Your project!)
│   ├── decisions
│   ├── sessions
│   ├── patterns
│   └── conventions
└── ai-mcp-{other-projects}

Your decisions are completely isolated from other projects and users.

Usage Limits

Check your usage:

curl -X GET https://ai-api.gograb.space/ai-api/mcp/usage \
  -H "X-MCP-API-Key: mcp_..." \
  -H "X-MCP-Project-Id: my-project"

Claude Desktop Configuration

For native MCP support in Claude Desktop:

{
  "gograb-cloud": {
    "transport": "http",
    "url": "https://ai-api.gograb.space/ai-api/mcp",
    "headers": {
      "X-MCP-API-Key": "mcp_your_api_key_here",
      "X-MCP-Project-Id": "your-project-id"
    }
  }
}

Error Handling

Common Error Responses

401 Unauthorized

{
  "statusCode": 401,
  "message": "API key authentication requires both X-MCP-API-Key and X-MCP-Project-Id headers"
}

403 Project Inactive

{
  "statusCode": 403,
  "message": "Project \"my-project\" is suspended. Only active projects can make API calls."
}

429 Rate Limited

{
  "statusCode": 429,
  "message": "Hard limit reached. Upgrade your tier or wait for next billing period."
}

Security Best Practices

1. Never commit API keys - Use environment variables
2. Regenerate keys periodically - Use the regenerate-key endpoint
3. Use project-specific keys - Don't share keys across projects
4. Monitor usage - Check /mcp/usage regularly

Troubleshooting

API Key Not Working

1. Verify both headers are present:
   • X-MCP-API-Key: mcp_...
   • X-MCP-Project-Id: your-project
2. Check project status is "active"
3. Verify key hasn't been regenerated

Decisions Not Appearing

1. Ensure projectId is in the request body
2. Check the correct database: ai-mcp-{projectId}
3. Verify the tool call was successful

High Latency

1. Check /ai-api/mcp/health for service status
2. Consider using preflight instead of multiple tool calls
3. Batch operations when possible

Related Documentation

• Cloud MCP Implementation
• MCP Architecture Decision
• Multi-Project Guide
• Railway Deployment

Session 60.2 - Cloud MCP External Access