Agent integrations

Connect Codex to Orchestor

Codex is OpenAI's coding agent for editing files and running commands from a terminal or desktop app. Use Orchestor CLI to explore your brands, prompts, AI answers, and reports from Codex.

Orchestor CLI · Orchestor Skills · Orchestor MCP · Codex documentation

You can also use the Codex desktop app. The quickstart below uses the CLI.

Quick start

1
Install Codex
Install Codex in your terminal. See the Codex installation guide for requirements and other installation methods.
npm install -g @openai/codex
2
Launch Codex in your project
Start Codex from the root of your project. Follow the first-run instructions to sign in.
codex
3
Install Orchestor CLI
Open another terminal to install Orchestor CLI and sign in. These commands are for macOS and Linux. See other installation methods for your platform.
curl -fsSL https://orchestor.io/install | sh orc auth login
Follow the browser instructions to sign in to Orchestor. If needed, create an account.
List your workspaces and select one. Replace YOUR_WORKSPACE_ID with an ID from the list.
orc workspaces list orc workspace use YOUR_WORKSPACE_ID
4
Try a prompt
Return to Codex and try this prompt.
Use Orchestor CLI (orc) to list the brands in the current workspace. Include each brand's ID and name. Do not change any data.
If Codex asks for permission to run a command, review it. A workspace without registered brands can return an empty list.

Orchestor platform access

Expand a section to learn more.

Orchestor Skills

Workflows that teach the agent how to investigate brands and AI answers.

Skills are instructions the agent loads when needed. The skills bundled with Orchestor CLI guide command selection and workflows for checking brands, organizing prompts, investigating answers, and reading reports.

Skill	What it does
`orchestor-brand`	Find analysis targets and inspect or manage brand profiles and settings.
`orchestor-topic`	Inspect and manage topics to organize analysis themes.
`orchestor-prompt`	Inspect and manage the prompts you measure.
`orchestor-answer`	Retrieve collected AI answers and investigate their content.
`orchestor-report`	Retrieve and interpret visibility, citation, and sentiment reports.

Select Codex and the installation scope in the skills distribution guide. Skills add instructions; sign in to your workspace separately through the CLI.

MCP servers

Tools for accessing brands, AI answers, and reports from a conversation.

MCP servers provide agents with tools that define their inputs and responses. Hosted Orchestor MCP connects to the workspace authorized through OAuth. Alongside tools for retrieving brands and answers, it supports discovering and running additional read-only tools.

Resource	Use
Brands, topics, and prompts	Find analysis targets with `brands_list`, `topics_list`, and `prompts_list`, then inspect settings with the corresponding detail tools.
AI answers	Investigate collected answers with `answers_list` and `answers_get`.
Visibility, citations, and sentiment	Retrieve metrics and evidence with `get_visibility_report`, `get_citations_report`, and `get_sentiment_report`.
Tool discovery	Search with `search_tools`, inspect inputs with `get_tool_schema`, and run additional read-only tools with `execute_tool`.

Use this server URL:

https://mcp.orchestor.io/mcp

Add the following server to ~/.codex/config.toml. Merge it with existing configuration; preserve other servers and settings.

[mcp_servers.orchestor]
url = "https://mcp.orchestor.io/mcp"

If an orchestor entry already exists, inspect its URL and reuse the intended connection rather than creating a duplicate.

codex mcp login orchestor
codex mcp list

In the browser, check the selected workspace and permissions before authorizing. Use read access for analysis tasks.

Ask the agent to list brand IDs and names without changing data. A successful brands_list response confirms the connection; an empty list is valid for a workspace without brands.

Available tools depend on connection permissions and server configuration. See MCP tools for inputs, responses, and the distinction between preview and write operations. See Orchestor MCP for authentication and connection management.

Orchestor CLI

Commands for managing brands, investigating answers, and retrieving reports.

The orc command in Orchestor CLI lets Codex work with your workspace from the terminal. Find analysis targets with orc brands list, inspect answers with orc answers list, and retrieve visibility reports with orc reports visibility get. The bundled skills guide command selection and execution for each task.

orc brands list --json
orc answers list --json
orc reports visibility get --json

Use JSON output for agent reads and scripted analysis. Check orc --help and each command's --help for arguments.

Install on macOS or Linux with:

curl -fsSL https://orchestor.io/install | sh

Follow the CLI quickstart to sign in and select a workspace. Choose an answer audit, competitor investigation, or another task from CLI workflows.

Agent-friendly docs

References you can discover and share with agents as Markdown.

Use the page copy control to retrieve headings, examples, tables, and links as Markdown. The adjacent menu also lets you view or download it. If you do not know which page to read, give your agent one of these indexes:

