Integrating with your application

Using Coral Server from, and integrating it with your application

This page is up to date, and intended for version 1.0 of the Coral Server and Coral Studio.

Deploying Coral Server

The first step to integrating Coral Server with your application is having a proper deployment of it. Exactly how you manage & deploy it depends on your application, but we offer a docker image for Coral Server, and support orchestrating agents via Docker.

Docker (recommended)

Coral Server looks for a config.toml file & registry.toml file in the paths provided to it via the CONFIG_FILE_PATH & REGISTRY_FILE_PATH environment variables respectively. When running from our provided docker image these path default to /config/config.toml//config/registry.toml when unset.

For that reason - the easiest way to configure Coral Server, is by creating a config folder & mounting that to /config when running:

# create your config dir, that our config.toml & registry.toml will live inside
mkdir my-config

touch my-config/config.toml # create empty files for now
touch my-config/registry.toml

# and mount my-config when running
docker run -p 5555:5555 -v ./my-config:/config ghcr.io/coral-protocol/coral-server:latest

Our provided docker image is very minimal! This means you should not (and usually can’t) run agents through the executable runtime - and should use Docker orchestration instead.

This is intended, as Docker orchestration is more stable, reproducible & portable - well suited for production.

See Docker in Docker for steps to support Docker orchestration from inside Docker

Java

Clone the repo and build the jar file:

git clone https://github.com/Coral-Protocol/coral-server.git
cd coral-server

./gradlew build --no-daemon -x test
# the resulting .jar will end up in build/libs/coral-server-[..].jar

Coral Server looks for a config.toml file & registry.toml file in the paths provided to it via the CONFIG_FILE_PATH & REGISTRY_FILE_PATH environment variables respectively. When unset, these paths default to ./src/main/resources/config.toml & ./src/main/resources/registry.toml, for convenience during development.

In production, we recommended you set CONFIG_FILE_PATH & REGISTRY_FILE_PATH to somewhere more easily accessible (and not in the cloned repo folder):

# make a folder outside of the repo folder, that our application.yaml will live inside
mkdir ../coral-config/

# and point at that folder when running Coral Server
export CONFIG_FILE_PATH=../coral-config/config.toml
export REGISTRY_FILE_PATH=../coral-config/registry.toml
java -jar "<name of jar file>"

You should also consider writing a systemd service (or something similar) that runs your jar file for more reliable deployments.

Using Coral Server

In production, the only ways you should be interfacing with Coral Server - is through the Coral Server API directly (not Coral Studio!).

An API reference is available at http://localhost:5555/v1/docs (assuming you are running a server locally).

Creating Sessions

The create session endpoint is one of the most important endpoints - it’s how you define and instantiate graphs of agents. While Coral Studio has a ready-made interface over this endpoint, when integrating Coral with your application, you’ll want to use this API directly.

You can use the JSON available in Coral Studio’s ‘Export’ tab when creating a session - to quickly get a usable request body for your own POST to /api/v1/sessions.

Custom Tools

There are a lot of scenarios where agents need to be given capabilities that are tightly integrated with your application. While you can hardcode these kinds of tools in agents you write yourself, when using agents from other developers - this doesn’t work.

For this reason, Coral Server supports passing custom MCP tools to agents at runtime.

When an agent calls one of these custom tools, Coral Server sends a request to an endpoint you provide, to know how to respond.

Example - User Input

A common use case in applications is exposing some kind of “chat”-style agent to your end users. This can be implemented using custom tools.

Coral Studio implements this exact use case for easy local development. Feel free to browse the source code for an example implementation.

You’ll need to implement two tools, one to allow the agent to request input from the user, and one to respond to the user’s request.

Coral Studio calls these tools request-question and answer-question.

As an example, the flow for Coral Studio’s request-question tool looks (roughly) like: