3.21.0 • Published 6d agoCLI

@genlobe/mcp-server

Licence

MIT

Version

3.21.0

Deps

Size

419 kB

Vulns

Weekly

319

Summary Dependency Versions

Genlobe MCP Server

A Model Context Protocol (MCP) server that documents the Genlobe API so AI assistants in your IDE (Cursor, Claude Code, Windsurf, Claude Desktop, …) can build real clients against it — without hallucinating endpoints, shapes, or auth headers.

Paste it into your MCP config and ask your assistant "build me a login screen" or "add a checkout flow". It will pull the right endpoints, headers, and code patterns straight from this server.

What it documents

The Genlobe API has two surfaces. This server only exposes the one your end-user app should call:

Surface	Path prefix	Auth	Documented here?
End-user API	`/v1/auth/`, `/v1/agents/`, `/v1/organizations/`, `/v1/external-agents/`, …	`X-API-Key` + end-user JWT	Yes
Tenant / Dashboard API	`/v1/tenant-auth/`, `/v1/dashboard/`	Tenant member JWT	No — by design

If the assistant ever suggests calling /v1/dashboard/... or /v1/tenant-auth/... from your end-user frontend, it's wrong: those endpoints exist for tenant admins, not for the apps you build on Genlobe.

Install

Get an API key from genlobe.ai → Tenant Dashboard → API Keys. Pick your client below, drop the key in, restart the client, and the genlobe server appears in its MCP list. The two env vars are SAAS_API_URL (defaults to https://api-core.genlobe.ai) and SAAS_API_KEY (pk_live_* or sk_live_*) — see Environment variables.

A sk_live_* secret key is sensitive — don't put it in a config that gets committed to version control (e.g. a project-scoped file). Use a public pk_live_* key there, or keep the secret in a per-user / local config.

Claude Code

Use the CLI (docs) — it writes the config for you:

claude mcp add genlobe \
  --env SAAS_API_URL=https://api-core.genlobe.ai \
  --env SAAS_API_KEY=pk_live_or_sk_live_xxx \
  -- npx -y @genlobe/mcp-server

The -- separates Claude Code's own flags from the command that launches the server. Choose where it's stored with --scope: local (default — this project, private to you), project (writes a shared .mcp.json at the repo root), or user (all your projects). With --scope project the resulting .mcp.json looks like:

{
  "mcpServers": {
    "genlobe": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@genlobe/mcp-server"],
      "env": {
        "SAAS_API_URL": "https://api-core.genlobe.ai",
        "SAAS_API_KEY": "pk_live_or_sk_live_xxx"
      }
    }
  }
}

There is no ~/.config/claude-code/mcp.json. Claude Code stores servers in the project .mcp.json (project scope) or ~/.claude.json (local / user scope) — prefer the claude mcp add command above over hand-editing those.

Cursor

Settings → Tools & MCP → New MCP Server, or create .cursor/mcp.json in the project (~/.cursor/mcp.json applies to all projects) (docs):

{
  "mcpServers": {
    "genlobe": {
      "command": "npx",
      "args": ["-y", "@genlobe/mcp-server"],
      "env": {
        "SAAS_API_URL": "https://api-core.genlobe.ai",
        "SAAS_API_KEY": "pk_live_or_sk_live_xxx"
      }
    }
  }
}

Windsurf

Cascade's Plugins / MCP panel, or edit ~/.codeium/windsurf/mcp_config.json (Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json) (docs):

{
  "mcpServers": {
    "genlobe": {
      "command": "npx",
      "args": ["-y", "@genlobe/mcp-server"],
      "env": {
        "SAAS_API_URL": "https://api-core.genlobe.ai",
        "SAAS_API_KEY": "pk_live_or_sk_live_xxx"
      }
    }
  }
}

Claude Desktop

Settings → Developer → Edit Config, or edit claude_desktop_config.json directly — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json. Fully quit and reopen Claude Desktop after editing.

{
  "mcpServers": {
    "genlobe": {
      "command": "npx",
      "args": ["-y", "@genlobe/mcp-server"],
      "env": {
        "SAAS_API_URL": "https://api-core.genlobe.ai",
        "SAAS_API_KEY": "pk_live_or_sk_live_xxx"
      }
    }
  }
}

Codex CLI

Codex uses TOML, not JSON. Manage with codex mcp or edit ~/.codex/config.toml (a project-scoped .codex/config.toml also works) (docs):

[mcp_servers.genlobe]
command = "npx"
args = ["-y", "@genlobe/mcp-server"]

[mcp_servers.genlobe.env]
SAAS_API_URL = "https://api-core.genlobe.ai"
SAAS_API_KEY = "pk_live_or_sk_live_xxx"

npx -y always pulls the latest published version. Pin one for reproducibility: @genlobe/mcp-server@3.3.1.

Environment variables

Variable	Required	Value
`SAAS_API_URL`	no	Defaults to `https://api-core.genlobe.ai`. Override only if you point at a local or on-prem backend.
`SAAS_API_KEY`	optional	Your Genlobe API key. Accepts both `pk_live_` (public) and `sk_live_` (secret). Without it, only the offline documentation tools work — the four live tools (`validate_credentials`, `list_end_users`, `list_oauth_providers`, `get_openapi_spec`) need it.
`SAAS_FRONTEND_URL`	no	Dashboard URL used by the redirect-URL tools (`get_stripe_config_url`, `get_agent_secrets_url`, `get_plan_management_url`). Resolution order: (1) this variable if set; (2) derived from `SAAS_API_URL` by swapping the leading `api.` / `api-core.` sub-domain for `app.`; (3) `https://app.genlobe.ai`.

API_URL and API_KEY (without the SAAS_ prefix) are accepted as aliases for backward compatibility.

