| name | agenticflow-mcp |
| description | Attach external tool providers (Google Docs, Google Sheets, Slack, Notion, GitHub, Apify, etc.) to an AgenticFlow agent via MCP clients. Use when the user wants their agent to read or write external data, call third-party APIs, save outputs to a doc/sheet, or use any tool beyond the model's built-in knowledge. Covers `af mcp-clients list --name-contains`, `af mcp-clients inspect --id` (classify pattern before attach), and the Pipedream vs Composio write-capability distinction — critical for parametric writes. Route traffic through the `af` CLI; the standalone `agenticflow-mcp` server repo lags the CLI and is not recommended. |
| compatibility | Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI |
| metadata | {"author":"PixelML","version":"3.0.0","license":"MIT"} |
| triggers | ["mcp","mcp client","attach tools","give my agent tools","google docs","google sheets","notion","slack","github","apify","external tool","tool integration","pipedream","composio"] |
AgenticFlow MCP
🚫 Do NOT install the legacy agenticflow-mcp standalone server repo. It is stale (last release lags the current platform by many versions) and is not the recommended integration path. Everything below uses the af CLI (install via npm install -g @pixelml/agenticflow-cli), which covers MCP operations comprehensively and stays in lockstep with platform changes.
MCP (Model Context Protocol) clients are the tool-provider layer that lets an agent read or write external systems — Google Docs, Google Sheets, Slack, Notion, GitHub, Apify, Gmail, Pinterest, YouTube, and many more. A workspace usually has many MCP clients already configured; your job is to pick the right one and verify it's safe before attaching to an agent.
Orient first
Before touching MCP clients, run:
af bootstrap --json
Extract auth.workspace_id + _links.mcp (the web UI URL for MCP management). Surface _links.mcp to the user: "Your MCP connections live at <_links.mcp> — you can add or re-authenticate providers there if any inspections fail." If data_fresh: false, the backend is degraded — don't mutate.
The one pattern that matters: inspect before attach
Not all MCP clients are equal. There are two major families, and one of them breaks on writes.
af mcp-clients list --name-contains "google sheets" --fields id,name,is_authenticated --json
af mcp-clients inspect --id <mcp_client_id> --json
inspect classifies the tool set and returns a pattern field:
| pattern | Meaning | Safe to attach? |
|---|
composio | Structured schemas with multiple named fields (e.g. spreadsheetId, range, values) | ✅ Yes — writes work reliably |
pipedream | Every tool has a single {instruction: string} input | ⚠️ Read-only tools fine. Parametric writes (add-row, update-cell, append) may get stuck in a configure_props_<tool>_props loop — the tool configures but never executes |
mixed | Some structured, some instruction-only | Restrict allowlist to the structured (Composio-style) tools only |
unknown | Tool list couldn't be enumerated | Do not attach. Check classification_reason + fetch_error in the response. Re-auth via the web UI if needed |
inspect also returns known_quirks[] — read it. If it contains a warning about configure_props_<tool>_props, you've been warned; do not attach that client for writes.
Attach shape (use --patch, not full-body update)
af agent update --agent-id <agent_id> --patch --body '{
"mcp_clients": [
{
"mcp_client_id": "<id-from-inspect>",
"run_behavior": "auto_run",
"description": "Google Sheets for logging outputs",
"timeout": 150,
"tools": {
"GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND": {"allowed": true},
"GOOGLESHEETS_VALUES_UPDATE": {"allowed": true},
"GOOGLESHEETS_DELETE_SHEET": {"allowed": false}
}
}
]
}' --json
tools is a per-tool allow/block map. Block destructive ops (DELETE_*, CLEAR_*) unless the use case explicitly needs them. The CLI's --patch merges this over the current agent — existing MCP clients and other config are preserved.
Verify auth state (list vs. get can disagree)
af mcp-clients list returns a cached is_authenticated that can be stale. If something is off, reconcile:
af mcp-clients list --verify-auth --json
If classification_reason in inspect is fetch_failed or unauthenticated, re-auth the client in the web UI at /workspaces/<ws>/mcp/<client_id> before attaching.
Smoke test after attach
af agent run --agent-id <agent_id> --message "Try writing 'hello' to row 1" --json
On failures
pattern: "pipedream" + write attempt → TOOL_CONFIGURATION_COMPLETED or configure_props_<tool>_props in the response. Switch to a Composio-backed client (many workspaces have both).mcp-clients inspect returns classification_reason: "fetch_failed" → the MCP provider's backend is down or the OAuth session expired. Open the web UI, re-auth, retry.- Silent success (model says "done" but no actual write) → 99% of the time it's a Pipedream write quirk. Re-inspect, switch provider.
Reference
