osTicket MCP Server: Configuration

All environment variables of the osTicket MCP Server with defaults and validation rules, location of the .env file, and the fixed limits for response size, timeout, attachments and logs.

Deutsche Version

Back to overview

osTicket MCP Server: Configuration

This documentation always describes the latest published version.

Where the configuration lives

The server reads environment variables in this order:

Variables the MCP client passes to the process (env in the MCP configuration). They take precedence.
The file ~/.claude/mcp-servers/osticket/.env, if it exists.
If that file does not exist, a .env in the working directory of the process. This is meant for development.

An empty variable counts as unset and gets the default value. After changing the file you have to restart the MCP client.

Environment variables

Variable	Required	Default	Meaning
`OSTICKET_API_URL`	Yes	-	Base URL of the osTicket instance, for example `https://tickets.example.com`
`OSTICKET_API_KEY`	Yes	-	API key, sent as the header `X-API-Key`. Must not be empty and must not contain line breaks
`OSTICKET_API_REJECT_UNAUTHORIZED`	No	`true`	Verify the TLS certificate. Only the exact value `true` keeps verification on, any other value turns it off
`OSTICKET_DEFAULT_NAME`	No	empty	Name that `osticket_create_ticket` uses when no `name` is passed
`OSTICKET_DEFAULT_EMAIL`	No	empty	Email address for the same purpose. Checked for a valid format at startup
`OSTICKET_DEFAULT_TOPIC_ID`	No	`0`	Help topic ID when no `topicId` is passed. `0` means no help topic. A non-numeric value aborts startup
`LOG_LEVEL`	No	`info`	`debug`, `info`, `warn` or `error`. Any other value is not rejected, in that case all messages except debug messages are written
`ALLOW_HTTP`	No	not set	Only the exact value `true` allows an `http://` URL. Otherwise startup aborts on HTTP
`MCP_DEBUG`	No	not set	The value `true` enables debug messages of the logger

ALLOW_HTTP and MCP_DEBUG are not part of the file .env.example, but the server evaluates them.

Startup checks

The server aborts at startup with an error message if:

OSTICKET_API_URL or OSTICKET_API_KEY is missing or empty,
the URL is invalid or uses http: without ALLOW_HTTP=true,
the API key contains a line break,
OSTICKET_DEFAULT_EMAIL is not a valid email format,
OSTICKET_DEFAULT_TOPIC_ID is not a number.

If OSTICKET_API_REJECT_UNAUTHORIZED is not true, the server writes a warning to stderr and to the log, but keeps working.

The server builds all endpoint URLs from the host of OSTICKET_API_URL and the fixed path /api/.... A path component in the base URL, such as https://example.com/support, is dropped. osTicket therefore has to be reachable at the root of the host.

Fixed limits

These values are set in the code and cannot be changed.

Limit	Value
Timeout per request	10 seconds
Retries on transient errors	up to 2, waiting 500 ms and 1000 ms
Size of an osTicket response	at most 10 MB, larger responses are aborted
Length of a result list in the tool response	about 25,000 characters, the list is truncated beyond that
Default and maximum for `limit`	20 and 100
Attachments per call	5 files, 10 MB each, 50 MB in total at most
Cache of the status list	5 minutes
Log file	Rotated only at startup, when the file is larger than 10 MB. The last 5 rotated files are kept. While the server runs, the file keeps growing

Example

OSTICKET_API_URL=https://tickets.example.com
OSTICKET_API_KEY=your-api-key
OSTICKET_API_REJECT_UNAUTHORIZED=true

OSTICKET_DEFAULT_NAME=Claude
OSTICKET_DEFAULT_EMAIL=claude@example.com
OSTICKET_DEFAULT_TOPIC_ID=1

LOG_LEVEL=info