Skip to main content

Custom Tools & MCP Servers

Extend agents with your own tools — either by defining a webhook tool that points at any HTTP endpoint, or by registering a Model Context Protocol (MCP) server that exposes a whole catalog of tools at once.

Use this when:

  • You want the agent to call an internal API that isn't covered by the bundled agent tool integrations.
  • You're standing on top of an MCP server that already exposes the integration you need.
  • You want to wrap a multi-step internal workflow as a single named tool the agent can call cleanly.

Custom webhook tools​

A custom webhook tool is just an HTTP endpoint and a parameter schema. The agent calls it like any built-in tool; ZenSearch translates that into an outbound HTTP request to your endpoint, sends the parameters as the body (or query string), and returns the response back to the agent.

Defining a tool​

In the team admin dashboard, open Custom Tools → Create:

FieldDescription
NameSnake-cased name the agent uses to call the tool, e.g. lookup_customer_account.
DescriptionWhat the tool does, in agent-friendly language. The model uses this to decide when to call it.
MethodGET, POST, PUT, PATCH, or DELETE.
URLThe endpoint to call. Path templates are supported (e.g., https://api.example.com/customers/{id}).
Authnone, api_key, basic, or custom headers. Credentials are encrypted at rest.
ParametersA JSON-schema-like definition of the parameters the agent can pass.
Request timeout0–300 s (default: 15 s).

Once saved, the tool is available to every agent in the team. To restrict it to specific agents, use the per-agent tool selector in the agent builder.

Best practices​

  1. Keep response payloads small. Anything over a few KB is wasted tokens — let the agent ask for follow-up detail rather than always returning the world.
  2. Make tool names task-shaped (escalate_ticket_to_tier_2), not endpoint-shaped (post_zendesk_v2_tickets). The model picks tools based on the name + description.
  3. Return useful errors. A 4xx/5xx with a clear message lets the agent self-correct; a generic 500 leaves it stuck.
  4. Use human approval when the tool performs writes that are non-reversible.

MCP servers​

Model Context Protocol is an open spec for exposing tools to language models. If a system you use has an MCP server, you can register it once and get all of its tools without defining each individually.

Registering an MCP server​

In the main app, open Integrations → MCP Servers → Add Server:

FieldDescription
Display NameDisplay name for the server.
Transportsse or streamable_http (both usable in any deployment), or stdio (self-hosted only — see below).
Server URLFor sse / streamable_http servers.
Command / ArgumentsFor stdio servers — the executable to launch and its arguments (one per line).
AuthenticationOptional auth (header name + API key, or bearer token) sent with each request. Encrypted at rest.
Environment VariablesPassed only to the subprocess (stdio servers in self-hosted deployments only). Saved keys are shown by name; leave a value blank to keep the stored secret, or enter a new value to replace it.

ZenSearch handshakes with the server, discovers its tool catalog, and registers each tool as if it were a custom tool. New tools added to the server appear in the next discovery cycle without further setup.

Operational notes​

  • Each MCP server runs in the team's tool registry alongside the built-in tools.
  • If two tools share a name, the explicit custom-tools and built-in-tools take precedence over MCP.
  • Server failures are surfaced to the agent as tool errors — the agent typically backs off and continues with what it has.

Limits​

  • Custom tool body size: 65 KB response cap. Larger responses are truncated with a note for the agent.
  • Custom tool concurrency: governed by the agent's overall tool-call budget (see Cost & Auto-Resume).
  • MCP transport: sse and streamable_http work in any deployment; stdio servers run a local subprocess and require a self-hosted deployment with MCP_STDIO_ENABLED=true (optionally restricted by the MCP_STDIO_ALLOWED_COMMANDS allowlist) and the binary installed and reachable.