MCP Clients / Codex
OpenAI Codex
Connect Telara to OpenAI Codex using a TOML config file. Codex uses a different format than other editors — bearer tokens are referenced by environment variable name rather than pasted inline.
The Telara CLI can configure Codex automatically with telara setup codex. It writes the TOML config and sets the environment variable for you. The guide below is for manual setup.
Before You Begin
Prerequisites
Go to Capabilities > Configurations in Telara. Create one and add at least one integration as a data source if you haven't already.
In Telara, open Capabilities → API Keys, click "Generate Key", and pick a scope (tenant, team, project, or user). Copy the key — it starts with telara_mcp_ and is only shown once.
Configuration Scope
Global vs. project-level
Codex reads config from two locations. The global config applies to all sessions; the project config activates when Codex is run inside that directory and overrides the global config.
Available in every Codex session across all projects. Best for your primary Telara configuration.
Only active when Codex runs in that project directory. Useful for project-specific Telara configurations with different data sources.
Step 1 — Environment Variable
Store your API key as an environment variable
Unlike other editors that accept an inline token, Codex references bearer tokens by environment variable name. This keeps credentials out of config files entirely.
Because Codex reads the token from the environment, your config.toml contains only the variable name — never the key itself. This means you can safely commit project-level configs to source control.
Step 2 — Config File
Add Telara to your config.toml
Open (or create) your Codex config file and add a [mcp_servers.telara] section. Note: Codex uses TOML format, not JSON.
The section header must be [mcp_servers.name] with an underscore — not [mcp-servers.name]. Using a hyphen will cause a parse error.
Verification
Confirming the connection
After saving your config and setting the environment variable, start Codex. Use the /mcp command in the TUI to verify Telara is connected.
The TELARA_API_KEY variable must be set in the shell where you run Codex. Open a new terminal or run source ~/.zshrc to reload your profile.
Run codex in your project directory. Codex loads MCP servers defined in config.toml during startup.
Type /mcp in the Codex interface. Telara should appear in the connected servers list with a green status indicator.
Ask Codex to search your knowledge base — for example: "find how we handle auth in this repo." It will call Telara's search tools automatically.
Advanced
Filtering available tools
You can limit which Telara tools Codex can invoke using enabled_tools or exclude specific tools with disabled_tools. Use the names Telara actually serves — every one carries the telara_ prefix. Filtering out telara_tool_search also removes your ability to reach integration actions, since they are discovered rather than listed up front.
Filtering tools in config.toml restricts what Codex can even see — a tool filtered out here won't appear at all, regardless of the permission policy. This is a local preference, not a security control. Telara's permission policies are enforced server-side and apply regardless of what's in your local config.
Tips
Recommendations
If you connect to multiple Telara configurations (e.g. eng-access and security-access), use a distinct env var name for each: TELARA_ENG_KEY, TELARA_SEC_KEY.
Because no key is stored in config.toml — only the env var name — project-level .codex/config.toml files are safe to commit to source control.
Set enabled = false to temporarily disable a Telara connection without removing the config. Useful when switching between projects.
Add multiple [mcp_servers.*] sections to connect to more than one Telara configuration at the same time. Each appears as a separate tool source.
Finding integration actions
Codex sees a fixed set of Telara tools when it connects — knowledge search, graph traversal, archive reads, task tracking, and two discovery tools. Your connected platforms are not all listed up front. GitLab alone contributes 107 actions and Jira 84; loading every schema into the model on each request would crowd out the context you actually want it thinking with.
Describe the task in plain language — "comment on a Jira issue", "open a merge request". Matching actions become callable by name straight away. Only actions your organization's policy permits are returned.
Returns one action's full parameter schema. Worth calling before invoking an action whose arguments are not obvious.
If you already know the action you want, telara_execute_action runs any permitted action directly — pass integration, action and params, with no search step. You can also browse the telara://integrations/available resource. Policy is enforced server-side on every call, whichever route you take.