Developer Reference

API & MCP Bridge

Integrate AI assistants and automation tools with your CloudNerve workspace. Add links, organize categories, and manage your cloud dashboard programmatically.

Open Dashboard ← About

Two Integration Paths

MCP Protocol (AI Bridge)

Connect any MCP-compatible AI client (Claude, Gemini, Cursor, etc.) directly to your dashboard. The AI discovers available tools automatically.

API Key Auth

REST API

Traditional REST endpoint for scripts, CI/CD pipelines, or custom integrations. Uses Firebase ID tokens for user authentication.

Bearer Token

Base URL

Production

https://cloudnerve-dashboard-api-ygiud3zwvq-uc.a.run.app

Endpoints

GET/healthNo Auth

Health check. Returns service status.

Response

{
  "status": "ok",
  "timestamp": "2026-05-24T20:18:00.000Z"
}

POST/api/workspace/updateBearer Token

Merges the supplied fields into the authenticated user's default workspace. Supports updating the name, visibility, and categories with links.

Authentication

Header

Authorization: Bearer <firebase-id-token>

Get a Firebase ID token by calling getIdToken() on the authenticated Firebase user in your client app, or via the Firebase Auth REST API.

Request Body

JSON Schema

{
  "name": "My Workspace",           // optional
  "isPublic": false,                 // optional
  "categories": [                    // optional
    {
      "categoryName": "AI Tools",
      "links": [
        {
          "title": "ChatGPT",
          "url": "https://chat.openai.com",
          "addedAt": "2026-05-24T12:00:00Z"  // optional
        }
      ]
    }
  ]
}

Example

cURL

curl -X POST https://cloudnerve-dashboard-api-ygiud3zwvq-uc.a.run.app/api/workspace/update \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-firebase-id-token>" \
  -d '{
    "categories": [
      {
        "categoryName": "Documentation",
        "links": [
          {
            "title": "Kubernetes Docs",
            "url": "https://kubernetes.io/docs/"
          }
        ]
      }
    ]
  }'

Response (200)

{
  "workspace": {
    "name": "My Cloud Workspace",
    "isPublic": false,
    "categories": [...],
    "updatedAt": "2026-05-24T20:18:00.000Z"
  }
}

POST/mcpX-API-Key

MCP (Model Context Protocol) endpoint. Any MCP-compatible AI client can connect and discover available tools. Exposes 6 tools for managing dashboard content, searching links, and logging sessions.

Authentication

Header

X-API-Key: <your-mcp-api-key>

Available Tools (6)

add_to_dashboard

Adds a link to a workspace with notes and source references. Category created if missing. Deduplicates by URL.

Parameter	Type	Description
`userId`	string?	Firebase UID (defaults to owner)
`workspaceId`	string?	Target workspace (defaults to "default")
`category`	string	Category name (case-insensitive)
`title`	string	Display title
`url`	string	URL to add
`notes`	string?	Context note
`sourceUrl`	string?	NotebookLM / reference URL

list_workspaces

Lists all workspaces with names, IDs, counts, and NotebookLM references.

Parameter	Type	Description
`userId`	string?	Firebase UID (defaults to owner)

list_links

Lists all links in a workspace, optionally filtered by category.

Parameter	Type	Description
`userId`	string?	Firebase UID (defaults to owner)
`workspaceId`	string?	Workspace ID (defaults to "default")
`category`	string?	Filter by category name

add_note_to_link

Adds or updates a note/source reference on an existing link. Finds by URL in a category.

Parameter	Type	Description
`userId`	string?	Firebase UID (defaults to owner)
`workspaceId`	string?	Workspace ID (defaults to "default")
`category`	string	Category containing the link
`url`	string	URL of the link to annotate
`notes`	string?	Note to set (replaces existing)
`sourceUrl`	string?	NotebookLM / reference URL

search_links

Searches across category names, link titles, URLs, and notes. If a category name matches, all links in that category are returned.

