@octavus/docs 3.0.0 → 3.2.0

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

@@ -38,6 +38,7 @@ mcpServers:
 | `description` | Yes      | What the MCP server provides                                                          |
 | `source`      | Yes      | `remote` (platform-managed) or `device` (consumer-provided)                           |
 | `display`     | No       | How tool calls appear in UI: `hidden`, `name`, `description` (default: `description`) |
+| `connection`  | No       | When to connect: `eager` or `lazy` (default: `lazy`). Remote only.                    |
 
 ### Display Modes
 
@@ -97,7 +98,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 +123,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
 
@@ -134,6 +135,34 @@ Configuration happens in the Octavus platform UI:
 2. The server's slug must match the namespace in your protocol
 3. The platform connects, discovers tools, and makes them available to the agent
 
+### Connection Modes
+
+The `connection` field controls when the platform connects to a remote MCP server:
+
+| Mode    | Behavior                                                                                                               |
+| ------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `lazy`  | (default) The agent activates integrations on demand at runtime. The agent starts responding immediately.              |
+| `eager` | The platform connects and discovers tools before the first LLM request. Tools are guaranteed available from message 1. |
+
+```yaml
+mcpServers:
+  sentry:
+    source: remote
+    connection: eager # Always connected upfront
+    display: name
+
+  notion:
+    source: remote
+    # connection defaults to lazy - agent activates when needed
+    display: description
+```
+
+With **lazy connection** (the default), the agent receives two built-in tools - one for listing available integrations and one for activating them. The agent decides which integrations it needs based on the conversation and activates them on demand. This avoids paying connection latency for integrations the agent doesn't end up using.
+
+With **eager connection**, the platform connects to the MCP server before the first LLM request, exactly like a declared tool. Use this when the agent needs the MCP's tools from the very first message.
+
+The `connection` field is only valid on `source: remote` - device MCPs have their own connection mechanism through the server-sdk.
+
 ### Authentication
 
 Remote MCP servers support multiple authentication methods:
@@ -145,7 +174,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 +228,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 +313,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.
 
@@ -238,6 +324,7 @@ mcpServers:
   figma:
     description: Figma design tool integration
     source: remote
+    connection: eager
     display: description
   sentry:
     description: Error tracking and debugging
@@ -298,10 +385,12 @@ mcpServers:
   figma:
     description: Figma design tool integration
     source: remote
+    connection: eager # Need design tools from message 1
     display: description
   sentry:
     description: Error tracking and debugging
     source: remote
+    # Lazy (default) - agent activates when debugging is needed
     display: name
 
 tools:

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