@octavus/docs 2.21.0 → 3.1.0

package/content/04-protocol/13-mcp-servers.md

@@ -97,7 +97,7 @@ A server defined as `figma:` that exposes `get_design_context` produces:
 
 - `figma__get_design_context`
 
-The namespace is stripped before calling the MCP server — the server receives the original tool name. This convention matches Anthropic's MCP integration in Claude Desktop and ensures tool names stay unique across servers.
+The namespace is stripped before calling the MCP server - the server receives the original tool name. This convention matches Anthropic's MCP integration in Claude Desktop and ensures tool names stay unique across servers.
 
 ### What the LLM Sees
 
@@ -122,7 +122,7 @@ Device MCP tools (auto-discovered):
   filesystem__list_directory
 ```
 
-You don't define individual MCP tool schemas in the protocol — they're auto-discovered from each MCP server at runtime.
+You don't define individual MCP tool schemas in the protocol - they're auto-discovered from each MCP server at runtime.
 
 ## Remote MCP Servers
 
@@ -145,7 +145,7 @@ Remote MCP servers support multiple authentication methods:
 | Bearer    | Bearer token authentication     |
 | None      | No authentication required      |
 
-Authentication is configured per-project — different projects can connect to the same MCP server with different credentials.
+Authentication is configured per-project - different projects can connect to the same MCP server with different credentials.
 
 ## Device MCP Servers
 
@@ -199,11 +199,68 @@ handlers:
       system: research-prompt
 ```
 
-This thread can use Figma and browser tools, but not sentry or filesystem — even if those are available on the main agent.
+This thread can use Figma and browser tools, but not sentry or filesystem - even if those are available on the main agent.
+
+## On-Demand MCP Servers
+
+By default, an agent can only call MCP tools whose namespace is listed in `mcpServers`. With `onDemandMcpServers`, a scope can opt into **every connected MCP of a given source** at runtime, without enumerating each one in the protocol.
+
+Remote MCPs are connected at the project level from the Octavus dashboard. Normally, each connected MCP that the agent should be able to use has to be declared in the protocol - connecting a new MCP means editing the protocol and redeploying. `onDemandMcpServers` removes that round-trip: once a source is opted in, any MCP connected to the project under that source becomes available to the agent immediately.
+
+Currently supported for `source: remote`.
+
+### Protocol-level declaration
+
+Add an `onDemandMcpServers:` section alongside `mcpServers:`, keyed by source. Each entry configures how the matched MCPs appear in tool lists:
+
+```yaml
+mcpServers:
+  figma:
+    description: Figma design tool integration
+    source: remote
+    display: description
+
+onDemandMcpServers:
+  remote:
+    description: Additional connected integrations
+    display: name
+    contextRetention:
+      toolResults: { retainLast: 5 }
+```
+
+### Scope-level opt-in
+
+The agent and individual `start-thread` blocks each choose whether to pick up on-demand MCPs, by listing the sources they want:
+
+```yaml
+agent:
+  mcpServers: [figma]
+  onDemandMcpServers: [remote]
+
+handlers:
+  user-message:
+    focused:
+      block: start-thread
+      mcpServers: [figma]
+      # no onDemandMcpServers - this thread does NOT see on-demand MCPs
+    broad:
+      block: start-thread
+      mcpServers: [figma]
+      onDemandMcpServers: [remote]
+```
+
+### Rules
+
+- A scope's tool list includes every **connected** MCP of any referenced source, whether or not any protocol declares that slug.
+- Undeclared namespaces inherit `description`, `display`, and `contextRetention` from the per-source entry in `onDemandMcpServers`.
+- Scopes decide independently - threads do not inherit `onDemandMcpServers` from their parent, the same rule as `mcpServers:`.
+- Tool namespaces are always the connector's slug (for example `notion__search`, `linear__create_issue`). Source keys are never namespaces.
+
+Workers opt into on-demand MCPs the same way: through `start-thread` blocks inside `steps`. A worker without a `start-thread` that lists a source won't see on-demand MCPs of that source.
 
 ## Workers
 
-Workers can declare and use MCP servers using the same `mcpServers:` syntax. Workers resolve their own MCP connections independently — they don't inherit from a parent interactive agent.
+Workers can declare and use MCP servers using the same `mcpServers:` syntax. Workers resolve their own MCP connections independently - they don't inherit from a parent interactive agent.
 
 ```yaml
 # Worker protocol
@@ -227,7 +284,7 @@ steps:
     maxSteps: 10
 ```
 
-Since workers don't have a global `agent:` section, MCP servers are scoped per-thread via `start-thread` — the same way tools and skills work in workers. Remote MCP connections are project-scoped, so workers in the same project share the same OAuth connections.
+Since workers don't have a global `agent:` section, MCP servers are scoped per-thread via `start-thread` - the same way tools and skills work in workers. Remote MCP connections are project-scoped, so workers in the same project share the same OAuth connections.
 
 See [Workers](/docs/protocol/workers) for the full worker protocol reference.
 

package/content/05-api-reference/02-sessions.md

@@ -35,7 +35,7 @@ POST /api/agent-sessions
 | `agentId` | string | Yes      | Agent ID (the `id` field, not `slug`) |
 | `input`   | object | No       | Input variables for the agent         |
 
-> **Getting the agent ID:** Copy the ID from the agent URL in the [platform](https://octavus.ai) (e.g., `octavus.ai/platform/agents/clxyz123`), or use the [CLI](/docs/server-sdk/cli) (`octavus sync ./agents/my-agent`) for local development workflows.
+> **Getting the agent ID:** Copy the ID from the agent URL in the [platform](https://octavus.ai) (e.g., `octavus.ai/projects/.../agents/clxyz123`), or use the [CLI](/docs/server-sdk/cli) (`octavus sync ./agents/my-agent`) for local development workflows.
 
 ### Response
 
@@ -216,7 +216,7 @@ curl -X POST https://octavus.ai/api/agent-sessions/:sessionId/restore \
 
 Clear session state, transitioning it to `expired` status. The session can be restored afterwards with the [Restore Session](#restore-session) endpoint.
 
-This is idempotent — clearing an already expired session succeeds without error.
+This is idempotent - clearing an already expired session succeeds without error.
 
 ```
 DELETE /api/agent-sessions/:sessionId

package/content/06-examples/02-nextjs-chat.md

@@ -354,6 +354,6 @@ Tool handlers receive the parameters as `args`:
 
 ## Next Steps
 
-- [Protocol Overview](/docs/protocol/overview) — Define agent behavior
-- [Messages](/docs/client-sdk/messages) — Rich message rendering
-- [Streaming](/docs/client-sdk/streaming) — Advanced streaming UI
+- [Protocol Overview](/docs/protocol/overview) - Define agent behavior
+- [Messages](/docs/client-sdk/messages) - Rich message rendering
+- [Streaming](/docs/client-sdk/streaming) - Advanced streaming UI

package/content/06-examples/03-socket-chat.md

@@ -404,6 +404,6 @@ const SockJS: typeof import('sockjs-client') = require('sockjs-client');
 
 ## Next Steps
 
-- [Socket Transport](/docs/client-sdk/socket-transport) — Advanced socket patterns
-- [Protocol Overview](/docs/protocol/overview) — Define agent behavior
-- [Tools](/docs/protocol/tools) — Building tool handlers
+- [Socket Transport](/docs/client-sdk/socket-transport) - Advanced socket patterns
+- [Protocol Overview](/docs/protocol/overview) - Define agent behavior
+- [Tools](/docs/protocol/tools) - Building tool handlers