> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Give agents tools through vaults and tool bundles: MCP servers, custom tools, the DataGen MCP gateway, workspace data tools and code mode

An agent can call the tools in its **tool bundle**. A tool bundle is an allowlist inside a **vault**: the vault holds the credentials (MCP servers and secrets), and the bundle picks which of the vault's tools an agent may use. Pick the vault and bundle on the agent, and every run gets exactly those tools, authenticated with that vault's credentials.

| Tool source | What it is | Where it comes from |
| - | - | - |
| **Default** | Built-in tools that need no external credential | Available in every vault |
| **MCP** | Tools from a remote MCP server (Slack, Linear, Gmail, your own server...) | An MCP credential in the vault |
| **Custom** | Deterministic Python workflows you deploy as tools | [Custom tools](#custom-tools) |
| **DataGen MCP gateway** | `searchTools`, `getToolDetails`, `executeToolCall` | The **Enable DataGen MCP** switch on the agent |
| **Workspace data tools** | Read-only access to workspace files, earlier outputs and connected knowledge bases | The **Enable workspace data tools** switch on the agent |

***

## How an agent gets its tools

<Steps>
  <Step title="Add credentials to a vault">
    Open **Connection Vaults** in the sidebar, open a vault, and add MCP servers and secrets on its **Credentials** tab. See [Add an MCP server](#add-an-mcp-server).
  </Step>

  <Step title="Create a tool bundle">
    On the vault's **Tool Bundles** tab, create a bundle and choose its tools, or turn on **Allow all tools in this vault**. See [Tool bundles](#tool-bundles).
  </Step>

  <Step title="Point the agent at them">
    In the builder's **Config** tab (or the agent's **Settings** tab, **Vault & Tool Bundle**), choose the **Vault** and **Tool bundle**. The bundle list only shows bundles in the selected vault.
  </Step>

  <Step title="Check the result">
    The agent's **Tools** tab shows the bundle that actually applies, the vault its credentials come from, and every tool grouped as **Default**, **MCP** and **Custom**. Each MCP tool shows whether it authenticates with a shared or per-user credential.
  </Step>
</Steps>

If the agent has no vault or bundle selected, it uses the workspace default vault and that vault's default bundle. Changes apply from the agent's next turn.

***

## Add an MCP server

MCP servers give agents access to external services such as Gmail, Linear, Slack and HubSpot. You connect a server once, as a credential in a vault, and every agent using that vault can reach it.

### From the MCP Registry

Open the vault, go to the **MCP Registry** tab, and click **Connect** on a server. OAuth servers open a sign-in popup; when you approve, the row shows as connected.

### Any MCP server by URL

<Steps>
  <Step title="Add credential">
    On the vault's **Credentials** tab, click **Add credential** and choose **MCP server**.
  </Step>

  <Step title="Fill in the server">
    Enter a name, the server URL (for example `https://mcp.example.com/mcp`) and the **Auth method**: **OAuth**, **Bearer token**, **API key** or **No authentication**.
  </Step>

  <Step title="Choose shared or per-user">
    **Shared with workspace**: an admin provides one value and everyone uses it without seeing it. **Per-user**: each member connects their own account from the row's **Connect** button. OAuth is always per-user.
  </Step>

  <Step title="Sync its tools">
    DataGen lists the server's tools when you save. Use **Refresh tools** to re-sync the tool catalog for every MCP server in the vault.
  </Step>
</Steps>

See [Vault](/foundation/vault) for credential types, rotation and egress policies.

### Commonly used MCP servers

* **Notion** -- `https://mcp.notion.com/mcp`
* **Linear** -- `https://mcp.linear.app/sse`
* **Neon** -- `https://mcp.neon.tech`
* **Open-source servers** -- [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)
* **Your own systems** -- build a server with the MCP SDK and add it by URL

### From Claude Code

With the DataGen plugin installed, run:

```
/datagen:add-mcps
```

It checks DataGen's built-in server templates, connects the server (running the OAuth flow if needed), and lists the new tools. You can also ask Claude directly, for example `"Add Linear MCP to DataGen: https://mcp.linear.app/sse"`, and it calls `addRemoteMcpServer` for you.

***

## Tool bundles

A tool bundle is an allowlist of tools that authenticate with one vault's credentials.

* Click **New tool bundle** on the vault's **Tool Bundles** tab and name it, for example `read-only`.
* Pick its members from the vault's tools, grouped as Default, MCP and Custom.
* Or turn on **Allow all tools in this vault**: every default tool, MCP server tool and custom tool in the vault is included, and tools added later are included automatically.

Each bundle also has an **MCP URL**, so MCP clients outside DataGen can use the same allowlist. **Rotate MCP URL** revokes the current URL immediately.

<Tip>
  Create a narrow bundle per kind of agent -- for example one bundle with only reporting tools, another with write access to your CRM -- instead of giving every agent **Allow all tools in this vault**.
</Tip>

***

## DataGen MCP gateway

Turn on **Enable DataGen MCP for this agent** (builder **Config**, or the agent's **Settings** tab) to attach the DataGen MCP gateway to the agent's runs. The agent can then discover and call tools on demand with `searchTools`, `getToolDetails` and `executeToolCall`. It is off by default, applies from the next turn, and does not change the other MCP servers the agent loads.

## Workspace data tools

**Enable workspace data tools for this agent** (builder **Config**, or the agent's **Data access** tab) lets the agent list, read and fetch the workspace's raw files, its own earlier outputs and its connected knowledge bases on demand, beyond what is copied into the sandbox at run start. The tools are read-only: the agent can never write or delete through them, and other agents' files and other members' personal files stay private. They are on by default.

If the agent has a **Data scope**, the tools only return raw data inside it; with the tools off, a scoped agent cannot read any raw data. See [Build an agent](/agents/build#knowledge-and-data).

## Calling other agents

On the **Data access** tab, **Agents it can call** lists agents this agent may start a turn on with `datagen-assets invoke`. Each call runs as the person the agent is running for, needs that person to be allowed to run the target agent, and needs the target to be enabled. A called agent cannot call further agents.

***

## Custom tools

Custom tools are deterministic Python workflows that help your agents with fast, reliable operations. Instead of letting the agent work out multi-step logic each time, you package it as a tool: same input, same output, every time.

A deployed custom tool appears on the **Tools** page under **Custom Tools**, can be added to tool bundles, and is callable from agents, Claude conversations and the REST API.

<Tip>
  **Using Claude Code?** Run `/datagen:create-custom-tool` for a guided workflow that designs the schema, implements and tests the code, and deploys it.
</Tip>

### Write the code

Call MCP tools as Python functions with the DataGen SDK:

```python theme={null}
from datagen_sdk import DatagenClient

client = DatagenClient()

issues = client.execute_tool("mcp_Linear_list_issues", {
    "filter": {"state": {"name": {"eq": "In Progress"}}}
})

active_count = len(issues)
result = f"Found {active_count} active issues"
```

**Input schema.** Define the parameters the tool accepts with JSON Schema:

```json theme={null}
{
  "type": "object",
  "properties": {
    "campaign_id": {"type": "string", "description": "The campaign ID to analyze"},
    "days": {"type": "integer", "description": "Number of days to look back", "default": 30}
  },
  "required": ["campaign_id"]
}
```

**Output variables.** List the variables your code assigns; they become the tool's return values:

```python theme={null}
result = {"total_leads": 150, "conversion_rate": 0.12}
summary = "Campaign performed above average"
# Output variables: ["result", "summary"]
```

**Dependencies.**

| Type | Description | Example |
| - | - | - |
| **MCP servers** | Which MCP servers the code calls | `["Linear", "Gmail"]` |
| **Secrets** | Environment variables the code needs | `["OPENAI_API_KEY"]` |
| **Imports** | Python packages to import | `["pandas", "httpx"]` |

### Test and deploy

1. **Test** the code in a sandbox first: ask Claude to run it, and it calls `executeCode`.
2. **Deploy** it: ask `"Deploy this as a custom tool called 'analyze_campaign'"`, and Claude calls `createCustomTool` with your code, schema and dependencies.
3. **Run** the deployed tool: `"Run my analyze_campaign tool with campaign_id='abc123'"` calls `submitCustomToolRun`; `checkRunStatus` returns the state and output.

To change a tool later, ask Claude to update it (`updateCustomTool`), or find your tools with `searchCustomTools`.

From the terminal:

```bash theme={null}
datagen tools list
datagen tools show <uuid>
datagen tools run <uuid> --input '{"campaign_id": "abc123"}'
```

See [CLI](/developers/cli) and [MCP Tools](/developers/mcp-tools) for every option.

<AccordionGroup>
  <Accordion title="Example: lead enrichment tool">
    ```python theme={null}
    from datagen_sdk import DatagenClient

    client = DatagenClient()

    enriched = []
    for domain in input_domains:  # from the input schema
        research = client.execute_tool("mcp_Perplexity_search", {
            "query": f"What does {domain} do? Who are the founders?"
        })
        enriched.append({"domain": domain, "description": research.get("answer")})

    result = enriched
    total_enriched = len(enriched)
    ```

    Input schema: `input_domains` (array of strings, required). Output variables: `["result", "total_enriched"]`. MCP servers: `["Perplexity"]`.
  </Accordion>

  <Accordion title="Best practices">
    * **Keep tools focused.** One tool, one job.
    * **Use descriptive names.** `enrich_company_data`, not `tool1`; good descriptions help agents pick the right tool.
    * **Handle errors.** Catch `DatagenToolError` around tool calls and return a clear message.
    * **Test before deploying.** Run with `executeCode` first; deployed tools are harder to debug.
  </Accordion>
</AccordionGroup>

***

## Code mode

Code mode means writing a Python or TypeScript script that calls MCP tools through the DataGen SDK, instead of calling them one at a time in a conversation. Use it for batch processing, complex logic and production jobs.

<Tip>
  **Using Claude Code?** Run `/datagen:code-mode` for guided scripting with tool discovery and large-output handling.
</Tip>

**Rule of thumb:** fewer than 5 tool calls with small results, call the tools directly. More calls, large data or complex logic, write a script.

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install datagen-python-sdk
    export DATAGEN_API_KEY="your_api_key_here"
    ```

    ```python theme={null}
    from datagen_sdk import DatagenClient, DatagenToolError

    client = DatagenClient(retries=3, backoff_seconds=1.0)

    sent, failed = [], []
    for contact in contacts:
        try:
            client.execute_tool("mcp_Gmail_gmail_send_email", {
                "to": contact["email"],
                "subject": "Welcome!",
                "body": f"Hi {contact['name']}, thanks for signing up!",
            })
            sent.append(contact["email"])
        except DatagenToolError as e:
            failed.append({"email": contact["email"], "error": str(e)})

    print(f"Sent: {len(sent)}, Failed: {len(failed)}")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install @datagen-dev/typescript-sdk
    export DATAGEN_API_KEY="your_api_key_here"
    ```

    ```typescript theme={null}
    import { DatagenClient } from '@datagen-dev/typescript-sdk';

    const client = new DatagenClient();

    const result = await client.executeTool(
      "mcp_Linear_list_issues",
      { filter: { state: { name: { eq: "In Progress" } } } }
    );

    console.log(`Found ${result.length} active issues`);
    ```
  </Tab>
</Tabs>

| Error | Meaning |
| - | - |
| `DatagenAuthError` | Authentication failed (401/403): check the API key or MCP connection |
| `DatagenToolError` | Tool execution failed: check the parameters |
| `DatagenHttpError` | Network or HTTP-level error |

See [Python SDK](/developers/sdk-python) and [TypeScript SDK](/developers/sdk-typescript) for every method, including deploying a script as a custom tool.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="A tool is missing from the agent's Tools tab">
    1. Check which bundle the **Tools** tab says applies; the agent may be on the workspace default.
    2. Open that bundle on the vault's **Tool Bundles** tab and add the tool, or turn on **Allow all tools in this vault**.
    3. Click **Refresh tools** on the vault's **Credentials** tab to re-sync the MCP server's tool list.
  </Accordion>

  <Accordion title="OAuth fails or times out">
    1. Allow popups for DataGen; the OAuth flow opens in a popup.
    2. Try a private window, or clear cookies for the provider.
    3. Check whether your organization blocks OAuth for the service.
    4. Click **Connect** on the credential row to run the flow again.
  </Accordion>

  <Accordion title="Permission denied from a tool">
    1. Confirm you granted every scope the provider asked for during OAuth.
    2. Some services need admin approval for certain scopes.
    3. For a per-user credential, make sure the member who triggers the run has connected their own account.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Trigger it" icon="bolt" href="/agents/triggers">
    Run now, schedules and webhooks with automations
  </Card>

  <Card title="Channels" icon="comments" href="/agents/channels">
    Slack, Teams, Discord, email, web chat and public chat links
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.