Flowra

Manage app connections

FLOWRA_MANAGE_CONNECTIONS

Idempotent

Connect the user to an app, or check whether an app is already connected. Pass the toolkit slugs you need; connections are per end user and several toolkits can be checked in one call.

mode:

"connect" (default): if not already active, start the normal connect flow (may return redirectUrl / requires_parameters).
"status": read-only. Never mint OAuth/consent links or create INITIATED rows. Returns active / not_connected / no_auth_required / needs_setup only.

Each toolkit comes back with a status you must handle:

active / no_auth_required: ready — go execute the app's tools.
not_connected: only when mode is "status" — no active connection; call again with mode "connect" (or omit mode) when the user wants to connect.
initiated: redirectUrl is set. Show that one markdown link and stop. Do not call this tool again until the user says they finished connecting in the browser. Then call with the same toolkits to confirm it is active. A verify call must not mint a second link (wasReinitiated stays false).
requires_parameters: the user must supply credentials. Ask for exactly the fields listed in requiredParameters, showing each field's description, then call again with specifyCustomAuth.
requires_challenge: only when this status is returned. Ask for exactly the fields in requiredParameters, then call again with challengeResponse: { connectionId, plus those field names }. Do not invent a verification step when this status is absent.
needs_setup: a secondary end user cannot connect yet because project App credentials are missing. Tell them the app is not ready; never ask them for client_id, client_secret, or other app-level secrets. (Project default / owner instead gets requires_parameters for those App credential fields.)
failed: read errorMessage before retrying.

When talking to the user, use the label field (email, username, or app name). Never show a connection UUID.

Use specifyCustomAuth to activate an API key, bearer token, basic auth, or pasted cookies directly, without opening a browser. Pass session.id from FLOWRA_DISCOVER_TOOLS when you are continuing the same discovery session.

Input Schema

Name	Required	Description	Default
`mode`	Yes	connect (default): may start OAuth/consent when not active. status: read-only check — never mint redirectUrl or INITIATED rows.	connect
`session`	No	Optional meta session.id from DISCOVER for correlation (not required for OAuth).
`toolkits`	Yes	List of toolkit slugs (base like 'gmail' or project-scoped like 'gmail:abc123') to check or connect. Prefer base slugs from CREATE_OR_UPDATE_TOOLKIT / DISCOVER_TOOLS — project suffix is resolved automatically. Never invent slugs.
`reinitiateAll`	Yes	Force reconnection for ALL toolkits in the `toolkits` list, even if they already have active connections. DEFAULT: false (preserve existing active connections). Ignored when mode is status.
`challengeResponse`	No	Continue a pending challenge only after status is requires_challenge. Pass connectionId plus the field names from requiredParameters. Do not send this unless that status was returned.
`specifyCustomAuth`	No	Agent-friendly way to provide per-toolkit credentials and connection fields. Outer object: keys are toolkit names (must match entries in `toolkits`). Inner object: credentials for that toolkit. Supported patterns: API Key {"apiKey": "YOUR_KEY"}, Bearer Token {"bearerToken": "YOUR_TOKEN"}, Basic Auth {"username": "USER", "password": "PASS"}, Cookie {"cookies": "..."}, email/password {"email":"...","password":"..."}, Custom OAuth {"client_id": "...", "client_secret": "..."}, plus any field names from the toolkit authConfigDetails.

Output Schema

Name	Required	Description
`data`	No
`error`	No	Error if any occurred during the execution of the action
`message`	No
`successful`	No	Whether or not the action execution was successful or not

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 11, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "data": {
+      "properties": {
+        "message": {
+          "description": "Overall status message"
+        },
+        "results": {
+          "description": "Connection results for each toolkit",
+          "propertyNames": {}
+        },
+        "summary": {
+          "description": "Summary of results by status type",
+          "propertyNames": {}
+        }
+      }
+    },
+    "error": {
+      "anyOf": [
+        {},
+        {}
+      ],
+      "description": "Error if any occurred during the execution of the action"
+    },
+    "message": {},
+    "successful": {
+      "description": "Whether or not the action execution was successful or not"
+    }
+  },
+  "type": "object"
+}

First observedSep 25, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only carry readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true; the description adds substantial behavior beyond that: read-only mode never mints redirectUrl/INITIATED rows, verify calls must not re-issue a link, app-level secrets must never be requested from secondary users, and failed requires reading errorMessage first.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is long, but front-loaded with the core purpose and organized as a scannable mode block plus a status-handling list, so no section is filler. A few lines (e.g. the parenthetical about project default/owner) could be tightened, keeping it just under maximum marks.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 6-parameter tool with nested objects and an output schema (which the description rightly doesn't duplicate), it covers the full operating loop: modes, every return status, the exact follow-up action per status, and secrets/error handling. An agent has everything needed to invoke and recover correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3, but the description meaningfully enriches parameter use: it explains mode semantics and status outcomes, how requiredParameters maps to a follow-up call with specifyCustomAuth or challengeResponse, and when to pass session.id from DISCOVER. It stops short of documenting every field (e.g. reinitiateAll behavior is largely left to the schema).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a precise dual verb+resource: connect a user to an app, or check whether an app is already connected. It also names the scope (per end user, multiple toolkits per call), allowing an agent to distinguish this from discovery/execution siblings like FLOWRA_DISCOVER_TOOLS or FLOWRA_MULTI_EXECUTE_TOOL.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use rules for both modes ('status: read-only, never mint links'; 'connect: may start OAuth/consent'), plus a per-status playbook telling the agent exactly what to do next (show one link and stop, ask for requiredParameters fields, never invent a challenge). Alternatives and sequencing with FLOWRA_DISCOVER_TOOLS are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Flowra tools Inspect

Try in Browser

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?