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
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

1. 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.

2. 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.

3. 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.

4. 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.

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

1. Add credential

   On the vault’s Credentials tab, click Add credential and choose MCP server.

2. 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.

3. 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.

4. 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.

See 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
• 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.

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.

---

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.

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.

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

Write the code

Call MCP tools as Python functions with the DataGen SDK:

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:

{
  "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:

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:

datagen tools list
datagen tools show <uuid>
datagen tools run <uuid> --input '{"campaign_id": "abc123"}'

See CLI and MCP Tools for every option.

Example: lead enrichment tool

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"].

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.

---

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.

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

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.

Python

pip install datagen-python-sdk
export DATAGEN_API_KEY="your_api_key_here"

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)}")

TypeScript

npm install @datagen-dev/typescript-sdk
export DATAGEN_API_KEY="your_api_key_here"

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`);

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 and TypeScript SDK for every method, including deploying a script as a custom tool.

---

Troubleshooting

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.

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.

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.

Next

Trigger it

Run now, schedules and webhooks with automations

Channels

Slack, Teams, Discord, email, web chat and public chat links