This section explains how to create and start an MCP profile using the mcpgen utility. A profile defines the configuration, certificates, and runtime environment for MCP services. Generating a profile is an important step in preparing the MCP server for development or production testing.

Basic profile setup

Use this command to quickly start the MCP Server using your OpenAPI specification file:
./mcpgen up --spec <openapi.yml>
where, --spec ./<openapi.yml>—Specifies the OpenAPI specification file for tool definitions.

Basic TLS setup

Use this command to start the MCP Server with TLS enabled and your OpenAPI specification:
./mcpgen up --quick --tls --spec ./<openapi.yml>
where,
  • --quick—Creates a profile using default settings for faster setup.
  • --tls—Enables TLS for secure communication.
  • --spec ./<openapi.yml>—Specifies the OpenAPI specification file for tool definitions.

TLS with custom hostnames

Run this command to enable TLS and include additional hostnames in the certificate to avoid browser or client warnings:
./mcpgen up --quick --tls --extra-hostnames "api.example.com,myapp.local" --spec ./<openapi.yml>
where,
  • --extra-hostnames—Adds additional hostnames to the TLS certificate Subject Alternative Names (SAN).
  • "api.example.com,myapp.local"—Comma-separated list of hostnames to include.

What happens during profile creation

The following steps outline the process of profile creation:
  1. A directory named generated/<profile_name>/ is created. The system also updates the generated/servers.registry.tsv file to track the newly created profile.
  2. Self-signed TLS certificates are generated for development if none exist.
  3. Service account keys and JWT tokens are created (unless --no-sa is specified).
  4. The mcp_server_config.json MCP server configuration file is written with default routing settings.
  5. The container starts and performs a smoke check, where:
    • All the tools available on the MCP Server are listed.
    • The client invokes the first MCP tool, which results in an API call to the MCP Server. The server processes the request and returns the response to the client.
Note: If you used localhost in the base URL when generating the profile, the MCP Server container cannot reach the Data Service. For more information, see Work with a data service created using localhost.

Other configuration options and generated profile structure

During profile creation, additional configuration options are applied. The following table provides details of the directory structure and client MCP configuration created by the up command.
Configuration Purpose
Service account keys and tokens Used for MCP client-to-server authentication
TLS/mTLS settings Configures transport security for the MCP server
OpenAPI visibility and context settings Ensures proper exposure and context handling for API operations
Downstream TLS certificates and host verification Provides secure communication with downstream services
The up command creates a structured directory under generated/<profile>/. This directory contains all necessary artifacts, such as configuration files, scripts, certificates, and metadata required for consistent deployment and operation. The following table lists the contents of the generated profile:
Directory/File Description
sa/ Contains key material if the service account feature is enabled.
client/ Contains configuration and environment variables for client-side operations, enabling interaction with the MCP Server without manual setup.
server/ Contains configuration files, environment variables, and scripts required to start and manage the MCP Server instance.
certs/ Contains TLS and mTLS assets if secure communication is selected.
start_server.sh|ps1 Script to start the MCP Server instance.
try_client.sh|ps1 Script to validate client-server interaction.
docker-compose.mcp.yml Docker configuration to run the OpenEdge MCP server with required parameters and environment details.
profile.json Contains metadata file describing the generated profile.
Contents of the server directory
The server directory holds all files required to start and configure the MCP Server:
File Description
<openapi.yml> The OpenAPI specification used to define and generate the MCP Server.
server.env Stores environment variables required for the MCP server, including sensitive information such as tokens, certificates, and other secrets.
mcp_server_config.json Contains the core MCP Server configuration, which is used to create and start the MCP Server. The MCP Server cannot run without this file. Use the .verbose option for detailed output.

Contents of the client directory

The client directory provides everything needed to interact with the MCP Server without manual setup:
File Description
sa.jwt Stores a JWT associated with the service account configured for the MCP Server. This token is required for secure communication between the client and the server.
client.env Stores environment variables for the MCP client.
mcp.json Auto-generated MCP client configuration file.

The mcp.json file is an auto-generated client configuration that simplifies connecting an MCP client to your development environment. For example, in VS Code, you can use this file to configure the MCP client without manually setting up endpoints, authentication tokens, or tool definitions.

Instead of creating these settings from scratch, the MCP generation process provides a ready-to-use mcp.json. You can simply copy this file into the MCP client configuration of your IDE, and start interacting with the MCP Server immediately without any additional setup.

The following characteristics define how authentication headers are managed in the mcp.json client MCP configuration file:
  • The service account header is included only when service account authentication is enabled.

  • Authentication header precedence is resolved in the following order: service_account.prefix → user_auth.prefix → Bearer

  • Double prefixing is automatically avoided.
For example:

{
  "servers": {
    "myprof": {
      "url": "http://localhost:8500/http",
      "type": "http",
      "headers": {
        "X-OEMCP-SERVICEACCOUNT": "Bearer eyJ..."
      }
    }
  },
  "inputs": []
}

List all profiles

To list all profiles, run:
./mcpgen list --wide

For detailed information about the core commands used to manage a profile with the mcpgen CLI, see Manage core commands in mcpgen.