Documentation

MangoApps for Gemini

Connect MangoApps to Google Gemini — setup, scopes, tools, tenant search, security, and admin controls.

At a glance Setup Tenant search For admins Tools Security Troubleshooting

At a glance

Endpoint

https://mcp.iq.mangoapps.com/api/v1/mcp

Protocol

Model Context Protocol (MCP) 2025-11-25, Streamable HTTP transport. The same MCP server used by Anthropic's Claude and OpenAI's ChatGPT — there is no separate codebase per AI vendor.

Authentication

OAuth 2.1 with PKCE. The Gemini CLI discovers the authorization server from the MCP endpoint and opens your browser to consent. MangoApps supports Dynamic Client Registration (RFC 7591), so no manual client setup is required.

Tools available

More than 1,150 tools across 95+ product domains plus the canonical search and fetch tools for tenant-wide lookup. The actual set surfaced is filtered by (a) the apps your tenant has enabled, (b) the scopes you grant during consent, and (c) your individual access rights inside MangoApps.

Rate limits

5,000 reads/hour per access token. 200 write operations/hour per (connector × tenant). 60 token refreshes/minute per source IP.

Audit

Every tool call records the calling client, user, tool, status, and latency. Sensitive argument values are redacted. Records are visible to tenant admins at /admin/connectors.

Availability

The MangoApps connector is enabled per-tenant by a MangoApps administrator. It's not gated by pricing tier — trial tenants, design partners, and any customer whose admin has flipped the switch can use it. If you can't authorize the connector, ask your tenant administrator or your MangoApps account team to enable it for your tenant.

Setup

Gemini CLI

Register MangoApps as a remote MCP server in your Gemini CLI settings (~/.gemini/settings.json, or a project-level .gemini/settings.json):

{
  "mcpServers": {
    "mangoapps": {
      "httpUrl": "https://mcp.iq.mangoapps.com/api/v1/mcp"
    }
  }
}

Save the file and start the Gemini CLI. On first use of a MangoApps tool, Gemini opens your browser to the MangoApps authorization page.
You'll be asked which MangoApps tenant — enter your tenant slug, the part of your MangoApps URL before .workforce.mangoapps.com. For example, if you sign in at acme.workforce.mangoapps.com, enter acme.
Sign in to MangoApps if you're not already, review the requested scopes on the consent screen, and click Authorize.
Back in the CLI, ask anything — "list my recent form submissions", "summarize last week's surveys", "what's overdue on my OKRs?"

Run /mcp to inspect the server and /mcp auth mangoapps to start or repeat OAuth. Keep trust false so Gemini continues to confirm tool calls.

See the official Gemini CLI MCP server guide for the current configuration schema and OAuth commands.

Search across your tenant

The connector exposes canonical search and fetch tools so Gemini can find and read across your data before it answers:

search(query) — Unified ILIKE search across forms, tasks, news-feed posts, Sites pages, and workspace messages. Returns up to ~15 results with typed IDs you can follow up on.
fetch(id) — Retrieve the full body of a single record by its typed ID (e.g., page:12, form:1145, post:7).

Example prompts that work well against a MangoApps tenant:

"Audit our remote-work policy: pull every policy doc, training module, and FAQ that mentions remote work, then summarize what's missing or contradictory."
"Compile a Q3 review packet: every Communications announcement, OKR status update, and Workspace post about the field-team launch."
"Find all forms our HR team owns. Which haven't been updated in 12+ months?"

Search respects every filter: Gemini can only read what the consenting user could read in MangoApps directly, and only across the OAuth scopes granted.

For administrators

Tenant-level controls

Tenant administrators manage every active connector from https://<your-tenant>.workforce.mangoapps.com/admin/connectors:

See who connected — Each row shows the OAuth client (e.g., "Gemini"), the user who authorized it, the scopes granted, and the last-used timestamp.
Revoke access — One-click revokes every active token issued to that connector for your tenant.
Audit log — Bottom of the page lists the most recent MCP tool calls (tool name, status, latency).

App-level controls

Disabling a marketplace app in MangoApps automatically removes its tools from the connector's catalog. For example, if your tenant disables the "Sites" app, Gemini can no longer list, create, or modify Sites pages even if the user had previously consented to those scopes.

User-level controls

The connector inherits each user's permissions in MangoApps. A user without permission to view payroll data cannot use Gemini to view payroll data, regardless of the OAuth scopes granted.

Privilege gate for broad access

