Use MCP tools

The Model Context Protocol (MCP) is the open standard for connecting AI to external tools. TurfAI uses it in both directions. See Integrations for the overview.

Outbound: TurfAI as an MCP server

TurfAI exposes its own capabilities as MCP tools so clients like Claude Desktop or Cursor can call them. The server wraps the DMS REST API — it creates jobs and polls for results — and provides tools for document extraction, semantic search (RAG), workflow execution, and agent chat.

Claude Desktop / Cursor ──MCP──▶ TurfAI MCP Server ──HTTP──▶ DMS ──▶ Job Router ──▶ Processor

Point your MCP client at the TurfAI MCP server. For a stdio client like Claude Desktop, add it to the client's MCP config:

{
  "mcpServers": {
    "turfai": {
      "command": "npx",
      "args": ["-y", "@turfai/mcp-server"],
      "env": {
        "TURFAI_BASE_URL": "https://apisandbox.turfai.in/api",
        "TURFAI_JWT": "<your-jwt>"
      }
    }
  }
}

Once connected, the TurfAI tools appear alongside the client's other tools. For example, the agent-chat tool proxies POST /agents/{slug}/public-chat, so an MCP client can talk to any of your agents.

Inbound: agents using external MCP servers

An agent can connect to external MCP servers (databases, GitHub, Slack, custom) and use their tools inside its ReAct loop. The discovered tools merge into the agent's tool list automatically — no per-tool wiring.

Configure the agent's mcp_servers (a JSON array on the agent record) with connection details. Each entry needs an id (used to namespace its tools), a transport (stdio today), and the command / args / env to launch the server. Secrets in env use the same {{CREDENTIAL_NAME}} placeholder syntax as the rest of the platform and resolve from the encrypted credential store at runtime.

{
  "data": {
    "name": "DB-Aware Agent",
    "goal": "Answer questions using the customer database.",
    "available_tools": ["generate_text"],
    "mcp_servers": [
      {
        "id": "company-database",
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres"],
        "env": { "POSTGRES_CONNECTION_STRING": "{{db_connection_string}}" }
      }
    ]
  }
}

You can also point an entry at a shared MCP server in the registry instead of inlining it — { "registry_id": 5 } — which keeps the command and secrets centrally managed.

How MCP tools appear in the ReAct loop

When the agent task starts, it connects to each configured server, lists its tools, and adds them to the LLM's tool list namespaced as serverId::toolName (e.g. company-database::query) to avoid collisions. From there they behave like any built-in tool in the ReAct loop:

1. The model reasons and emits a tool call, e.g. company-database::query with arguments.
2. The agent routes the call to the matching MCP server and awaits the result.
3. The result is fed back as an observation; the model reasons again until it can answer.

Every MCP tool call is audited (agent ID, tool name, sanitized arguments, status, latency). Connections are opened for the run and closed when it finishes.

MCP as a single workflow step

If you don't need a full agent, a workflow can call one MCP tool directly with the mcp_tool_task node — useful to drop an MCP tool alongside extraction, email_send_task, etc. It takes the server config (inline or registry_id), the tool_name, and arguments:

{
  "task_type": "mcp_tool_task",
  "config": {
    "mcp_server": { "registry_id": 5 },
    "tool_name": "query",
    "arguments": { "sql": "SELECT count(*) FROM customers" }
  }
}

Security

• Agents only reach MCP servers explicitly configured on them — no implicit discovery.
• Credentials are encrypted at rest, resolved at runtime, never logged or returned in results.
• stdio servers run as isolated subprocesses launched by the agent; remote transports (SSE / HTTP), once available, are subject to network egress policy.

Reference

• Agent ReAct loop and tools: Agents concept.
• Integrations, credentials, and OAuth: Integrations concept.
• Agent config and the mcp_servers field: Agent API.