The Octavus MCP server connects your Octavus account to an AI coding tool, such as Cursor or Claude Code, through the Model Context Protocol. Once connected, your tool can list your Octavus Agents, give one of them a task and read its reply, follow and stop its threads, and read or author your organization's skills, all from your editor. It is a remote server: there is nothing to install and no process to run. You point your client at one URL and sign in with your Octavus account.
You need:
- An Octavus account that belongs to an organization. The connection acts as you, in that organization, with what you can see and do there.
- An MCP client that supports remote servers over Streamable HTTP with OAuth sign-in. Cursor and Claude Code both do.
Connect
The server's URL is:
https://octavus.ai/mcpWhen your client connects for the first time, your browser opens Octavus, you sign in if you are not already, and you choose an access level. After you approve, the client is connected.
Cursor
Add the server to your Cursor MCP configuration, ~/.cursor/mcp.json for every project or .cursor/mcp.json in one project:
{
"mcpServers": {
"octavus": {
"url": "https://octavus.ai/mcp"
}
}
}Cursor asks you to sign in the first time it uses the server.
Claude Code
Add the server from the command line, then complete the sign-in when prompted:
claude mcp add --transport http octavus https://octavus.ai/mcpAny other client
Point the client at https://octavus.ai/mcp as a Streamable HTTP server with OAuth. The server supports OAuth 2.1 discovery and dynamic client registration, so there is no client ID or secret to configure.
Choose an access level
At sign-in you choose one of two levels, and it is bound to the connection:
| Level | What the connection can do |
|---|---|
| Read-only | Read your skills and follow your Octavus Agents: list them, list their threads, read a thread. No changes. The write tools are not even offered to your tool. |
| Read and write | Everything read-only allows, plus sending messages to your agents, stopping their runs, and creating or updating your organization's custom skills. |
To change the level, disconnect the client (see Manage connections) and connect again.
What your tool can do
Your agents
| Tool | Access | What it does |
|---|---|---|
list_workforce_agents | read | List the agents you can access, with each one's id, name, role, and department |
list_workforce_threads | read | List an agent's threads, newest first, with status and timestamps |
read_workforce_thread | read | Read a thread's messages and status, as the dashboard shows them. With wait: true it waits up to about 25 seconds for the run to finish |
send_to_workforce_agent | write | Send a message to an agent, starting a new thread or continuing one |
cancel_workforce_thread | write | Stop a thread's run, like the Stop button in the dashboard |
Agent runs take a while, so giving an agent work is two steps, which your tool handles on its own once you ask it:
send_to_workforce_agentwith the agent's id and your message. It returns athreadIdright away.read_workforce_threadwith thatthreadIdandwait: true. The wait is bounded: if the run is still going, the result saysisRunning: true, and the tool calls again until the run finishes.
For example, in Cursor or Claude Code: "Ask Anna to draft the follow-up email for the Acme deal and show me what she wrote." Your tool lists your agents to find Anna, sends her the task, waits for the thread, and shows you her reply.
Skills
| Tool | Access | What it does |
|---|---|---|
list_skills | read | List the skills available to your organization: your custom skills and the public Octavus skills |
get_skill | read | Read a skill in full: its SKILL.md and its scripts, references, and assets |
save_skill | write | Create or update one of your organization's custom skills |
delete_skill | write | Archive one of your custom skills |
Writing a skill needs an account that can manage skills in your organization. A skill can declare the secrets it needs, but their values are set in the dashboard, never through the MCP server. To write a new skill, read an existing one with get_skill first as a worked example of the format.
Models
| Tool | Access | What it does |
|---|---|---|
list_models | read | List the models an agent can use, with the copy-ready id, provider, context length, and pricing: the same catalog as octavus.ai/pricing/models |
Manage connections
Every connected client is listed under Account -> Connected apps in the dashboard, with its access level and when it was last used. Disconnect one there, or all of them: a disconnected client fails on its next request and has to connect again to regain access. Changing your password disconnects every client the same way. A connection that goes unused for 180 days lapses on its own.
Verify
Ask your tool to list your Octavus Agents. It should answer with the agents you see in the dashboard. On a read-and-write connection, ask it to send one of them a short message and read the reply, then find that thread on the agent in the dashboard.
Troubleshooting
| What you see | What it means |
|---|---|
| The sign-in page says your account is not part of an organization | Finish setting up your account in Octavus, then connect again. |
| "This connection is read-only" | The connection was approved as read-only. Disconnect it under Account -> Connected apps and connect again with read and write. |
| Your tool does not list a tool you expect | Clients cache the tool list when they connect. Refresh the server in your client, or disconnect and reconnect. |
| Your tool reports an authorization error | The connection was disconnected, or your password changed. Connect again. |
read_workforce_thread keeps returning isRunning: true | The agent is still working; full runs can take several minutes. Keep calling with wait: true, or follow the thread in the dashboard. |
| A skill write is refused | Your role cannot manage skills in this organization. Ask an owner. |