Configuration

Every setting of the @octri/mcp server, the one your users run with npx. Each is an environment variable, and most have a command-line flag too. Only the project is required.

A flag wins over its variable. A flag takes its value as --group billing or --group=billing. A variable that switches something on takes 1, true, yes or on, and a list is comma-separated. An empty variable counts as unset, so a client config with "OCTRI_API_BASE_URL": "" keeps the default.

A package published under your own name reads the same variables with your prefix, such as ACME_API_TOKEN for OCTRI_API_TOKEN. The transport variables (MCP_* and PORT) have no prefix.

Commands

npx @octri/mcpcommand

Runs the server, on the transport MCP_TRANSPORT names. This is what an AI client starts.

npx @octri/mcp doctorcommand

Checks the setup from end to end, says what to fix, and makes one real read from your API to prove the credential works. It exits with 1 when a check fails.

--no-call skips the read. So does --dry-run, and --practice checks only that there's practice data. See troubleshooting.

npx @octri/mcp logincommand

Asks for your API credential, for the scheme your API uses, and saves it in the macOS Keychain, Windows Credential Manager or the Secret Service on Linux. The server reads it back when it starts, so the client's config can carry none. Needs the project, from --project-id or OCTRI_PROJECT_ID.

npx @octri/mcp logoutcommand

Removes the saved credential for the project.

A healthy setup, checked without the test call:

npx @octri/mcp doctor --project-id YOUR_PROJECT_ID --no-call

PASS  Project          YOUR_PROJECT_ID
PASS  Octri API        https://api.octri.dev/api/v1 answered
PASS  Operation tools  23 offered, 11 ask the user before each call (needs a client with MCP elicitation, such as Claude Code 2.1.76+)
PASS  Base URL         https://api.acme.com/v1
PASS  Credentials      bearer auth: OCTRI_API_TOKEN set
INFO  Test call        Skipped (--no-call).
INFO  Usage reporting  Off.

Ready. Add the server to your client and ask it about your API.

The project

OCTRI_PROJECT_IDstringrequired

The project to serve. Copy it from MCP Studio. Flag: --project-id.

OCTRI_API_URLURLdefault: https://api.octri.dev/api/v1

The Octri API the server reads your docs and tools from. Change it only for a test environment. This isn't your API: see OCTRI_API_BASE_URL.

Calling your API

Only operation tools need these. The documentation tools work without them.

OCTRI_API_BASE_URLURLdefault: the Base URL in SDK Studio

Your API: the address operation tools call. Point a shared config at staging, and the worst a stray credential can do is call staging.

Set the credential your API's scheme takes, the one in your API settings, which your SDK uses too:

Scheme	Set	Sent as
Bearer or OAuth 2	`OCTRI_API_TOKEN`	`Authorization: Bearer <token>`
API key	`OCTRI_API_KEY`, and `OCTRI_API_KEY_HEADER` if needed	The key, in that header
Basic	`OCTRI_API_USERNAME` and `OCTRI_API_PASSWORD`	`Authorization: Basic <encoded pair>`

OCTRI_API_TOKENsecret

A bearer or OAuth 2 token. For a Basic API, a ready-encoded credential, used when no username or password is set.

OCTRI_API_KEYsecret

An API key.

OCTRI_API_KEY_HEADERheader namedefault: X-API-Key

The header the API key goes in. Set it when your API reads the key from another header.

OCTRI_API_USERNAMEstring

A Basic username.

OCTRI_API_PASSWORDsecret

A Basic password.

Credentials set in the environment win. If any credential variable is set, the server uses only the environment and ignores what login saved, so a token from one place never pairs with a username from the other.

These are all sent as headers. An API that takes its credentials in the request body, such as a client_id and secret, gets them as ordinary tool arguments instead.

Tools and permissions

Each of these narrows what you published in MCP Studio, except --allow-tools and --allow-writes, which pre-approve tools you set to ask first. Nothing here brings back a tool you turned off. See permissions and limits.

--groupstring

Serves one tool group, by its slug. Variable: OCTRI_GROUP.

--tool-modechoicedefault: what you published

How the operation tools are listed. Variable: OCTRI_TOOL_MODE.

Value	Lists
`auto`	Every tool, or search mode once there are more than the search threshold (40 unless you change it)
`all`	Every tool
`search`	`search_tools`, `describe_tool` and `call_tool` in their place
`code`	`describe_sdk` and `run_code`, when you've turned code mode on. Otherwise search mode

See search and code mode.

--read-onlyswitchdefault: off

Lists and runs only the tools that read. Variable: OCTRI_READ_ONLY.

--deny-toolslist

Never lists or runs these tools: by name, by the name before you renamed it, or by endpoint slug. Variable: OCTRI_DENY_TOOLS.

--allow-toolslist

Runs these Asks first tools without asking, by name or endpoint slug. * means all of them. Variable: OCTRI_ALLOW_TOOLS.

--allow-writesswitchdefault: off

Runs every Asks first tool without asking, the same as --allow-tools '*'. Variable: OCTRI_ALLOW_WRITES.

--dry-runswitchdefault: off

Builds each API request and returns it, sending nothing. Variable: OCTRI_DRY_RUN.

--practiceswitchdefault: off

Answers every call with sample data built from your docs, sending nothing and needing no credential. Works once you've turned practice mode on for the project. Variable: OCTRI_PRACTICE.

--skip-promptslist

Leaves these prompts out, by name. For a client that already has them, such as through the Claude Code plugin. Variable: OCTRI_SKIP_PROMPTS.

--no-telemetryswitch

Stops reporting tool calls to MCP Studio. A report carries the tool's name, the outcome, how long it took and the client's name, never arguments or responses. Variable: OCTRI_TELEMETRY=0.

What agents are told

Each is on unless you set it to 0. See agent experience.

OCTRI_CHANGE_NOTICES0 to turn offdefault: on

Notes on tools that changed since the agent last connected, and the what_changed tool.

OCTRI_CHANGES_SINCErelease number

Starts every session's notes from this release, instead of the last one this machine's agent saw.

OCTRI_STATE_DIRfolderdefault: the system's per-user state folder

Where the server remembers the last release each agent saw, in changes.json. By default %LOCALAPPDATA%\octri-mcp on Windows, ~/Library/Application Support/octri-mcp on macOS, and $XDG_STATE_HOME/octri-mcp or ~/.local/state/octri-mcp on Linux.

OCTRI_ERROR_GUIDES0 to turn offdefault: on

The guide to fixing a failed call that comes back with the error.

OCTRI_OUTAGE_STATUS0 to turn offdefault: on

Warnings when Octri monitoring sees an endpoint is down.

Transport

See transports.

MCP_TRANSPORTchoicedefault: stdio

Value	For
`stdio`	A client that starts the server itself, such as Claude Desktop or Cursor
`http`	Streamable HTTP, for hosting the server yourself. It serves `/mcp`
`sse`	The older HTTP and SSE transport, for existing deployments

PORTnumberdefault: 3000

The port http and sse listen on.

MCP_HOSTinterfacedefault: 127.0.0.1

The interface to listen on. Anything but loopback needs MCP_AUTH_TOKEN, and the server won't start without it.

MCP_AUTH_TOKENsecret

A bearer token every request must carry.

MCP_ALLOWED_ORIGINSlist

Browser origins allowed to call the server. None by default.

Keep credentials out of shared files

MCP configs are plain JSON on disk, and often in git

.cursor/mcp.json in a repo root is the natural place for a config, and also a file people commit without thinking. A token there is a token in your history.

Install: the config each client takes.
Tool reference: every built-in tool.
Troubleshooting: when a setting doesn't take.