Gealo MCP Server

Hosted remote Model Context Protocol server for Gealo workspaces.

Connect Claude, Cursor, VS Code, Codex, or Gemini CLI to your organization's tasks, projects, meetings, documents, and chat — with OAuth 2.1, tenant isolation, and the same project permissions you have in the app.

The MCP server runs on Gealo's infrastructure at your tenant URL (https://{slug}.gealo.app/mcp). This repository documents the public integration surface and ships an optional STDIO bridge Docker image for MCP clients that only support local subprocess transport.

Endpoint

Every Gealo organization has its own MCP endpoint:

https://{your-tenant-slug}.gealo.app/mcp

Example: workspace acme → https://acme.gealo.app/mcp

Copy the exact URL from Tenant → AI Agents after sign-in.

Discovery

OAuth protected-resource metadata is published per tenant:

GET https://{your-tenant-slug}.gealo.app/.well-known/oauth-protected-resource/mcp

Related MCP server: Google Workspace MCP

Transport

Gealo's hosted MCP server uses Streamable HTTP at /mcp (MCP 2025-03-26+). It also supports session-backed SSE when clients send Accept: text/event-stream and maintain an Mcp-Session-Id. stdio is not served by Gealo — clients that only speak stdio need a local bridge (see Docker image below).

Authentication

• Interactive (default): OAuth 2.1 + PKCE. Your MCP client (or the bridge) opens a browser consent flow on first connect. Tokens are stored locally by the client/bridge (~/.mcp-auth or MCP_REMOTE_CONFIG_DIR), not on Gealo beyond server-side refresh-token rotation metadata.

• Scopes: mcp:read (default), mcp:write (when tenant admin enables write tools)

• Headless / CI: Service accounts via client_credentials grant (Tenant → AI Agents → Service Accounts)

curl -X POST "https://{slug}.gealo.app/oauth/mcp/token" \
  -d grant_type=client_credentials \
  -d client_id=sa:{service-account-id} \
  -d client_secret={api-key} \
  -d scope=mcp:read \
  -d resource=https://{slug}.gealo.app/mcp

Use the returned access_token as Authorization: Bearer on POST /mcp.

Quick connect (recommended — no Docker)

Replace {slug} with your tenant slug. Prefer direct remote URL when your client supports HTTP + OAuth natively.

Cursor

~/.cursor/mcp.json or project .cursor/mcp.json:

{
  "mcpServers": {
    "gealo": {
      "url": "https://{slug}.gealo.app/mcp"
    }
  }
}

Cursor opens the OAuth consent flow on first use.

See also: examples/cursor-mcp.json

Claude (Desktop / Web)

1. Settings → Connectors → Add custom connector

2. URL: https://{slug}.gealo.app/mcp

3. Advanced → OAuth Client ID: claude (secret empty)

4. Complete sign-in and consent in the browser

VS Code (Copilot agent mode)

.vscode/mcp.json:

{
  "servers": {
    "gealo": {
      "type": "http",
      "url": "https://{slug}.gealo.app/mcp"
    }
  }
}

See also: examples/vscode-mcp.json

Codex CLI

~/.codex/config.toml:

[mcp_servers.gealo]
url = "https://{slug}.gealo.app/mcp"

Then: codex mcp login gealo

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "gealo": {
      "httpUrl": "https://{slug}.gealo.app/mcp"
    }
  }
}

Then /mcp auth gealo if needed.

Docker image (optional STDIO bridge)

Image: ghcr.io/mhdyousuf/gealo-mcp:latest
Purpose: Lets stdio-only MCP clients connect to Gealo's hosted Streamable HTTP endpoint. The container is not the Gealo MCP server — it is a local proxy.

Use Docker when:

• Your MCP client only supports command / stdio servers

• You need OAuth bridging for a client without native remote MCP support

Do not use Docker when your client supports url / HTTP remote MCP (Cursor, VS Code, Claude Web, Codex, Gemini) — connect directly to https://{slug}.gealo.app/mcp.

Environment variables

* Set GEALO_TENANT_SLUG or GEALO_MCP_URL.

Security: Never bake secrets into the image. Pass service-account credentials via env at runtime. Mount a named volume for OAuth tokens so reconnects do not re-prompt.

Local testing

# Build
docker build -t ghcr.io/mhdyousuf/gealo-mcp:local .

# Health check (discovery endpoint reachable)
docker run --rm -e GEALO_TENANT_SLUG=acme ghcr.io/mhdyousuf/gealo-mcp:local dist/health.js

# Interactive OAuth bridge (stdio — pipe JSON-RPC for manual tests)
docker run -i --rm \
  -e GEALO_TENANT_SLUG=acme \
  -p 3333:3333 \
  -v gealo-mcp-auth:/home/gealo/.mcp-auth \
  ghcr.io/mhdyousuf/gealo-mcp:local

# Service account (headless)
docker run -i --rm \
  -e GEALO_TENANT_SLUG=acme \
  -e GEALO_AUTH_MODE=service_account \
  -e GEALO_CLIENT_ID=sa:YOUR-SA-ID \
  -e GEALO_CLIENT_SECRET=YOUR-API-KEY \
  ghcr.io/mhdyousuf/gealo-mcp:local

# Node (without Docker)
npm install && npm run build
GEALO_TENANT_SLUG=acme npm start

Docker + Cursor (stdio clients)

See examples/cursor-mcp-docker.json. Map port 3333 for the OAuth browser callback on first connect.

Docker + VS Code

See examples/vscode-mcp-docker.json.

Docker + service accounts / CI

See examples/cursor-mcp-service-account-docker.json.

Publishing

GitHub Actions workflow .github/workflows/publish-docker.yml publishes to GHCR using GITHUB_TOKEN:

• ghcr.io/mhdyousuf/gealo-mcp:latest (on main)

• ghcr.io/mhdyousuf/gealo-mcp:<version> (from package.json and git tags v*)

Make the package public in GitHub → Packages after the first successful publish.

First tool call

After connecting, call whoami to ground the session:

• User, tenant, and plan

• Remaining monthly MCP tool budget

• Whether write tools are enabled for your token

Use search_tools to browse the catalog filtered to your permissions.

Tools (60+)

Tools are scoped to your tenant and project permissions. Writes require admin opt-in (mcp:write scope).

Catalog tools (e.g. sprint/release write ops) are reachable via search_tools → execute_tool when your role allows.

Requirements

• A Gealo workspace with MCP access on your plan

• Active membership in that tenant (agents act as you)

• MCP not disabled by a workspace admin

Governance

• Tenant isolation — every call is scoped to your workspace tenant_id

• Project permissions — same templates as the REST API; no privilege escalation via MCP

• Read by default — writes off until an owner enables them

• Destructive preview — archive, bulk status, delete comment, etc. return a preview token; apply_pending_action confirms (10-minute expiry)

• Audit & metering — tool calls logged; monthly caps from your subscription entitlements

Details: gealo.app/mcp-server/governance

Multi-tenant users

Connections are per organization. Add one server entry per tenant slug you work in.

Troubleshooting

Links

• Product: gealo.app

• MCP overview: gealo.app/mcp-server

• Governance: gealo.app/mcp-server/governance

• Sign up: gealo.app/register

License

MIT — see LICENSE. Gealo is a commercial product; this repo documents the public MCP integration surface only.