Skip to main content

Work with your agents from Cursor or Claude Code with the MCP server

Connect Cursor, Claude Code, or any MCP client to Octavus to give your agents work, read their threads, and manage skills without leaving your editor.

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:

text
https://octavus.ai/mcp

When 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:

json
{
  "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:

bash
claude mcp add --transport http octavus https://octavus.ai/mcp

Any 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:

LevelWhat the connection can do
Read-onlyRead 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 writeEverything 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

ToolAccessWhat it does
list_workforce_agentsreadList the agents you can access, with each one's id, name, role, and department
list_workforce_threadsreadList an agent's threads, newest first, with status and timestamps
read_workforce_threadreadRead 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_agentwriteSend a message to an agent, starting a new thread or continuing one
cancel_workforce_threadwriteStop 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:

  1. send_to_workforce_agent with the agent's id and your message. It returns a threadId right away.
  2. read_workforce_thread with that threadId and wait: true. The wait is bounded: if the run is still going, the result says isRunning: 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

ToolAccessWhat it does
list_skillsreadList the skills available to your organization: your custom skills and the public Octavus skills
get_skillreadRead a skill in full: its SKILL.md and its scripts, references, and assets
save_skillwriteCreate or update one of your organization's custom skills
delete_skillwriteArchive 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

ToolAccessWhat it does
list_modelsreadList 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 seeWhat it means
The sign-in page says your account is not part of an organizationFinish 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 expectClients cache the tool list when they connect. Refresh the server in your client, or disconnect and reconnect.
Your tool reports an authorization errorThe connection was disconnected, or your password changed. Connect again.
read_workforce_thread keeps returning isRunning: trueThe 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 refusedYour role cannot manage skills in this organization. Ask an owner.