How Do You Connect Any REST API to an AI Support Agent? Macha's AI Tool Builder

Macha's AI Tool Builder connects a REST API to your support agents in one conversation: you describe the API, paste an API key, bearer token or basic-auth login, and Macha discovers the endpoints, tests them against the live API, and saves the calls that work as agent-ready tools. It shipped on 30 March 2026, needs no OpenAPI spec, no middleware and no glue code, and any tool that uses POST, PUT, PATCH or DELETE is marked as a write that needs confirmation before it runs.

Macha is the AI agent layer that sits on top of the help desk you already run (Zendesk, Freshdesk, Gorgias, Front, HubSpot or Intercom, including Zendesk), so a custom tool you build here is immediately available to the agents working your live queue. Below: how the builder works, where the manual editor is still better, and the guardrails that keep a custom tool from doing something it shouldn't.

How do teams usually give AI agents custom tools?

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 (the feature is still labelled preview): 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.

What are the two ways to add a tool in Macha?

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 does the AI Tool Builder work?

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. Macha's docs note that the builder does best when you also paste the API documentation URL or a few example endpoints.

2. Paste your credentials

When the builder needs to authenticate, you paste the key. Macha supports the three auth schemes that cover most REST APIs, plus "None" for open endpoints:

• API key (sent in a custom header)
• Bearer token (in the Authorization header)
• 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. Credentials are encrypted at rest and never exposed to the AI model. 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 should you 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.

What does a real build look like? 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 do 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.

When should you not build 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 an API key in a header, a bearer token, or basic auth. An API that needs a full OAuth authorization-code flow, 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.
• They are not a premium add-on. Custom API tools and the AI Tool Builder are on every plan. Macha sells one plan priced by ticket volume, from $299 a month for up to 750 tickets, with unlimited agents and seats and setup by the Macha team included. The pricing page lists every tier.
• Calling the tool doesn't add a line item. Macha bills per ticket — one conversation, charged once, however many tool calls the agent makes inside it — so a tool that fires three times in a thread costs no more than one that fires once. Scope tools to the agents and triggers that need them for accuracy and speed, not to save money.

How does the AI Tool Builder compare with spec import and MCP?

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. Copilot Studio does support OAuth 2.0, which Macha's builder does not, so the trade runs both ways. 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 needs no auth or authenticates with an API key in a header, 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 never exposed to the AI model, 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.

Does the AI Tool Builder support OAuth? No. It covers no-auth endpoints, API keys in a header, bearer tokens and basic auth. For systems that need an OAuth sign-in, use one of Macha's native connectors where one exists.

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? Every plan does. Macha has one plan with every feature, priced by ticket volume from $299 a month for up to 750 tickets, and there is no separate add-on. See the pricing page for current details.

How do you try the AI Tool Builder?

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 free trial ($50 of usage, no credit card, no time limit), 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-09-24.