How AIClaw Extends Agents with Custom Tools and MCP Servers

#ai #opensource #webdev #agents

Most agent demos look flexible until you need them to talk to your own systems.

That is where AIClaw takes a practical route. The project ships with a broad built-in toolset, but it also lets you extend agents through custom HTTP tools, script tools, and MCP servers without changing the core runtime.

This is not a new feature announcement. It is an existing part of the current repository that is worth a deeper look because it changes what an AIClaw deployment can actually do in day-to-day work.

The problem: built-ins are not enough

Built-in tools cover the common cases well: files, shell, browser automation, web search, web fetch, memory, session search, scheduled jobs, code interpretation, and sub-agents.

But real deployments usually need one more layer:

Call an internal HTTP API.
Wrap a small script around an existing operational workflow.
Reuse external MCP tools from another server process.

Without that layer, the agent can reason, but it cannot reach the systems that matter in your environment.

AIClaw's extension model

The current README describes AIClaw's tool system as a combination of:

built-in tools
custom HTTP tools
custom command tools
MCP server tools
skill-defined tools

In the runtime, those paths are normalized into the same execution flow.

internal/agent/tool.go builds tracked tools from the configured definitions. Built-ins get their native handlers, HTTP tools are wrapped with NewHTTPHandler, command tools use NewCommandHandler, script tools use NewScriptHandler, and MCP tools are loaded from connected servers before the model call.

That matters because extension points do not become second-class behavior. They still participate in the same execution loop, step tracking, and agent prompt assembly.

Custom tools from the web console

The current tool management UI gives you a practical authoring flow instead of requiring hand-written runtime config.

On the Tools page you can:

Create a tool with a name, description, timeout, and enabled state.
Choose a handler type.
Define the function schema that the model will see.
Bind the tool to agents that should be allowed to call it.

The form currently exposes two handler types directly in the UI:

HTTP Callback
Script

For HTTP tools, AIClaw lets you define a request URL and method, with {param_name} placeholders that are substituted from model-supplied arguments at runtime.

For script tools, the form supports:

Python
JavaScript
Shell
Go

The same page also lets you describe the function in a structured way or switch to raw JSON mode for the full function definition.

That is a useful design choice. It keeps the operational handler config and the model-visible function schema separate, which makes tools easier to tune without rewriting everything.

MCP servers as first-class runtime inputs

AIClaw also has a dedicated MCP management page.

The current MCP settings flow supports:

stdio transport
sse transport
endpoint configuration
argument lists
enabled or disabled state

The runtime API behind that page is straightforward: GET /api/v1/runtime/mcp reads the workspace MCP list, and PUT /api/v1/runtime/mcp replaces it.

The runtime side is more interesting.

internal/tools/mcp/client.go connects to each enabled MCP server, initializes the client, lists available tools, and then exposes them to the agent executor. In internal/agent/executor.go, MCP tools are connected before execution so they can be merged into the available tool set for the request.

This gives AIClaw two useful extension paths:

create narrow custom tools inside AIClaw when the integration is simple
mount an external MCP server when the tool suite already exists elsewhere

Safety and operability details that matter

The implementation is more pragmatic than flashy, and that is a good thing.

A few concrete examples from the current codebase:

HTTP tool calls use a shared HTTP client with connection pooling instead of rebuilding a client on every invocation.
Command tools apply additional safety checks on top of the normal shell safeguards, including blocking patterns like outbound shell access and risky recursive deletes.
Tool calls are wrapped as tracked steps, so custom and MCP-backed calls show up in the same execution timeline as built-ins.
The MCP manager is reused at the executor level instead of being torn down after every request.

These are not marketing details. They are the difference between "extensible in theory" and "usable under load".

A practical workflow

If you want to extend an AIClaw agent today, the workflow is roughly:

Start with the smallest possible integration.
If the system is just one API call, create a custom HTTP tool.
If the integration needs local logic, wrapping, or formatting, use a script tool.
If you already have a larger tool surface implemented elsewhere, register it as an MCP server.
Attach only the needed tools to the target agent.
Inspect the execution log after real runs to verify the tool contract is clear enough for the model.

A good example is an internal support workflow:

one HTTP tool for looking up a ticket by ID
one script tool for normalizing the raw result into a concise summary
one MCP server for a broader internal knowledge or operations toolkit

That combination keeps the default agent prompt small while still giving the agent a path into real systems.

Why this matters

The strongest agent products are not the ones with the longest built-in tool list. They are the ones that let you adapt the tool surface to your own environment without fighting the runtime.

AIClaw's current design gets that mostly right: