Integrations

Reasoning is only useful if a workflow can act. TurfAI integrates with the outside world through integration task types, OAuth (Google-delegated and a generic OAuth2 adapter), the MCP protocol, and a secure credential store.

Built-in integration tasks

Each task type is a node you drop into a workflow. The executor resolves {{variable}} templates in config from the trigger payload, upstream node outputs, and injected credentials/OAuth tokens before the processor runs.

The rest_api_task is the universal escape hatch — if a system has an HTTP API, a workflow can call it. See the REST integration guide. Field-level schemas live in the Task types reference.

Google (Drive & Gmail)

Google integrations use delegated OAuth (distinct from "Sign in with Google" login). A user grants TurfAI access to their own Drive/Gmail; the platform stores per-user tokens and auto-refreshes them when a workflow runs.

Scopes are limited to what the feature needs (Drive read, Gmail read/reply). Once GET /google/oauth/status shows connected, workflows can fetch Drive files, read Gmail, and the Event Bus can watch folders. Full detail: Google OAuth reference.

Generic OAuth2 adapter (any provider)

Beyond Google, TurfAI ships a provider-agnostic OAuth2 adapter. A new provider is added by registering an integration record with an oauth_config (authorize/token/userinfo/revoke URLs, scopes, env-var names for client id/secret, optional PKCE) — no code changes. The same four endpoints serve every provider:

Microsoft 365, Salesforce, and Slack are seeded out of the box. To use a connected provider's token in a workflow node, set "oauth_integration": "{provider}" in the node config — at execution time the executor looks up the user's tokens, auto-refreshes if expiring, and injects oauth_access_token into the node's input_mapping (the oauth_integration key is then removed before the processor sees it).

{
  "task_type": "rest_api_task",
  "config": {
    "oauth_integration": "microsoft_365",
    "url": "https://graph.microsoft.com/v1.0/me/messages",
    "method": "GET",
    "headers": { "Authorization": "Bearer {{oauth_access_token}}" }
  }
}

Credentials

Don't hardcode secrets in task configs. Store them as credentials (/api/credentials): each has a name, a provider, named fields, and is encrypted at rest with AES-256-GCM. The API never returns secret values — only metadata and field_names.

curl -X POST https://apisandbox.turfai.in/api/credentials \
  -H "Authorization: Bearer $TURFAI_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "Acme API",
      "provider": "acme",
      "fields": { "api_token": "sk_live_…" }
    }
  }'

The response echoes metadata only — id, name, provider, field_names: ["api_token"] — never the values.

How {{variable}} resolves

A node references a credential by its numeric credential_id, not by name. At execution time the executor decrypts the credential and merges each field into that node's input_mapping (without overwriting existing keys), then deletes credential_id from the config so the processor never sees it. Templated strings in url / headers / body then resolve {{field_name}} from input_mapping:

{
  "task_type": "rest_api_task",
  "config": {
    "credential_id": 7,
    "url": "https://api.acme.com/roles/{{role_id}}",
    "headers": { "Authorization": "Bearer {{api_token}}" }
  }
}

Here {{api_token}} comes from credential 7's decrypted fields, and {{role_id}} comes from the trigger payload or an upstream node. Deleting a credential requires step-up authentication. Walk through it end to end in the REST integration guide.

MCP (Model Context Protocol)

MCP is the open standard for connecting AI to external tools. TurfAI uses it two ways:

1. Outbound — TurfAI exposes its own capabilities (extract, search, workflow, agent chat) as an MCP server so clients like Claude Desktop or Cursor can call them.
2. Inbound — agents connect to external MCP servers (databases, GitHub, Slack, custom) and use their tools inside the ReAct loop. Configure an agent's mcp_servers, and the discovered tools merge into its tool list automatically (namespaced serverId::toolName). A workflow can also call a single MCP tool as a step via the mcp_tool_task node.

See Use MCP tools.