App tools and triggers

An agent on a self-hosted deployment can use several kinds of capability. Some work with no extra setup. Connecting to third-party apps needs a gateway. This page explains which is which.

Works without extra setup

• Built-in Agenta tools. Available on every deployment.
• Schedule triggers. Run an agent on a time schedule (for example, every morning). These read from your own database and need no third-party service.

Connect an MCP server

An agent can use tools from an external MCP (Model Context Protocol) server over HTTP. You connect the server to a project with its URL and, if it needs one, a credential. This does not go through Composio. For the steps in the app, see Add an MCP server.

Since v0.119.0, the agent's sandbox does not call the MCP server itself. Every MCP call an agent makes goes to the api container, which relays it to the server. The server's credential stays on your deployment. AGENTA_MCP_GATEWAY_ENABLED controls this and is on by default.

Two consequences for a self-hosted deployment. The api container, not the runner, is the one that has to reach the MCP server. And the relay applies its own outbound guard, which is a different setting from the one that governs webhooks.

A public https:// MCP server works with no configuration.

Use an MCP server on a private network or over plain HTTP

Applies when the MCP server's URL is http:// rather than https://, or when its address is on a private network (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback, link-local, or in RFC 6598 shared address space. It does not apply to a public https:// server.

Two settings decide whether such a server works. The first answers both the save-time and the call-time question. The second is a narrower exemption, checked before it.

Setting	Read by	Question it answers
AGENTA_GATEWAYS_INSECURE_EGRESS_ALLOWED	api	May this URL be saved, and may the relay call it during a run?
AGENTA_MCP_GATEWAY_HOST_ALLOWLIST	api	Which hostnames skip that guard entirely?

Pick the posture that matches your deployment.

Posture 1: nobody untrusted can create MCP connections

This is the posture the four Docker Compose env templates ship:

AGENTA_GATEWAYS_INSECURE_EGRESS_ALLOWED=true

One setting covers both steps. The URL saves, and the relay calls the server during a run, whether the server is on a private address or answers over plain HTTP.

On 0.119.0 only, the save-time check read AGENTA_INSECURE_EGRESS_ALLOWED instead, so on that version a .gh deployment refused the save with a 400 even with the line above set. Upgrade to 0.119.1 rather than widening that webhook setting.

Recreate the api container so it reads the change:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml \
  --env-file hosting/docker-compose/oss/.env.oss.gh up -d api

Posture 2: people you do not trust can create MCP connections

Leave AGENTA_GATEWAYS_INSECURE_EGRESS_ALLOWED=false. With open egress, any project can point an MCP connection at an address inside the network the api container sits on, and the relay will dial it.

Name the one server you want reachable instead. AGENTA_MCP_GATEWAY_HOST_ALLOWLIST takes comma-separated hostnames, with no scheme and no port. A hostname on that list skips the guard while the guard stays on for every other target:

AGENTA_GATEWAYS_INSECURE_EGRESS_ALLOWED=false
AGENTA_MCP_GATEWAY_HOST_ALLOWLIST=mcp.internal

The allowlist is checked first, before any scheme or address check, and it covers both steps. At save time, a URL whose hostname is on the list is accepted whatever its scheme, so both https://mcp.internal:8443 and http://mcp.internal:8080 are saved. At call time, the relay dials such a host as written, with no address check and no resolve-and-pin, so the plain-HTTP URL is called too. For the hosts on it, the allowlist drops the HTTPS requirement as well as the private-address one.

Every URL whose hostname is not on the list follows AGENTA_GATEWAYS_INSECURE_EGRESS_ALLOWED. With that at false, https://10.0.0.5:8443 is refused at save time, as a literal private IP address. A hostname that is not a literal IP address, such as https://other.internal:8443, saves anyway, because the save-time check resolves no hostnames. It is refused later, at call time, once the name resolves to a private address.

Errors you will see

blocked target: Upstream URL must use https. during a run. The relay refused an http:// server. Allow it with AGENTA_GATEWAYS_INSECURE_EGRESS_ALLOWED=true, or put the server's hostname in AGENTA_MCP_GATEWAY_HOST_ALLOWLIST.

blocked target: Upstream URL resolves to a blocked IP range. during a run. The server's hostname resolved to a private, loopback, link-local, reserved, multicast or RFC 6598 address. Same two fixes. This one fires at call time rather than at save time, so a public hostname that resolves to an internal address reaches it too.

endpoint.data.route.base_url is invalid: URL must use https. with a 400 when saving. The save-time check refused the URL. Set AGENTA_GATEWAYS_INSECURE_EGRESS_ALLOWED=true, or put the server's hostname in AGENTA_MCP_GATEWAY_HOST_ALLOWLIST. On 0.119.0 this check read AGENTA_INSECURE_EGRESS_ALLOWED instead.

gateway_insecure_endpoint during a run. Unrelated to the MCP server's address. It means your own Agenta deployment is reached over plain HTTP at a non-loopback address, so Agenta will not send the run its gateway credential. See Reaching the gateway over plain HTTP.

App tools and event triggers need Composio

Connecting an agent to a third-party app goes through Composio, a tool gateway. This covers two things:

• App tools. Letting an agent act in an outside app, such as opening a GitHub issue or sending a Slack message.
• Event triggers. Letting an outside app start a run, such as a new GitHub issue firing your agent. This is different from a schedule trigger, which is time-based and needs no gateway.

Without a Composio API key, these are unavailable. Tool and trigger discovery (discover_tools, discover_triggers) returns 404, because the gateway they route through is not configured.

To enable them, set a Composio API key. Composio has a free tier; create an account, get a key, then add it to your env file:

COMPOSIO_API_KEY=your-composio-api-key

Recreate the stack so the API picks it up:

docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml \
  --env-file hosting/docker-compose/oss/.env.oss.gh up -d

See Configuration for the full list of Composio variables.

Code tools are disabled

The runner does not run custom code tools (an agent shelling out to gh or curl, for example). This is a security decision, not a configuration you can turn on. To let an agent act in an outside service, use an app tool through Composio instead.