Skip to main content

Host your own tool server

Tools

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 imageAn app plus its spec
What you writeA server that speaks the Model Context ProtocolAny REST service with an OpenAPI spec
Where it runsA pod the platform creates for it, on one replicaAn app in App Studio, with replicas you choose
How it is registeredAdd MCP Server, Docker ContainerImport OpenAPI from the app's spec address
Where tools come fromThe server's own tool list, discovered after it startsOne tool per operation in the spec
Reachable fromAgents on this platformAgents on this platform, and anything else that can reach the app
Ports it may serveOneOne, and the app has an address of its own
WalkthroughHost a custom MCP imageHost 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.

Describes the platform as of .

Was this page helpful?