Getting Started with Trento MCP Server

This guide provides everything you need to start developing with the Trento MCP Server. It covers environment setup, project architecture, building, running, testing, and debugging.

Building the Project

Before you begin development, ensure you have the following tools installed:

Go (see Go installation guide).
Docker or Podman (for containerization).
Make (for build automation).
Git (for version control).

Using asdf for Version Management

asdf is a version manager that allows you to use specific versions of programming languages and tools that are known to be compatible with this project, rather than relying on globally installed versions.

To get started with asdf:

Follow the official asdf getting started guide to install asdf.
Install all required plugins from the project’s .tool-versions file:

cut -d' ' -f1 .tool-versions | xargs -I {} asdf plugin add {}

Install the specified versions:

asdf install

Project Overview

The Trento MCP Server is a Model Context Protocol (MCP) server implementation that enables AI tools and agents to interact with Trento infrastructure. The project automatically generates MCP tools from OpenAPI specifications, ensuring strong alignment between the API contract and implementation.

Project Structure

The project follows Go standard layout conventions:

mcp-server/
├── bin/                    # Compiled binaries
├── cmd/                    # CLI commands and entry points
│   └── root.go            # Main command definitions and flags
├── docs/                   # Documentation
├── hack/                   # Build scripts and linters
├── internal/               # Private application code
│   ├── server/            # Server implementation
│   │   ├── auth.go        # Authentication logic
│   │   └── server.go      # Core server functionality
│   └── utils/             # Shared utilities
│       ├── logger.go      # Logging configuration
│       └── types.go       # Common types and transport definitions
├── main.go                 # Application entry point
├── Dockerfile             # Container image definition
└── Makefile              # Build automation

Development Workflow

1. Clone and Setup

git clone https://github.com/trento-project/mcp-server.git
cd mcp-server

2. Install Dependencies

The project uses Go modules for dependency management:

go mod download

To install development tools (linters, etc.):

make install-tools

3. Building the Project

To build the project binary:

make build

The compiled binary will be located in the bin/ directory as mcp-server-trento.

4. Running the Project Locally

To run the server locally with default settings:

make run

To run it in MCP protocol 2026-07-28 stateless mode (see Stateless Mode):

go run main.go --port 5000 --verbosity=info --enable-health-check --trento-url https://demo.trento-project.io --stateless

Or run the binary directly:

./bin/mcp-server-trento --port 8080 --transport sse --verbosity info

For a complete list of available flags:

./bin/mcp-server-trento --help

Testing

Running Tests

To run the full test suite:

make test

This runs all tests with coverage reporting.

To run tests for a specific package:

go test ./internal/server -v
go test ./internal/utils -v

To run tests with verbose output and coverage:

go test ./... -v -cover

Test Structure

Unit tests are located alongside source files with _test.go suffix.
Test exports are defined in export_test.go files for testing internal functionality.

Linting

The project includes some linters to ensure code quality:

# Run all linters
make lint

# Individual linters
make linter-asciidoc      # Documentation in AsciiDoc validation
make linter-golangci      # Go code linting
make linter-license       # License header verification
make linter-shellcheck    # Shell script linting
make linter-yamllint      # YAML file linting

Debugging

Debug Logging

Run the server with debug logging enabled:

./bin/mcp-server-trento --verbosity debug

Log levels: * debug: Debug (most verbose). * info: Info (default). * warning: Warning. * error: Error (least verbose).

Common Debugging Scenarios

OpenAPI Specification Issues: Verify OAS documentation provided via --oas-path flag is valid and contains operations tagged with the tag selected via --tag-filter flag.
Authentication Problems: Check that the provided Trento PAT is correct.
Transport Issues: Try switching between streamable and sse transports. Note that --stateless only works with streamable.
Port Conflicts: Use --port flag to specify a different port.

Container Development

Building the Container Image

To build the container image:

make build-container

To build with a custom image name:

IMAGE=my-registry/mcp-server-trento:dev make build-container

This creates a container image named ghcr.io/trento-project/mcp-server-trento:latest (or your custom name).

Running the Container

To run the server in a container:

make run-container

To run with custom environment variables:

docker run -p 5000:5000 ghcr.io/trento-project/mcp-server-trento:latest --trento-url https://your-trento-instance.com

Pushing Container Images

To push the container image to a registry:

make push-container