The AI Tool Builder: Connect Any API by Pasting Credentials and Chatting

Macha's AI Tool Builder is the answer to that gap. You describe the API you want to connect, paste your credentials, and Macha's AI discovers the endpoints, tests them against the live API, and turns the successful calls into agent-ready tools — automatically. No OpenAPI spec to hunt down, no middleware to deploy, no glue code. It works with any REST API that authenticates by API key, bearer token, or basic auth.

This post is a deep dive on how it works, where the manual path is still better, and the guardrails that keep a custom tool from doing something it shouldn't. Macha is the AI agent layer that sits on top of the helpdesk you already run — Zendesk, Freshdesk, Gorgias, Front — so a custom tool you build here is immediately available to the agents working your live queue.

How teams give AI agents custom tools today

Before we get into Macha's approach, it's worth mapping the landscape, because "connect an API to your AI agent" can mean four genuinely different things, and the right one depends on how much engineering you want to spend.

• Native function / tool calling. At the lowest level, the model providers expose a way to hand the LLM a set of typed function schemas; the model decides which to call and with what arguments, and your code executes the call and returns the result. It's the foundation everything else is built on, but it's a developer primitive — you write and host the execution layer yourself.
• OpenAPI / Swagger spec import. Several agent platforms let you upload an API's OpenAPI (Swagger) specification and turn each endpoint into an action. Microsoft's Copilot Studio works this way: you extend an agent with tools from a REST API by uploading an OpenAPI specification that defines the endpoints, auth, and descriptions. It's clean if a current, accurate spec exists — and for a lot of internal and regional APIs, one simply doesn't.
• The Model Context Protocol (MCP). MCP, the open standard Anthropic introduced in late 2024, lets an agent discover and call tools exposed by an MCP server at runtime. It's powerful and increasingly common, but it presumes a server exists for the system you care about — and where one doesn't, the usual move is to generate an MCP server from an OpenAPI document, which lands you back at "you need a spec and somewhere to run the bridge."
• Unified-API platforms. Aggregators (think Merge, Nango, or vertical equivalents) give you one normalized API across many SaaS products. Great when your target is a popular SaaS app they already cover; no help at all for the bespoke service nobody aggregates.

Every one of these is a legitimate pattern, and Macha's own native integrations cover the common SaaS surface the way a unified-API platform would. The gap they all share is the long tail: the homegrown loyalty service, the regional payments provider, the internal warranty lookup — systems with a REST endpoint but no spec, no MCP server, and no aggregator coverage. That long tail is exactly what the AI Tool Builder is built for, and its bet is to skip the spec entirely.

The two ways to add a tool

Macha gives you two paths to the same destination — a working, typed tool your agents can call:

1. The AI Tool Builder — a conversation. Describe the API, paste a key, let Macha find and build the endpoints for you.
2. The manual editor — a form. Define the URL, method, parameters, body template, and auth by hand when you want exact control.

They share the same plumbing, so you can start a tool with the builder and refine it in the editor, or vice versa. Both live on the Custom Tools page, and both produce tools that show up in the same tool picker as Macha's built-in connectors.

How the AI Tool Builder works

The builder is the headline feature, and it's genuinely a different way to integrate an API. Here's the flow, step by step.

1. Describe the API in plain language

You open the builder and tell it what you're connecting — "Connect our ShipStation account so agents can look up shipment status and tracking," or "I want to read and update records in our internal warranty API." You don't need an integration guide open; you need to know roughly what the API does and where its base URL lives.

2. Paste your credentials

When the builder needs to authenticate, you paste the key. Macha supports the three auth schemes that cover the overwhelming majority of REST APIs:

• API key (header or query parameter)
• Bearer token
• Basic auth (username/password)

The clever part is what the changelog calls smart auth handling: credentials are captured from a successful test request and then applied to every other tool the builder creates in that same session. You paste once; the builder reuses it across the whole connector. And credentials are encrypted at rest — in the edit modal you only ever see a masked hint of the key, enough to confirm which key is configured without exposing the secret.

3. The AI discovers and tests endpoints

This is the step that separates the AI Tool Builder from a fill-in-the-form integration. Macha doesn't just write down what you said — it calls the API. It proposes endpoints, fires real test requests, reads the responses, and keeps the ones that come back clean. A tool that fails its test doesn't get created on a guess; the builder learns from the actual response shape. By the time the conversation ends, every tool it hands you has already proven it works against the live system.

4. Tools are grouped and typed automatically

When the builder finishes, it doesn't leave you with a flat pile of endpoints. Two things happen automatically:

• Auto-grouping. The new tools are organized under a single named connector, complete with an emoji icon and brand color, so your ShipStation tools sit together under a "ShipStation" group rather than scattered through your tool list. That group then appears on your Connectors page alongside Zendesk, Shopify, and the rest — a custom integration that looks and behaves like a first-party one.

• Auto-detected write protection. Macha inspects the HTTP method. Anything that mutates data — POST, PUT, PATCH, DELETE — is automatically flagged as a write operation that requires confirmation, while read-only GET calls are free to run. You don't have to remember to lock down the dangerous ones; the builder defaults to safe.

When to use the manual editor instead

The conversational builder is the fast path, but the manual Custom Tools editor exists for good reasons, and for some jobs it's the better choice. Reach for it when:

• You need exact control over the request. Maybe the endpoint takes a body template with specific field mappings, or query parameters that must be formatted just so. The editor lets you define the URL, HTTP method, URL parameters, body template, and authentication directly.
• The API has quirks the discovery step can't infer — an unusual pagination scheme, a non-obvious required header, a response you want to shape before the agent sees it.
• You're editing an existing tool. Open any tool to adjust its parameters, swap a key (you'll see the masked hint of the current one), or fix a description.

A couple of quality-of-life touches make the manual path less tedious than custom-tool builders usually are. Empty optional parameters are stripped from the request URL automatically, so APIs that reject empty query values (?status=) don't throw errors. And you can delete a tool inline from the list without opening the editor.

Test before you ship

Whichever path you take, you can test the endpoint from inside the editor before assigning the tool to any agent. This matters: a custom tool is only useful if it reliably returns what the agent expects, and you want to find a broken request while you're configuring it — not when a customer is waiting on a reply. The builder tests automatically; the manual editor gives you a test button. Either way, nothing reaches a live agent untested.

A worked example: an internal warranty lookup

Picture a hardware brand whose warranty data lives in an internal service with a REST API — no off-the-shelf connector exists. Here's how it comes together:

1. Open the AI Tool Builder and say: "Connect our warranty API at https://warranty.internal.example.com. Agents need to look up a warranty by serial number and create a warranty claim."
2. Paste the bearer token when prompted. Macha runs a test GET /warranties/{serial}, sees a clean response, and keeps the credential for the session.
3. The builder proposes two tools — get_warranty (a GET, left runnable) and create_warranty_claim (a POST, auto-flagged as a write that requires confirmation).
4. Both land under a new "Warranty" connector group with an icon, visible on the Connectors page.
5. You assign the get_warranty tool to your triage agent so it can enrich tickets with coverage status, and reserve create_warranty_claim for an agent that runs with explicit confirmation.

Now, when a customer writes "my blender died, here's the serial," the agent reads the serial off the ticket, calls get_warranty, and replies with real coverage status — and can offer to file the claim, pausing for confirmation before it writes. That whole loop took a chat and a pasted key, not a sprint.

How custom tools fit Macha's agents

A tool is only half the story; the other half is the agent that decides when to call it. In Macha you assign custom tools to agents the same way you assign built-in ones, alongside your knowledge sources, triggers, and sub-agents. The agent's model reads the ticket, decides a tool is needed, calls it, reads the result, and acts. Custom tools also flow through the same safety model as everything else — write operations require confirmation, and tool-call progress streams live in the status log so you can watch "Using Get Warranty" happen in real time.

Because custom tools sit next to Macha's native integrations, you can mix them freely: an agent might read a ticket in Zendesk, look up the order in Shopify, and hit your custom regional-payments API in a single resolution. The agent doesn't care which tools are first-party and which you built in a five-minute chat.

Watch-outs: when not to reach for a custom tool

Custom tools are powerful, which is exactly why a few honest caveats matter.

