[integrations] REST API gateway for non-MCP clients

[alanshurafa]

Summary

• Adds an optional REST API Edge Function alongside the MCP server
• 8 routes: search, capture, recent, get/update/delete thought, stats, health
• Unlocks ChatGPT Custom Actions, iPhone Shortcuts, Zapier/Make/n8n, web dashboards, and any tool that speaks HTTP
• Same auth as MCP (x-brain-key header or query param)
• Self-contained — no external dependencies beyond @supabase/supabase-js
• Follows the same README structure as the Slack Capture integration (credential tracker, numbered steps, troubleshooting)

Why

MCP works great for AI assistants (Claude, Cursor), but many tools only speak HTTP. This gateway gives every app, automation, and device a standard REST door into Open Brain without replacing or competing with MCP.

Tested in production with 75K+ thoughts — all 8 routes verified working (semantic search, text search, capture with metadata extraction, CRUD operations, stats).

Test plan

• Deploy to Supabase project via supabase functions deploy open-brain-rest --no-verify-jwt
• Test health endpoint: GET /health
• Capture a thought: POST /capture with {"content": "test thought"}
• Search semantically: POST /search with {"query": "test", "limit": 5}
• List recent: GET /recent?limit=5
• Get by ID: GET /thought/:id
• Update: PUT /thought/:id with {"content": "updated"}
• Delete: DELETE /thought/:id
• Verify CORS headers from browser

🤖 Generated with Claude Code

[justfinethanku]

Saw your Discord post — impressive work across all of these. I'm going to personally review each one. Not today, but they're on my list.

[justfinethanku]

Review: REST API Gateway for Non-MCP Clients

Great contribution! This fills a real gap in the Open Brain ecosystem by providing HTTP access for tools that don't speak MCP. The implementation is clean, well-documented, and follows the project's patterns.

What's Good

Strong documentation:

• Clear README with credential tracker, numbered steps, and troubleshooting
• Excellent use case examples (ChatGPT Custom Actions, iPhone Shortcuts, Zapier)
• Good code comments explaining the flow
• Test commands provided with expected responses

Solid technical implementation:

• Proper CORS headers for web dashboard compatibility
• Flexible auth (header, query param, or Bearer token)
• Parallel embedding + metadata extraction
• Safe error handling with fallbacks
• Consistent response format across all endpoints

Follows contribution standards:

• Correct category placement (integrations)
• Both required files present (README.md + metadata.json)
• Valid metadata.json with all required fields
• No credentials exposed
• PR title format correct: [integrations]

Required Changes

1. Remote MCP Pattern Violation (Critical)

The README correctly states this is a Supabase Edge Function, but the repo's guard rails require that all MCP-like integrations be documented as remote-only with no local server pattern. The contribution doesn't violate this (it IS an Edge Function), but I want to clarify one thing:

Question for the author: Is there any MCP server component to this, or is it purely a REST gateway? The title says "for non-MCP clients" which suggests it's an alternative to MCP, not an MCP server itself. If it's purely REST, this is fine. If there's an MCP component planned or implied, we need to ensure it's also deployed as an Edge Function.

Clarification needed: The README mentions "alongside the MCP server" in the intro. Is this contribution:

• A standalone REST API (no MCP involvement)
• A companion to an existing MCP server
• Both a REST API and an MCP server

If it includes MCP server functionality, please add setup steps for deploying that via Edge Functions following the pattern in docs/01-getting-started.md Step 7.

2. SQL Safety Check

The Edge Function code includes database operations. I don't see any DROP, TRUNCATE, or unqualified DELETE statements, which is good. The delete operations are properly scoped with .eq("id", id). ✅

3. Category-Specific Artifacts

For integrations, we require code files. This contribution includes a complete Edge Function in the README (563 lines of TypeScript). ✅

However, I strongly recommend extracting the Edge Function code to a separate file:

• Create integrations/rest-api-gateway/index.ts with the function code
• Update the README to reference it: "Copy the code from index.ts to supabase/functions/open-brain-rest/index.ts"

This makes the code easier to maintain, test, and copy-paste. It's not a blocker, but it's a strong recommendation.

Nice-to-Haves (Not Blockers)

OpenAPI Schema:
The README mentions "use the OpenAPI schema in the openapi.yaml file (or generate one from the routes above)" but there's no openapi.yaml file in the contribution. Consider adding one for the ChatGPT Custom Actions use case. Not required, but would be very helpful.

Rate Limiting Documentation:
The REST gateway doesn't appear to implement rate limiting (which is fine for v1), but it might be worth adding a troubleshooting note about Supabase Edge Function rate limits for users who expect high traffic.

Metadata Extraction Cost Warning:
Every capture call makes two OpenRouter API calls (embedding + metadata extraction). Consider adding a note in the README about API costs, especially for users doing bulk imports via this endpoint.

Metadata.json Review

{
  "name": "REST API Gateway", ✅
  "description": "Add a standard REST API to your Open Brain...", ✅
  "category": "integrations", ✅
  "author": {
    "name": "Alan Shurafa", ✅
    "github": "alanshurafa" ✅
  },
  "version": "1.0.0", ✅
  "requires": {
    "open_brain": true, ✅
    "services": [], ✅
    "tools": ["Supabase CLI"] ✅
  },
  "tags": ["rest", "api", "http", "gateway", "chatgpt-actions", "shortcuts", "zapier", "automation"], ✅
  "difficulty": "beginner", ✅
  "estimated_time": "10 minutes", ✅
  "created": "2026-03-16", ✅
  "updated": "2026-03-16" ✅
}

All required fields present and valid. Good tag selection covering the key use cases.

Test Plan Verification

The PR includes a comprehensive test plan:

• ✅ Health endpoint
• ✅ Capture
• ✅ Search (semantic)
• ✅ Recent thoughts
• ✅ CRUD operations (GET/PUT/DELETE)
• ✅ Stats
• ✅ CORS verification

This is thorough and matches the 8 routes documented in the README.

Scope Check

All changes are within integrations/rest-api-gateway/. No modifications to core files, other categories, or shared infrastructure. ✅

Security Review

• ✅ No hardcoded credentials
• ✅ Reuses existing secrets (MCP_ACCESS_KEY, OPENROUTER_API_KEY)
• ✅ Proper auth check before processing requests
• ✅ CORS headers are permissive (*) but appropriate for a personal Open Brain instance

---

Verdict: Minor fixes needed

Required before merge:

1. Clarify MCP involvement — If this includes MCP server functionality, add Edge Function deployment steps for that component
2. (Strongly recommended) Extract the Edge Function code to index.ts for easier maintenance

Optional improvements:

• Add openapi.yaml for ChatGPT Custom Actions
• Note API costs for metadata extraction
• Document Supabase rate limits

Author: Please respond to the MCP clarification question above. If this is purely a REST gateway with no MCP component, just confirm that and I'll approve. If there's MCP involved, we need deployment steps for that part.

Great work overall! This is a valuable addition that opens up Open Brain to a much wider ecosystem of tools.