Tools

19 tools, in four groups.

Documentation (offline, no API key needed)

Tool	Returns
`get_api_overview`	High-level architecture, auth model, key concepts, recommended call order. Start here.
`list_endpoint_categories`	Bare list of end-user endpoint categories plus a one-line summary of each. ~30 tokens. Call this once when you don't already know what's available; then use `get_end_user_endpoints({ category })` for the actual docs.
`get_end_user_endpoints`	Reference for end-user endpoints in ONE category. Pass `category` (one of `authentication`, `organizations`, `subscriptions`, `billing`, `organization_admin`, `usage`, `agents`, `users`, `plans`, `ai`, `entities`, `departments`, `files`, `external_agents`). The `billing` category covers Tier-3 admin read-only billing endpoints (`/v1/organization-admin/{org_id}/{plans, config/stripe, audit, subscriptions}`); the new `organization_admin` category covers the non-billing Org Owner Dashboard surfaces (members, customers, agents, knowledge bases, agent-change notifications, Stripe webhook audit). Calling without a category returns the full catalog — use sparingly.
`get_reserved_schema_slugs`	Returns the 53 slugs the Custom Entities subsystem refuses at `POST /v1/entity/schemas` (ADR-0011 — they collide with native DB tables: `users`, `conversations`, `agents`, …). Pure data, no network call. Use it to pre-validate before issuing the POST and avoid a `400` round-trip.
`get_request_headers`	The exact HTTP headers required for end-user requests, with examples.
`get_authentication_flow`	Step-by-step register → login → refresh → logout, including token storage and refresh-on-401 patterns.
`get_common_patterns`	Pagination, error handling, optimistic updates, file upload, RAG queries, agent execution.
`get_sdk_template`	A ready-to-paste TypeScript SDK module (`fetch`-based, typed) covering auth, agents, organizations, files, billing.
`search_endpoints`	Keyword search across path, summary, and description.
`get_endpoint_details`	Full request/response schema for a specific `(method, path)`.

Redirect-URL tools (no secrets ever returned by the MCP)

These tools return a Dashboard URL the human developer should visit to set or rotate a secret. The MCP NEVER accepts or returns raw secret values; instead it points the agent at the right page so the human pastes the key in the browser. See the "MCP server invariants" section in the root CLAUDE.md for the pattern.

All three return { url, reason, next_action: { type: "open_in_browser", url } } and do no network calls — they are pure URL computation against the configured SAAS_FRONTEND_URL.

Tool	Returns
`get_stripe_config_url({ org_id })`	`${frontend_url}/org-admin/{org_id}/integrations/stripe` — page where the Organization Owner sets / rotates the org's Stripe `secret_key`, `publishable_key`, `webhook_secret`. Pair it with `GET /v1/organization-admin/{org_id}/config/stripe` (returned masked) to detect whether Stripe is already configured.
`get_agent_secrets_url({ agent_id })`	`${frontend_url}/dashboard/agents/{agent_id}/secrets` — page where the Tenant rotates / sets an Agent's provider keys (OpenAI / Anthropic / etc.) and webhook secrets.
`get_plan_management_url({ org_id })`	`${frontend_url}/org-admin/{org_id}/plans` — page where the Organization Owner creates / edits / deletes Plans. Write operations are not exposed via MCP because the plan-sync flow needs the encrypted Stripe `secret_key`.

Live (require `SAAS_API_KEY`)

Tool	Does
`validate_credentials`	Probes the API with the configured key. Reports the detected key type (`pk_live_` vs `sk_live_`), masked prefix, success/failure of a sample call, and the resolved API URL. Run this first in any session.
`get_openapi_spec`	Fetches the live `/v1/openapi.json` from `SAAS_API_URL`. Reflects the deployed API exactly.
`list_end_users`	`GET /v1/auth/users` — paginated list of end-users in the tenant. Requires `sk_live_*`.
`list_oauth_providers`	Lists the OAuth providers (Google, …) enabled for end-user social login.

Security & architecture (key-aware, no network calls)

Tool	Does
`get_security_guide`	Key-type-specific safe-usage cheat sheet. For `pk_live_`: allowed endpoints and the "may be exposed in browser bundles" rule. For `sk_live_`: leak vectors and the server-only architecture pattern.
`recommend_stack`	Given an `app_type` (`frontend_only`, `fullstack`, `backend_service`, `mobile_app`, `cli_tool`, `desktop_app`) plus the detected key type, returns a framework recommendation that physically prevents the key from leaking (Next.js App Router, Remix, SvelteKit, Nuxt, Astro for fullstack + secret; appropriate alternatives elsewhere).

Recommended call order

1. validate_credentials       → confirm SAAS_API_KEY works, learn its type
2. get_security_guide         → know what you can and can't do with that key
3. recommend_stack            → pick a framework that won't leak the key
4. get_api_overview           → understand the API at a high level
5. get_authentication_flow    → wire up register / login / refresh
6. list_endpoint_categories   → see which endpoint categories exist
7. get_end_user_endpoints     → drill into one category at a time
8. get_sdk_template           → start writing real code

For targeted questions ("how do I list organizations?"), search_endpoints + get_endpoint_details is faster than scrolling through get_end_user_endpoints.

When the developer needs to set or rotate a secret (Stripe key, Agent provider key, webhook secret), call the matching get_*_url tool — the MCP returns a Dashboard URL the human visits to paste the key. Inline secret input through the MCP is not supported by design.

Support

Sign up and manage API keys: genlobe.ai
Issues and feature requests: github.com/KleioTechnology/saas-multi-agent-tenant-ui/issues

License

MIT.

Keywords

mcp model-context-protocol saas api ai copilot cursor genlobe