> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenovia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted tools

> Choose which tools the model provider may run for an agent, and which MCP servers it may reach.

Choose which tools the model provider may run for your agent. Web search, code execution and remote MCP servers run at the provider, out of your code's reach, so Xenovia checks them against an allow-list before the request is sent.

For example, allow only **Web search** and one MCP server, `https://mcp.example.com/sse`, with the tool `list_issues`. In Enforce, a request that asks for code execution or another MCP server is refused, and `X-Xenovia-Reason` says `policy:hosted_tools:code_execution`.

## Restrict hosted tools

The agent's **Hosted tools** tab controls the tools the model provider runs for it. Function tools your code runs are always allowed.

* With **Restrict hosted tools** off, every hosted tool the agent asks for is forwarded.
* With it on, only the types you allow under **Allowed tool types** are forwarded: **Web search**, **Web fetch**, **Code execution**, **Computer use**, **Shell**, **File search**, **Image generation**, **Remote MCP**, **Advisor** and **Other**.

Its **Mode** decides what happens to a hosted tool outside the list:

| Mode | Effect |
| - | - |
| **Enforce** | The request is refused with a `200` refusal. `X-Xenovia-Reason` is `policy:hosted_tools:<family>`, or `policy:hosted_tools:mcp:<server>` for an MCP server |
| **Monitor** | The request goes on, and the tool it would have refused is recorded on the turn |

The allow-list runs before the request-stage policies, so policies and Neon see the request as it will be sent. If the list can't be read, the request is refused with `503`. On a call to a [linked sub-agent](https://docs.xenovia.io/agents/sub-agents.md), the calling agent's list applies too.

### MCP servers

When **Remote MCP** is allowed, remote MCP calls can only reach the servers under **MCP servers**. Choose **Add server** and give it a label and one target:

| Target | Example |
| - | - |
| **Server URL** | `https://mcp.example.com/sse` (HTTPS, with no credentials, query or fragment) |
| **Connector ID** | `connector_googledrive` |
| **Tunnel ID** | `tun_123` |

**Allowed tools** narrows the server to the tools you list; leave it blank to allow every tool on the server. In **Enforce**, the runtime narrows the request's allowed tools to your list before it reaches the provider. An agent can have up to 50 servers, with up to 100 tools each.

### Set it with the API

`GET /api/v1/agents/{agent_id}/hosted-tools` returns the list, or `null` when the agent has none. `PUT` to the same path replaces it, and a JSON `null` body removes it:

```json theme={null}
{
  "mode": "enforce",
  "families": ["web_search", "mcp"],
  "mcp_servers": [
    { "label": "issues", "url": "https://mcp.example.com/sse", "tools": ["list_issues"] }
  ]
}
```

`families` takes `web_search`, `web_fetch`, `code_execution`, `computer`, `shell`, `file_search`, `image_generation`, `mcp`, `advisor` and `other`. A server takes exactly one of `url`, `connector_id` or `tunnel_id`. Server lists are kept when `mcp` is not in `families`, but no MCP tool is allowed then. For a coding agent, only `web_search`, `web_fetch`, `shell` and `mcp` apply, and a server is named by its label from the tool's MCP settings.

## How tools are checked

Most agent risk comes from tool use, not text generation. Xenovia sees the tools an agent declares and the calls a model makes, and governs them in three ways: the allow-list on this page for tools the provider runs, [policies](https://docs.xenovia.io/control/policies.md#examples) on tool names and calls, and [Neon](https://docs.xenovia.io/control/neon.md) on tool calls and their results.

### Tools your code runs

When your app sends a `chat/completions`, `responses` or `messages` request, the tool **definitions** you pass are visible to policy as `input.tools` and `input.tool_names`, and are recorded on the turn. When the model decides to call a tool, the **tool calls** it returns are recorded on the turn's model run, and the response-stage policy sees them as `input.output.tool_calls` (name, arguments and call ID).

Your code then runs the tool and sends the result back on the next request. That result is visible to the next request's policy as `input.tool_results`, on Chat Completions and Responses alike. Neon judges it at its **Tool result** stage. These tools are not separate runs in the trace: they live in the turn's messages and output.

### Tools the provider runs

Hosted tools, such as web search, code execution or a remote MCP server, are run by the model provider during the call. They appear in `input.tools` with their `family`, and what they returned comes back inside the reply, where Neon judges it at its **Tool result** stage. Control which ones an agent may use with the [hosted tool allow-list](#restrict-hosted-tools).

### Coding agents

For a coding agent connected through its hooks ([Claude Code](https://docs.xenovia.io/agents/coding-agents.md), [Codex](https://docs.xenovia.io/agents/coding-agents.md) or [Cursor](https://docs.xenovia.io/agents/coding-agents.md)), each tool the agent runs is recorded as its own tool run, with its input and output, on the session's turn.

To check actions your code takes on its own, such as tool calls and their results, memory writes and context summaries, use the [Xenovia SDK](https://docs.xenovia.io/sdk/quickstart.md).

## What next?

> [card] [Policies](https://docs.xenovia.io/control/policies.md)
>
> Block or allow your own tools by name.

> [card] [Neon](https://docs.xenovia.io/control/neon.md)
>
> Judge each tool call and tool result.

> [card] [Coding agents](https://docs.xenovia.io/agents/coding-agents.md)
>
> Limit the tools a coding agent may use.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.