Parameter	Type	Description
`userId`	string?	Firebase UID (defaults to owner)
`workspaceId`	string?	Workspace ID (defaults to "default")
`query`	string	Search query (case-insensitive)

log_session

Captures an Antigravity chat session as a link in the dedicated "Antigravity Sessions" workspace. Auto-creates the workspace if missing. Categories organized by date.

Parameter	Type	Description
`userId`	string?	Firebase UID (defaults to owner)
`title`	string	Session title/summary
`notes`	string?	Key decisions, changes, outcomes
`conversationId`	string?	Antigravity conversation UUID
`localPath`	string?	Local transcript file path
`category`	string?	Category name (defaults to today's date)
`sourceUrl`	string?	NotebookLM / reference URL

Getting Started: API Key

The MCP endpoint requires an API key passed via the X-API-Key header. This key authenticates your AI client to the CloudNerve API.

Quick Start (Development)

For local development and testing, you can use the development key:

Development API Key

X-API-Key: test-mcp-cloudnerve

⚠️ This is a development key intended for testing only. Do not use in shared or production environments. Rotate keys regularly and never commit them to source control.

Setting Your Own Key (Production)

To set or rotate the API key, update the MCP_API_KEY environment variable on your Cloud Run service:

gcloud CLI

gcloud run services update cloudnerve-dashboard-api \
  --region=us-central1 \
  --update-env-vars=MCP_API_KEY=<your-secure-key>

Use a strong, randomly generated key (32+ characters). The key is validated server-side on every MCP request before any tools are executed.

MCP Client Setup

Add the CloudNerve MCP server to your AI client's configuration to let AI assistants manage your dashboard automatically.

Claude Desktop / Cursor

Add to your claude_desktop_config.json or Cursor MCP settings:

MCP Server Config

{
  "mcpServers": {
    "cloudnerve-dashboard": {
      "url": "https://cloudnerve-dashboard-api-ygiud3zwvq-uc.a.run.app/mcp",
      "headers": {
        "X-API-Key": "<your-mcp-api-key>"
      }
    }
  }
}

Gemini CLI / Google Antigravity

Add to your mcp_config.json or Antigravity MCP settings:

MCP Server Config

{
  "mcpServers": {
    "cloudnerve-dashboard": {
      "url": "https://cloudnerve-dashboard-api-ygiud3zwvq-uc.a.run.app/mcp",
      "headers": {
        "X-API-Key": "<your-mcp-api-key>"
      }
    }
  }
}

Usage Examples

Once your MCP client is connected, simply ask your AI assistant in natural language. The AI will discover and call the right tool automatically.

Adding Links

“Save the Terraform docs to my dashboard under Infrastructure”

→ add_to_dashboard

“Add this Kubernetes tutorial to my 4208-Kensal-Links workspace under DevOps, with a note that it covers pod networking”

→ add_to_dashboard (with workspaceId + notes)

“Bookmark https://cloud.google.com/run/docs under API Reference with a link to my NotebookLM notebook”

→ add_to_dashboard (with sourceUrl)

Searching & Browsing

“Search for Financial in my dashboard links”

→ search_links (matches categories + link content)

“List all my workspaces”

→ list_workspaces

“Show me all links in the Infrastructure category”

→ list_links (with category filter)

Annotating & Logging

“Add a note to the Kubernetes docs link: covers v1.30 ingress changes”

→ add_note_to_link

“Log this Antigravity session — we built the export feature and fixed the MCP search”

→ log_session (auto-creates Sessions workspace)

“Export my CloudWorkspace as Markdown and save it to NotebookLM”

→ list_links (then frontend Export button)

Error Responses

Status	Error	Description
`400`	Invalid request body	Request failed Zod schema validation. Check the `details` field.
`401`	Missing or malformed Authorization header	REST endpoint: provide a valid `Authorization: Bearer <token>` header.
`401`	Invalid or missing API key	MCP endpoint: provide a valid `X-API-Key` header.
`503`	MCP endpoint not configured	The `MCP_API_KEY` environment variable is not set on the server.