orchestor.io/docs/llms.txt — An index of public documentation organized by section.
orchestor.io/docs/sitemap.md — Page titles, URLs, and descriptions for choosing what to read.
orchestor.io/docs/llms-full.txt — Public documentation content for work spanning multiple features.

curl -fsSL https://orchestor.io/docs/llms.txt

For retrieval methods and when to use each index, see Markdown access and agent indexes.

Example prompts

First choose a brand from the brand list and provide its name or ID.

Compare visibility

For the selected brand, compare visibility over the last 7 days with the previous 7 days.
Include the date ranges and reports you used. Identify any periods without data.
Do not change any data.

Investigate citations

Review AI answers related to the selected brand and organize the cited domains and URLs.
Include the answer IDs that support your findings. Do not change any data.

Plan next actions

Use the selected brand's reports and AI answers to identify 3 issues to investigate first.
Separate observed facts from proposed improvements and include supporting data.
Do not change any data.

Tips

Let skills guide command selection. The skills bundled with Orchestor CLI explain when to use orc brands list to find brands, orc answers list to read answers, and orc reports visibility get to investigate visibility. Describe your goal so Codex can consult the relevant instructions.
Start with the task. Try “Investigate why this competitor gained visibility” or “Organize the pages being cited.” CLI workflows cover answer audits, competitor research, and other tasks. Include the target brand and date range to keep comparisons consistent.
Discover additional MCP tools when you need them. Search with search_tools, inspect inputs with get_tool_schema, and run the tool with execute_tool. This discovery path is read-only. See the tool reference for details.
Launch from the project where you installed skills. Project-scoped Codex skills live in .agents/skills. Start codex from that project and check orc workspace current before working with data.
Check connections from the terminal. Use orc auth status --json for CLI authentication and codex mcp list for MCP registration. For CLI use in CI, follow the CI authentication guide and supply the API key through secret management.

Orchestor MCP serverExplore MCP server connection instructions, OAuth authentication, and available tools.

FAQ

Should I use Skills, MCP, the CLI, or all of them?

You can use them together. Skills teach Codex how to investigate brands and AI answers. MCP provides tools to access workspace data from a conversation. The CLI runs operations in the terminal and returns JSON for analysis and automation. Start with the CLI quickstart on this page, then add Skills for task guidance and MCP for the tools you want to use in conversation.

Skills · MCP · CLI

Can Codex use Orchestor CLI?

Yes. Install orc and sign in with orc auth login so Codex can run it from the terminal. Add --json for structured output. Tell Codex to use orc for Orchestor operations in your project's AGENTS.md. See CLI workflows for examples.

How do I give Codex access to my Orchestor account?

For MCP, start authentication from codex mcp login orchestor, then choose your workspace and permissions in the browser. Select Read-only for analysis. For the CLI, sign in with orc auth login and select a workspace with orc workspace use YOUR_WORKSPACE_ID. Authorize MCP and sign in to the CLI separately.

Can I use existing brands and workspaces?

Yes. You do not need to create a new brand. For the CLI, check orc workspace current and retrieve existing brands with orc brands list. MCP connects to the workspace selected during authorization. Give Codex the brand name or ID and the date range to investigate.

How does MCP tool discovery work?

Find an operation with search_tools, inspect its inputs with get_tool_schema, then run it with execute_tool. This lets Codex discover additional read-only tools even when the operation is absent from the initial tool list. This path only runs read operations. See the MCP tool reference.

Troubleshooting

MCP server connection fails or times out

Check the server status in codex mcp list. In ~/.codex/config.toml, confirm that orchestor points to https://mcp.orchestor.io/mcp. Keep other settings and server entries. Complete OAuth through codex mcp login orchestor, then start a new agent session if tools do not appear. See the client connection guide.

Codex cannot authenticate with Orchestor

For MCP, start OAuth from codex mcp login orchestor and complete authorization in your browser. If authorization has expired, check MCP connections and authorize again. For the CLI, check orc auth status --json and run orc auth login if needed. For CLI use in CI, see the service account and API key setup.

Codex gives outdated product information or commands

Give Codex the documentation index and ask it to read the current documentation before working. If you know the relevant page, use the page copy control to share its Markdown. Check the installed CLI's arguments with orc --help and each command's --help.

Codex cannot run orc

Run orc --version in a new terminal. If the command is not found, check the installation guide. Start a new Codex session after installing the CLI to pick up the updated PATH.

Build agents with Orchestor

Take what you explore in Codex into your own analysis agents and automation. Use Orchestor's MCP and CLI to bring brand visibility and AI answer research into your applications and workflows.

Connect MCP tools to your agentConnect an agent that supports remote MCP and OAuth to data in an authorized workspace.Automate research with the CLITurn answer audits and competitor comparisons into scripts, then run them from CI.