• A native connector beats a custom tool when one exists. If Macha already has a Shopify, Stripe, or Zendesk integration, use it — native connectors handle OAuth, token refresh, pagination, and edge cases that a hand-built REST tool won't. Build custom tools for the systems Macha doesn't cover, not as a substitute for the ones it does.
• REST and the three supported auth schemes are the boundary. The builder targets REST APIs authenticating with API key, bearer token, or basic auth. An API that needs a full OAuth authorization-code dance, request signing, or a non-REST protocol is out of scope for the builder.
• The AI's discovery is a starting point, not gospel. It tests what it proposes, but you should still review the generated tools — names, descriptions, and especially which calls got flagged as writes — before turning an agent loose. The confirmation-on-write default is your seatbelt; keep it on.
• There are plan limits. Custom API tools are a paid-plan capability — the Professional plan includes a set number of custom API tools and Enterprise includes more. Check the pricing page for the current limits if you're planning a stack of them.
• Running the tool costs credits like any agent action. Building and testing a tool is configuration, but every time a live agent calls it, that's part of an AI response — billed per action (default GPT-5.4 Mini = 1 credit, more for heavier models). Tools that fire on every ticket add up; scope them to the agents and triggers that actually need them.

How this compares to the usual approach

Set the AI Tool Builder against the four patterns above and the contrast is sharp. The spec-import route — Microsoft's Copilot Studio, for instance, requires you to upload an OpenAPI specification (it even expects a v2 Swagger file and converts v3 down to it) — assumes a current, accurate spec exists. The MCP route assumes a server exists, or that you'll generate one from that same OpenAPI document and host the bridge. Native function calling assumes you'll write the execution layer yourself. All of them are sound engineering. All of them stall on the same prerequisite: a spec, infrastructure, and a clear picture of every endpoint before you start.

Macha's bet is different: start from a description and let the AI do the discovery and testing. You bring intent and a credential; it brings the endpoint legwork and the live test calls. For the long tail of internal and regional APIs that no vendor will ever build a connector for, that's the difference between "we'll get to it next quarter" and "done before this ticket is closed." And unlike a generic automation tool, the result lands inside the agent that's already working your helpdesk queue — not in a separate workflow you have to wire back in.

If you'd rather skip the conversation and define everything by hand, the companion piece — Building Custom API Tools: connect any REST API to your agent — walks the manual editor end to end.

FAQ

What kinds of APIs can the AI Tool Builder connect? Any REST API that authenticates with an API key (header or query), a bearer token, or basic auth. You describe the API, paste the credential, and Macha discovers and tests the endpoints.

Do I need an OpenAPI or Swagger spec? No. That's the point of the conversational builder — it discovers and tests endpoints from your description and a working credential, rather than requiring you to upload a spec up front.

Are my credentials safe? Credentials are encrypted at rest, and in the editor you only see a masked hint of the key — enough to confirm which one is configured without exposing the secret. The builder captures the key from a successful test request and reuses it across the tools in that session.

How does Macha stop an agent from doing something destructive? Any tool using POST, PUT, PATCH, or DELETE is automatically flagged as a write operation that requires confirmation before it runs. Read-only GET tools run freely. You can review and adjust these flags before assigning a tool.

Can I edit a tool after the AI builds it? Yes. Every generated tool opens in the manual Custom Tools editor, where you can change the URL, method, parameters, body template, or auth, and re-test before assigning it to an agent.

Which plans include custom tools and the AI Tool Builder? Custom API tools and the AI Tool Builder are paid-plan features — Professional and Enterprise include them, with different limits on how many tools you can create. See the pricing page for current details.

Try it

If your stack has even one system Macha doesn't connect to out of the box, the AI Tool Builder is the fastest way to close that gap. Start a 7-day free trial, no credit card required, open the Custom Tools page, describe your API, and paste a key — you'll have a tested, agent-ready tool in minutes. Read the Custom Tools docs for the full walkthrough, or browse what's already built-in before you build your own.

Written by Abbas (Customer Support & AI, Macha) · Reviewed by Ankeet Guha (Co-founder & CTO) · Published 2026-06-24 · Last updated 2026-06-24.