Agent Registration

Registration via the Agent API

Use the Octopus Management API to add an external MCP server to an agent. The mcpServers array on the agent record holds one entry per external server.

// POST /api/agents
{
  "name":        "Zendesk Support Agent",
  "description": "Handles customer support tickets via Zendesk.",
  "systemPrompt": "You are a support specialist. Use the Zendesk tools to " +
                  "create, update, and search support tickets on behalf of users.",
  "llmModel":    "gpt-4o",
  "mcpServers": [
    {
      "name":         "zendesk",
      "baseUrl":      "https://mcp-zendesk.internal",
      "credentialId": 55,
      "timeoutMs":    30000,
      "enabled":      true
    }
  ]
}

mcpServers Registration Fields

Tool Discovery Lifecycle

1. Agent starts up (or is refreshed via the API)
2. Octopus calls GET {baseUrl}/tools with the resolved Bearer token
3. Discovered tools are merged into the agent's tool registry alongside built-in plugin tools
4. If toolFilter is set, only the listed tool names are registered
5. On each agent conversation turn, the merged tool list is sent to the LLM as function definitions
6. When the LLM calls an external tool, Octopus routes the call to POST {baseUrl}/tool/{name}/call

Filtering Tools from a Server

If your MCP server exposes 20 tools but a particular agent only needs 3, use toolFilter to limit what the LLM sees. This reduces prompt token usage and prevents agents from calling tools outside their intended scope.

{
  "mcpServers": [
    {
      "name":         "zendesk",
      "baseUrl":      "https://mcp-zendesk.internal",
      "credentialId": 55,
      "toolFilter": [
        "zendesk_create_ticket",
        "zendesk_search_tickets"
      ]
    }
  ]
}

Registering Multiple External Servers

An agent can connect to multiple MCP servers simultaneously. Tool names must be unique across all registered servers — Octopus rejects registrations that produce naming conflicts.

{
  "mcpServers": [
    {
      "name":         "zendesk",
      "baseUrl":      "https://mcp-zendesk.internal",
      "credentialId": 55
    },
    {
      "name":         "jira",
      "baseUrl":      "https://mcp-jira.internal",
      "credentialId": 56
    },
    {
      "name":         "slack",
      "baseUrl":      "https://mcp-slack.internal",
      "credentialId": 57
    }
  ]
}

Updating Server Registration

To update a server's URL, credential, or timeout — PATCH the agent with the updated mcpServers array. Octopus will re-discover tools from the updated configuration on the next agent turn.

// PATCH /api/agents/{agentId}
{
  "mcpServers": [
    {
      "name":         "zendesk",
      "baseUrl":      "https://mcp-zendesk-v2.internal",  // updated URL
      "credentialId": 58,                                   // new credential
      "timeoutMs":    45000
    }
  ]
}

Tool Discovery Errors