---
title: Connect OpenCode to Orchestor
description: Set up OpenCode and Orchestor CLI to explore brands and AI answers.
canonical_url: https://orchestor.io/docs/en/agent-setup/opencode
markdown_url: https://orchestor.io/docs/en/agent-setup/opencode.md
contentType: how-to
---

# Connect OpenCode to Orchestor

[← All agents](https://orchestor.io/docs/en/agent-setup.md)

OpenCode is an open-source terminal agent that supports multiple model providers. Use Orchestor CLI to explore your brands, prompts, AI answers, and reports from OpenCode.

[Orchestor CLI](https://orchestor.io/docs/en/cli.md) · [Orchestor Skills](https://orchestor.io/docs/en/agent-resources/skills.md) · [Orchestor MCP](https://orchestor.io/docs/en/mcp.md) · [OpenCode documentation](https://opencode.ai/docs/)

## Quick start

1. **Install OpenCode**
   Install OpenCode in your terminal. See the [OpenCode installation guide](https://opencode.ai/docs/) for requirements and other installation methods.

   ```bash
   curl -fsSL https://opencode.ai/install | bash
   ```
2. **Launch OpenCode in your project**
   Start OpenCode from the root of your project. Follow the first-run instructions to connect your model provider.

   ```bash
   opencode
   ```
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](https://orchestor.io/docs/en/cli/installation.md) for your platform.

   ```bash
   curl -fsSL https://orchestor.io/install | sh
   orc auth login
   ```

   Follow the browser instructions to sign in to Orchestor. If needed, [create an account](https://orchestor.io/signup).

   List your workspaces and select one. Replace `YOUR_WORKSPACE_ID` with an ID from the list.

   ```bash
   orc workspaces list
   orc workspace use YOUR_WORKSPACE_ID
   ```
4. **Try a prompt**
   Return to OpenCode and try this prompt.

   ```text
   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 OpenCode 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. |

OpenCode reads project skills from `.agents/skills`. Use `orc setup skills --agent codex --dry-run` to inspect this shared destination, then `orc setup skills --agent codex` to install. See [OpenCode skills](https://opencode.ai/docs/skills/) and the [skills distribution guide](https://orchestor.io/docs/en/cli/workflows/skills-distribution.md). 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:

```text
https://mcp.orchestor.io/mcp
```

Add the following server to `opencode.json`. Merge it with existing configuration; preserve other servers and settings.

```json
{
  "mcp": {
    "orchestor": {
      "type": "remote",
      "url": "https://mcp.orchestor.io/mcp",
      "oauth": {}
    }
  }
}
```

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

```bash
opencode mcp auth orchestor
opencode 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](https://orchestor.io/docs/en/mcp/tools.md) for inputs, responses, and the distinction between preview and write operations. See [Orchestor MCP](https://orchestor.io/docs/en/mcp.md) for authentication and connection management.

### Orchestor CLI

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

The `orc` command in [Orchestor CLI](https://orchestor.io/docs/en/cli.md) lets OpenCode 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.

```bash
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:

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

Follow the [CLI quickstart](https://orchestor.io/docs/en/cli/quickstart.md) to sign in and select a workspace. Choose an answer audit, competitor investigation, or another task from [CLI workflows](https://orchestor.io/docs/en/cli/workflows.md).

### 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](https://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](https://orchestor.io/docs/llms-full.txt) — Public documentation content for work spanning multiple features.

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

For retrieval methods and when to use each index, see [Markdown access and agent indexes](https://orchestor.io/docs/en/agent-resources/markdown-access.md).

## Example prompts

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

### Compare visibility

```text
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

```text
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

```text
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 OpenCode can consult the relevant instructions.
- **Start with the task.** Try “Investigate why this competitor gained visibility” or “Organize the pages being cited.” [CLI workflows](https://orchestor.io/docs/en/cli/workflows.md) 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](https://orchestor.io/docs/en/mcp/tools.md) for details.
- **Launch from the project where you installed skills.** Project-scoped OpenCode skills live in `.agents/skills`. Start `opencode` 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 `opencode mcp list` for MCP registration. For CLI use in CI, follow the [CI authentication guide](https://orchestor.io/docs/en/cli/workflows/ci-setup.md) and supply the API key through secret management.

- **[Orchestor MCP server](https://orchestor.io/docs/en/mcp.md)**
  Explore 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 OpenCode 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](https://orchestor.io/docs/en/agent-resources/skills.md) · [MCP](https://orchestor.io/docs/en/mcp.md) · [CLI](https://orchestor.io/docs/en/cli.md)

### Can OpenCode use Orchestor CLI?

Yes. Install `orc` and sign in with `orc auth login` so OpenCode can run it from the terminal. Add `--json` for structured output. Tell OpenCode to use `orc` for Orchestor operations in your project's `AGENTS.md`. See [CLI workflows](https://orchestor.io/docs/en/cli/workflows.md) for examples.

### How do I give OpenCode access to my Orchestor account?

For MCP, start authentication from `opencode mcp auth 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 OpenCode 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 OpenCode 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](https://orchestor.io/docs/en/mcp/tools.md).

## Troubleshooting

### MCP server connection fails or times out

Check the server status in `opencode mcp list`. In `opencode.json`, confirm that `orchestor` points to `https://mcp.orchestor.io/mcp`. Keep other settings and server entries. Complete OAuth through `opencode mcp auth orchestor`, then start a new agent session if tools do not appear. See the [client connection guide](https://orchestor.io/docs/en/mcp/clients.md).

### OpenCode cannot authenticate with Orchestor

For MCP, start OAuth from `opencode mcp auth orchestor` and complete authorization in your browser. If authorization has expired, check [MCP connections](https://app.orchestor.io/settings/mcp) 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](https://orchestor.io/docs/en/cli/workflows/ci-setup.md).

### OpenCode gives outdated product information or commands

Give OpenCode the [documentation index](https://orchestor.io/docs/llms.txt) 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`.

### OpenCode cannot run orc

Run `orc --version` in a new terminal. If the command is not found, check the [installation guide](https://orchestor.io/docs/en/cli/installation.md). Start a new OpenCode session after installing the CLI to pick up the updated PATH.

## Build agents with Orchestor

Take what you explore in OpenCode 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 agent](https://orchestor.io/docs/en/mcp.md)**
  Connect an agent that supports remote MCP and OAuth to data in an authorized workspace.

- **[Automate research with the CLI](https://orchestor.io/docs/en/cli/workflows.md)**
  Turn answer audits and competitor comparisons into scripts, then run them from CI.

## Other agents

- **[Claude Code](https://orchestor.io/docs/en/agent-setup/claude-code.md)**
  Set up Orchestor CLI to explore brands and AI answers from Claude Code.

- **[Codex](https://orchestor.io/docs/en/agent-setup/codex.md)**
  Add the MCP server and connect your workspace with OAuth.

- **[Cursor](https://orchestor.io/docs/en/agent-setup/cursor.md)**
  Add MCP to your editor to access Orchestor data while you work.

---

[Documentation index](https://orchestor.io/docs/llms.txt)