> ## Documentation Index
> Fetch the complete documentation index at: https://developer.opus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Opus MCP Server

> Connect AI agents such as Claude Code, Claude Desktop, VS Code, and Codex to your Opus organization through the Model Context Protocol.

## Overview

The Opus MCP server lets an AI agent work in your Opus organization through the [Model Context Protocol](https://modelcontextprotocol.io). Once connected, your agent can find, read, edit, and test workflows, map business processes, and manage workspaces and members, using the same permissions you have in the Opus app.

The server is split into **categories**. Each category is a separate MCP server URL with its own set of tools. You add one server entry in your client for each category you need.

> [!NOTE]
>
> Access to the Opus MCP server is enabled per organization. If your organization is not enabled yet, contact your Opus account team to request access.

## Server URLs

> [!WARNING]
>
> The MCP URL can be different for each Opus deployment. The URLs on these pages are for the Opus cloud at `app.opus.com`. If your organization uses a different deployment, such as a regional or dedicated instance, ask the Opus team for your MCP URL before you connect. Use that URL in place of `https://mcp.opus.com` in every setup guide.

On the Opus cloud, all categories share the base URL `https://mcp.opus.com`. Append `/v1/mcp/{category}`:

| Category | URL | What it does |
| - | - | - |
| `build` | `https://mcp.opus.com/v1/mcp/build` | Find, read, edit, and test workflows. |
| `discover` | `https://mcp.opus.com/v1/mcp/discover` | Find, read, and edit business processes. |
| `admin` | `https://mcp.opus.com/v1/mcp/admin` | Organization settings: workspaces, roles, members, and invites. |

> [!TIP]
>
> Name your client entries after the category, for example `opus-build`, `opus-discover`, and `opus-admin`. The setup guides in this section use those names.

## What Agents Can Do

Each category gives the agent a set of capabilities. The agent can use a capability only when your role has the matching workflow, process, or organization permission. See [Permissions](#permissions).

Every category also includes a few basic tools, so you never need a separate connection for them. They let the agent see which tools your key can use, read Opus guides, check the result of an earlier call, and list your workspaces. The exact tool list depends on your role and can change between releases. To see the current set, ask your agent to list its Opus tools.

### Build

Build can read **and change** workflows.

* Find and read workflows, their versions, nodes, and the checks Opus runs on them.
* See who else has a workflow open, and what changes other people and agents plan on it.
* Search the marketplace for agents, code, and human tasks, connect them to a workspace, and list integrations with their credential status. Credential values never come back.
* Create workflows, and add, change, connect, and remove nodes, including prompts, code, variables, routes, and execution settings. People who have the workflow open see each edit live.
* Archive a workflow and restore an archived one. Build never activates or deactivates a workflow. People do that in the Opus app.
* Start test runs of a whole workflow or of single nodes, read their results, and stop them. Each test run spends credits.

> [!WARNING]
>
> Test runs use your credentials, and integrations act for real. A test that sends an email sends a real email, and stopping a test does not undo steps that already ran.

### Discover

Discover can read **and change** business processes.

* Find and read business processes and their steps, with assignees, approval state, and comments.
* Create draft processes, and add, change, and remove steps. Discover cannot change or remove an approved step.
* Add comments to steps, as new threads or as replies.
* Approve and unapprove steps **as you**. Only the assignee of an assigned step can approve it. Discover does not approve the process itself.

### Admin

Admin can read **and change** organization settings. It acts on people, so review its use with care.

* List organization members, pending invitations, and roles, with the access each role gives.
* Create workspaces and change their name, description, industry, categories, or color. You become the Workspace Admin of a workspace that the agent creates.
* Invite people by email to workspaces, each with a role. Each invited person gets a **real invitation email** and a notification.
* Change members' organization roles, their roles in workspaces they already belong to, and their org unit membership and roles, or remove their workspace access. Admin never adds a member to a new workspace: use an invitation for that. This change can remove access.

## Authentication

The Opus MCP server uses your Opus API key. It does not support OAuth.

**1. Create an API key**

In the Opus app, open **API Keys** (`/app/dashboard/api-keys`) and create a key. Copy it when it is shown.

**2. Send it as a header**

Your MCP client sends the key on every request, in either header:

```text theme={null}
x-service-key: <your_api_key>
```

```text theme={null}
Authorization: Bearer <your_api_key>
```

Keep these points in mind:

* **Keys belong to a user.** The agent acts as the user who created the key, in that user's organization.
* **Keys belong to a deployment.** A key works only on the deployment that issued it. A key used on another deployment's MCP URL returns `401`.
* **Keep keys out of config files where you can.** Where a client supports environment variable references, store the key in an environment variable such as `OPUS_API_KEY` and reference it from the config, so the key stays out of the file. Each client guide notes where the key is stored.

> [!NOTE]
>
> Your API key is a unique, secret credential. Store it securely, never commit it to version control, and never expose it in client-side code.

## Permissions

The server applies the same role-based access as the Opus app:

* `tools/list` returns only the tools your role allows. A tool you cannot use does not appear in your client.
* If an agent calls a tool your role does not allow, the call returns a tool error with `code: "permission_denied"` and names the required permission.

To get access to more tools, ask an organization or workspace admin to change your role.

## Transport

The server speaks MCP over **Streamable HTTP** and is stateless:

* Requests use `POST` only. With a valid key, `GET` and `DELETE` return `405`, so clients that use the older SSE transport cannot connect. Without a valid key, every request returns `401` first.
* A `POST` to `/v1/mcp` without a category returns `400` with the list of categories.

## Connect Your Client

> [card] [Claude Code](https://developer.opus.com/mcp/claude-code.md)
>
> Add Opus with one `claude mcp add` command per category

> [card] [Claude Desktop](https://developer.opus.com/mcp/claude-desktop.md)
>
> Use a custom connector or a local config file

> [card] [VS Code](https://developer.opus.com/mcp/vscode.md)
>
> Configure Copilot agent mode with a secure key prompt

> [card] [Other Clients](https://developer.opus.com/mcp/other-clients.md)
>
> Codex, Cursor, Gemini CLI, and any Streamable HTTP client

> [card] [Troubleshooting](https://developer.opus.com/mcp/troubleshooting.md)
>
> Fix connection, authentication, and permission errors


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.