The mcp:all_tools scope — which grants Gemini access to every domain — can only be authorized by tenant administrators. Non-admin users must request per-domain scopes (read:forms, write:tasks, etc.).

Tools and scopes

The connector exposes 1,150+ tools across 95+ product domains plus the canonical search and fetch tools. Each tool declares whether it is read-only or destructive via standard MCP annotations (readOnlyHint, destructiveHint), and Gemini surfaces these in its tool-call approval prompts.

Scope naming

Scopes use the pattern read:<domain> and write:<domain> for every product domain that exposes tools. For example:

read:forms — View forms and your submissions
write:forms — Create forms and submit form data
read:tasks / write:tasks — Tasks app
read:reporting — Run reports and view dashboards
mcp:all_tools — Broad access to every domain (admin-only)

The complete scope list is published at /.well-known/oauth-authorization-server on every MangoApps tenant.

Agentic experience — preview, idempotency, structured errors

These work on every write tool over the same MCP endpoint, so an agent can act safely and unattended:

Preview before writing — add "dry_run": true to a write tool's arguments to get back what it would change (a field-level diff for CRUD-backed tools; otherwise previewable: false, would_write: true) without committing.
Safe retries — send an Idempotency-Key header on a write; a retry with the same key replays the stored result (idempotent_replay: true) instead of executing twice. A mismatched body returns IDEMPOTENCY_CONFLICT.
Structured errors — failures return code, category (auth / validation / rate_limit / not_found / conflict / server), retryable, and retry_after in structuredContent, so agents branch instead of parsing prose.
Field selection — pass "fields": ["id","status"] (dot-paths supported) to trim the response to just what you need.
Batch — the batch tool runs many operations in one call (each independently scoped, rate-limited, audited); dry_run previews them all.
Authenticated execution — tools run with the consenting user's current MangoApps permissions and the OAuth scopes they granted. Clients may still ask the user to confirm a sensitive action before sending it.

Security and privacy

Data boundaries

Gemini can access only the data the consenting user could see in MangoApps directly.
Each access token is bound to a single MangoApps tenant. Tokens issued for tenant A cannot read or write tenant B's data.
Tool call inputs and outputs are not used by MangoApps to train AI models, build user profiles, or feed analytics beyond per-tenant usage metering.

Transport and origin

All connections require HTTPS.
The MCP server validates browser Origin headers against an allowlist. The Gemini CLI connects server-to-server and does not send a browser Origin header.
OAuth 2.1 with PKCE (S256 only) prevents authorization-code interception.
Token endpoint, registration endpoint, and tool endpoint each have separate per-IP rate limits.

Once data reaches Gemini

When the user invokes a tool, the tool output is returned to Gemini's runtime so it can compose a response. From that point, the data is subject to Google's privacy policy: policies.google.com/privacy and the agreement governing the user's Gemini CLI account. MangoApps does not control retention or downstream use by Google.

Audit trail

Every tool call writes a tenant-scoped audit record with the tool, calling client, consenting user, status, timestamp, and latency. Sensitive argument values are redacted. Records are accessible only to tenant administrators.

Full privacy policy

See the MangoApps Privacy Policy, specifically the section "AI Assistants and MCP Connectors".

Troubleshooting

"I authorized but Gemini says no tools are available"

The most common cause is that your tenant has disabled some or all marketplace apps, so even with broad scopes the catalog is empty. Ask your admin to check /admin/marketplace_apps for app enablement. In the CLI, run /mcp to confirm the server is connected and see how many tools it exposes.

"Tool call returns 'not accessible'"

The corresponding app was disabled for your tenant, or your user account is outside the app's visibility group. Ask your tenant administrator.

"Search returned no results"

The search tool ILIKE-matches across forms, tasks, posts, Sites pages, and workspace messages. If you're searching for content in a less-common app (Wikis, Knowledge Base), wait for v2 of the unified search — or use the app-specific tools directly (e.g., list_wikis).

"I want to revoke a connector immediately"

End users: remove the mangoapps server from your Gemini CLI settings.json, or revoke from your Google account's connected apps. Tenant admins: from MangoApps, open /admin/connectors, find the application row, click Revoke. The admin path invalidates the token immediately.

Contact

Questions, security disclosures, or feedback on the connector.

Product or setup questions: support@mangoapps.com
Security disclosures: security@mangoapps.com
Privacy questions: privacy@mangoapps.com

Prefer a different assistant? MangoApps for Claude · MangoApps for ChatGPT.