> For the complete documentation index, see [llms.txt](https://dnotifier.gitbook.io/product-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dnotifier.gitbook.io/product-docs/workflows-and-agents/tools-and-mcp.md).

# Tools & MCP agents

Beyond classic `run(ctx)` agents, the SDKs support **tool agents**: the model can call **local tools** you register in code, or **MCP** tools from an HTTP MCP server. You define tools and instructions; the SDK runs the agent until it returns a final answer.

{% hint style="info" %}
Available in the **JavaScript**, **Python**, and **Dart** SDKs. Prefer `transport: "http"` for standalone `runAgent` / tool agents.
{% endhint %}

## Two agent styles

| Style          | How you define it                                                       | How it runs                                            |
| -------------- | ----------------------------------------------------------------------- | ------------------------------------------------------ |
| **Classic**    | `defineAgent({ name, run })`                                            | Your `run(ctx)` calls `ctx.sendAI`, `ctx.search`, etc. |
| **Tool agent** | `defineAgent({ name, tools, instructions })` (no custom `run` required) | The SDK calls tools as needed until a final message    |

Classic agents keep working unchanged. When you pass `tools` and omit a custom `run`, the SDK provides the tool-agent behavior automatically.

## Core APIs

| API                                                                                     | Purpose                                                                  |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `notifier.tools.register({ name, description, inputSchema, execute })`                  | Register a **local** tool                                                |
| `await notifier.mcp.connect({ id, name, endpoint, transport? })`                        | Connect an **MCP** HTTP server and discover tools                        |
| `defineAgent({ name, tools, instructions, permissions?, observability?, middleware? })` | Build a tool agent                                                       |
| `await notifier.runAgent(agent, { input, maxToolRounds? })`                             | Run a tool agent **outside** a workflow                                  |
| `ctx.runAgent("name")`                                                                  | Run a registered agent **inside** a workflow (tool agents work here too) |

## How a tool agent runs

```
  runAgent(agent, { input })
         │
         ▼
  Model may request tools
         │
         ▼
  SDK runs local / MCP tools
         │
         ▼
  Continues until a final answer
         │
         ▼
  { output, executionId, finishReason }
```

Use `maxToolRounds` to cap how many tool rounds a single run may take. When permission enforcement is enabled, each tool call is checked before it runs.

## Local tools vs MCP

|           | Local                       | MCP                                                            |
| --------- | --------------------------- | -------------------------------------------------------------- |
| Register  | `notifier.tools.register`   | `notifier.mcp.connect` then `connection.tools()`               |
| `execute` | Your function               | Handled by the connected MCP server                            |
| Tool name | Your `name`                 | Prefixed with the MCP server id (for example `mermaid.verify`) |
| Use case  | App logic, DB, APIs you own | Public or private MCP servers                                  |

## Permissions & events

Constructor options:

| Option                                             | Values                      | Default     | Description                                                |
| -------------------------------------------------- | --------------------------- | ----------- | ---------------------------------------------------------- |
| `permissionEnforcement` / `permission_enforcement` | `"backend"` \| `"disabled"` | `"backend"` | Check permissions before each tool runs                    |
| `onAgentEvent` / `on_agent_event`                  | callback                    | —           | Optional local events (`tool.started`, `mcp.connected`, …) |

On the agent: `permissions: { "tool.name": ["execute"], ... }` declares which tools the agent may use.

## Observability

Set `observability: true` on the agent (or on `runAgent`) to record the run in the workflow dashboard, including AI and tool steps.

## Language guides

| Language                | Guide                                                                                                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| JavaScript / TypeScript | [javascript-typescript.md](/product-docs/workflows-and-agents/tools-and-mcp/javascript-typescript.md) |
| Dart / Flutter          | [dart-flutter.md](/product-docs/workflows-and-agents/tools-and-mcp/dart-flutter.md)                   |
| Python                  | [python.md](/product-docs/workflows-and-agents/tools-and-mcp/python.md)                               |

## Examples

| Example                                                                      | Description                                             |
| ---------------------------------------------------------------------------- | ------------------------------------------------------- |
| [Local tool agent](/product-docs/workflows-and-agents/example-tool-agent.md) | Register a calculator tool and run it with `runAgent`   |
| [MCP Mermaid agent](/product-docs/workflows-and-agents/example-mcp-agent.md) | Connect a public MCP server and run a diagram assistant |

## Next steps

* [**Define an agent**](/product-docs/workflows-and-agents/define-agent.md) — classic and tool-agent fields
* [**Middleware**](/product-docs/workflows-and-agents/middleware.md) — logging, tool access, workflow guards
* [**Workflows overview**](/product-docs/workflows-and-agents/overview.md)
* [**Workflow observability**](/product-docs/workflows-and-agents/observability.md)