# Host your own tool server

Two ways to put code you wrote in front of agents on your own cluster, what your image must do for each, and how to choose between them.

The tool catalog and the OpenAPI importer cover services that already exist. When the work is yours, exact rules, a lookup over your own tables, a document your agents must produce the same way every time, you write a small service and host it on the cluster. This page is the map: the two routes in, what your code has to do for each, and which one to pick. The walkthroughs are on the two pages it links to.

**Who can use it:** an **Admin** registers either kind of server, in a tenant licensed for tools. The app route also needs the model serving licence, because the app runs in App Studio.

## The two routes

| | **MCP server from an image** | **An app plus its spec** |
| --- | --- | --- |
| What you write | A server that speaks the Model Context Protocol | Any REST service with an OpenAPI spec |
| Where it runs | A pod the platform creates for it, on one replica | An app in App Studio, with replicas you choose |
| How it is registered | **Add MCP Server**, **Docker Container** | **Import OpenAPI** from the app's spec address |
| Where tools come from | The server's own tool list, discovered after it starts | One tool per operation in the spec |
| Reachable from | Agents on this platform | Agents on this platform, and anything else that can reach the app |
| Ports it may serve | One | One, and the app has an address of its own |
| Walkthrough | [Host a custom MCP image](/tools/host-a-custom-mcp-image) | [Host a tool server as an app](/tools/host-a-tool-server-as-an-app) |

## Choosing between them

**Take the MCP route** when the service exists only to be called by agents, when you want its tools to appear and disappear with the server, and when you are happy for it to be reachable from nowhere else. It is the shorter path: one dialog, no second registration.

**Take the app route** when any of these is true. Your service already speaks REST and you would rather not wrap it. You want to call it yourself, from a notebook or another system, as well as from agents. You need more than one replica, a larger size than the three tool presets offer, or storage attached. Or you need it to serve something a browser opens, a generated file for instance, which an MCP server has no way to hand back.

The app route costs you one extra thing: the spec and the tools drift apart if you change the service and forget to refresh. The MCP route rediscovers tools when the server restarts.

## What both routes need

- **An image in a registry the platform may pull from.** The MCP route accepts a fixed set of registry prefixes plus whatever your administrator configured and whatever the catalog already trusts, so an image from a personal namespace is usually refused. Push to your platform's own registry, and use a version tag rather than a floating one, so you can tell which build answered a call.
- **One listening port, and nothing else exposed.** Serve the whole surface on one port. Neither route gives you a second one.
- **No state between calls.** A tool server that remembers something from the last call will surprise you the first time it restarts.
- **Secrets as environment variables.** Both forms take them at registration. Nothing credential-shaped belongs in the image, and a few names are refused because they would let input change how the container runs.
- **Data that is read at start-up.** There is no volume to mount on the MCP route, so reference tables are either baked into the image, which makes the image as sensitive as the data, or fetched when the container starts. An app can mount storage, which is the cleaner answer when the data is large or changes often.
- **A health endpoint.** Both routes check that something is listening. A real endpoint that reports whether the data loaded tells you far more than a port check, and it is the first thing to look at when tools are missing.

## Before you register it

Decide who may call it. Both dialogs ask for access groups, and both kinds of tool appear on **All tools** with a risk, so your tool policies apply to them exactly as they apply to a catalog server. A server that reads customer records should not be reachable by every group in the tenant because it was quicker to leave the field open.

## Related

- [Host a custom MCP image](/tools/host-a-custom-mcp-image)
- [Host a tool server as an app](/tools/host-a-tool-server-as-an-app)
- [Add an MCP server](/tools/add-an-mcp-server)
- [Connect an API as a tool](/tools/connect-an-api-as-a-tool)

Source: https://docs.katonic.ai/tools/host-your-own-tool-server
